1 Introduction to cmake and ninja
2 ===============================
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.
8 - For a decent-sized project - such as vpp - build performance is drastically better with (cmake, ninja).
10 - The cmake input language looks like an actual language, rather than a shell scripting scheme on steroids.
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.
14 See the `cmake website <http://cmake.org>`_, and the `ninja website
15 <https://ninja-build.org>`_ for additional information.
17 vpp cmake configuration files
18 -----------------------------
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.
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
26 - Build target lists come from CMakeLists.txt files found in subdirectories, which are named in the SUBDIRS list in .../src/CMakeLists.txt
30 ##############################################################################
31 # subdirs - order matters
32 ##############################################################################
33 if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux")
34 find_package(OpenSSL REQUIRED)
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")
41 message(FATAL_ERROR "Unsupported system: ${CMAKE_SYSTEM_NAME}")
44 foreach(DIR ${SUBDIRS})
45 add_subdirectory(${DIR})
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
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
61 get_filename_component(dir ${f} DIRECTORY)
62 add_subdirectory(${dir})
65 How to write a plugin CMakeLists.txt file
66 -----------------------------------------
68 It's really quite simple. Follow the pattern:
72 add_vpp_plugin(mactime
88 Adding a target elsewhere in the source tree
89 --------------------------------------------
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.
97 Here's how we build the g2 event data visualization tool:
101 option(VPP_BUILD_G2 "Build g2 tool." OFF)
103 find_package(GTK2 COMPONENTS gtk)
105 include_directories(${GTK2_INCLUDE_DIRS})
106 add_vpp_executable(g2
118 LINK_LIBRARIES vppinfra Threads::Threads m ${GTK2_LIBRARIES}
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.]
127 When invoking cmake manually [rarely done and not very easy], specify
132 $ cmake ... -DVPP_BUILD_G2=ON
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.
139 That would work, of course, but it's not a particularly elegant solution.
141 Tinkering with build options: ccmake
142 ------------------------------------
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
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
152 Here's approximately what you'll see:
156 CCACHE_FOUND /usr/bin/ccache
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
168 VPP_API_TEST_BUILTIN ON
170 VPP_BUILD_PERFTOOL OFF
171 VPP_BUILD_VCL_TESTS ON
172 VPP_BUILD_VPPINFRA_TESTS OFF
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)
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.
183 At that point "make build" or "make build-release" will build g2. And so on.
185 Note that toggling advanced mode ["t"] gives access to substantially
186 all of the cmake option, discovered directories and paths.