docs/developer/corearchitecture/buildsystem/cmakeandninja.rst

   1 Introduction to cmake and ninja
   2 ===============================
   3
   4 Cmake plus ninja is approximately equal to GNU autotools plus GNU
   5 make, respectively. Both cmake and GNU autotools support self and
   6 cross-compilation, checking for required components and versions.
   7
   8 - For a decent-sized project - such as vpp - build performance is drastically better with (cmake, ninja).
   9
  10 - The cmake input language looks like an actual language, rather than a shell scripting scheme on steroids.
  11
  12 - Ninja doesn't pretend to support manually-generated input files. Think of it as a fast, dumb robot which eats mildly legible byte-code.
  13
  14 See the `cmake website <http://cmake.org>`_, and the `ninja website
  15 <https://ninja-build.org>`_ for additional information.
  16
  17 vpp cmake configuration files
  18 -----------------------------
  19
  20 The top of the vpp project cmake hierarchy lives in .../src/CMakeLists.txt.
  21 This file defines the vpp project, and (recursively) includes two kinds
  22 of files: rule/function definitions, and target lists.
  23
  24 - Rule/function definitions live in .../src/cmake/{\*.cmake}. Although the contents of these files is simple enough to read, it shouldn't be necessary to modify them very often
  25
  26 - Build target lists come from CMakeLists.txt files found in subdirectories, which are named in the SUBDIRS list in .../src/CMakeLists.txt
  27
  28 ::
  29
  30     ##############################################################################
  31     # subdirs - order matters
  32     ##############################################################################
  33     if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux")
  34       find_package(OpenSSL REQUIRED)
  35       set(SUBDIRS
  36         vppinfra svm vlib vlibmemory vlibapi vnet vpp vat vcl plugins
  37         vpp-api tools/vppapigen tools/g2 tools/perftool)
  38     elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
  39       set(SUBDIRS vppinfra)
  40     else()
  41       message(FATAL_ERROR "Unsupported system: ${CMAKE_SYSTEM_NAME}")
  42     endif()
  43
  44     foreach(DIR ${SUBDIRS})
  45       add_subdirectory(${DIR})
  46     endforeach()
  47
  48 - The vpp cmake configuration hierarchy discovers the list of plugins to be built by searching for subdirectories in .../src/plugins which contain CMakeLists.txt files
  49
  50
  51 ::
  52
  53     ##############################################################################
  54     # find and add all plugin subdirs
  55     ##############################################################################
  56     FILE(GLOB files RELATIVE
  57       ${CMAKE_CURRENT_SOURCE_DIR}
  58       ${CMAKE_CURRENT_SOURCE_DIR}/*/CMakeLists.txt
  59     )
  60     foreach (f ${files})
  61       get_filename_component(dir ${f} DIRECTORY)
  62       add_subdirectory(${dir})
  63     endforeach()
  64
  65 How to write a plugin CMakeLists.txt file
  66 -----------------------------------------
  67
  68 It's really quite simple. Follow the pattern:
  69
  70 ::
  71
  72     add_vpp_plugin(mactime
  73       SOURCES
  74       mactime.c
  75       node.c
  76
  77       API_FILES
  78       mactime.api
  79
  80       INSTALL_HEADERS
  81       mactime_all_api_h.h
  82       mactime_msg_enum.h
  83
  84       API_TEST_SOURCES
  85       mactime_test.c
  86     )
  87
  88 Adding a target elsewhere in the source tree
  89 --------------------------------------------
  90
  91 Within reason, adding a subdirectory to the SUBDIRS list in
  92 .../src/CMakeLists.txt is perfectly OK. The indicated directory will
  93 need a CMakeLists.txt file.
  94
  95 .. _building-g2:
  96
  97 Here's how we build the g2 event data visualization tool:
  98
  99 ::
 100
 101     option(VPP_BUILD_G2 "Build g2 tool." OFF)
 102     if(VPP_BUILD_G2)
 103       find_package(GTK2 COMPONENTS gtk)
 104       if(GTK2_FOUND)
 105         include_directories(${GTK2_INCLUDE_DIRS})
 106         add_vpp_executable(g2
 107           SOURCES
 108           clib.c
 109           cpel.c
 110           events.c
 111           main.c
 112           menu1.c
 113           pointsel.c
 114           props.c
 115           g2version.c
 116           view1.c
 117
 118           LINK_LIBRARIES vppinfra Threads::Threads m ${GTK2_LIBRARIES}
 119           NO_INSTALL
 120         )
 121       endif()
 122     endif()
 123
 124 The g2 component is optional, and is not built by default. There are
 125 a couple of ways to tell cmake to include it in build.ninja [or in Makefile.]
 126
 127 When invoking cmake manually [rarely done and not very easy], specify
 128 -DVPP_BUILD_G2=ON:
 129
 130 ::
 131
 132    $ cmake ... -DVPP_BUILD_G2=ON
 133
 134 Take a good look at .../build-data/packages/vpp.mk to see where and
 135 how the top-level Makefile and .../build-root/Makefile set all of the
 136 cmake arguments. One strategy to enable an optional component is fairly
 137 obvious. Add -DVPP_BUILD_G2=ON to vpp_cmake_args.
 138
 139 That would work, of course, but it's not a particularly elegant solution.
 140
 141 Tinkering with build options: ccmake
 142 ------------------------------------
 143
 144 The easy way to set VPP_BUILD_G2 - or frankly **any** cmake
 145 parameter - is to install the "cmake-curses-gui" package and use
 146 it.
 147
 148 - Do a straightforward vpp build using the top level Makefile, "make build" or "make build-release"
 149 - Ajourn to .../build-root/build-vpp-native/vpp or .../build-root/build-vpp_debug-native/vpp
 150 - Invoke "ccmake ." to reconfigure the project as desired
 151
 152 Here's approximately what you'll see:
 153
 154 ::
 155
 156      CCACHE_FOUND                     /usr/bin/ccache
 157      CMAKE_BUILD_TYPE
 158      CMAKE_INSTALL_PREFIX             /scratch/vpp-gate/build-root/install-vpp-nati
 159      DPDK_INCLUDE_DIR                 /scratch/vpp-gate/build-root/install-vpp-nati
 160      DPDK_LIB                         /scratch/vpp-gate/build-root/install-vpp-nati
 161      MBEDTLS_INCLUDE_DIR              /usr/include
 162      MBEDTLS_LIB1                     /usr/lib/x86_64-linux-gnu/libmbedtls.so
 163      MBEDTLS_LIB2                     /usr/lib/x86_64-linux-gnu/libmbedx509.so
 164      MBEDTLS_LIB3                     /usr/lib/x86_64-linux-gnu/libmbedcrypto.so
 165      MUSDK_INCLUDE_DIR                MUSDK_INCLUDE_DIR-NOTFOUND
 166      MUSDK_LIB                        MUSDK_LIB-NOTFOUND
 167      PRE_DATA_SIZE                    128
 168      VPP_API_TEST_BUILTIN             ON
 169      VPP_BUILD_G2                     OFF
 170      VPP_BUILD_PERFTOOL               OFF
 171      VPP_BUILD_VCL_TESTS              ON
 172      VPP_BUILD_VPPINFRA_TESTS         OFF
 173
 174     CCACHE_FOUND: Path to a program.
 175     Press [enter] to edit option Press [d] to delete an entry   CMake Version 3.10.2
 176     Press [c] to configure
 177     Press [h] for help           Press [q] to quit without generating
 178     Press [t] to toggle advanced mode (Currently Off)
 179
 180 Use the cursor to point at the VPP_BUILD_G2 line. Press the return key
 181 to change OFF to ON. Press "c" to regenerate build.ninja, etc.
 182
 183 At that point "make build" or "make build-release" will build g2. And so on.
 184
 185 Note that toggling advanced mode ["t"] gives access to substantially
 186 all of the cmake option, discovered directories and paths.