diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/gettingstarted/developers/buildsystem/cmakeandninja.rst | 184 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/buildsystem/index.rst | 5 |
2 files changed, 188 insertions, 1 deletions
diff --git a/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst b/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst new file mode 100644 index 00000000000..86638beb088 --- /dev/null +++ b/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst @@ -0,0 +1,184 @@ +Introduction to cmake and ninja +=============================== + +Cmake plus ninja is approximately equal to GNU autotools plus GNU +make, respectively. Both cmake and GNU autotools support self and +cross-compilation, checking for required components and versions. + +- For a decent-sized project - such as vpp - build performance is drastically better with (cmake, ninja). + +- The cmake input language looks like an actual language, rather than a shell scripting scheme on steroids. + +- Ninja doesn't pretend to support manually-generated input files. Think of it as a fast, dumb robot which eats mildly legible byte-code. + +See the `cmake website <http://cmake.org>`_, and the `ninja website +<https://ninja-build.org>`_ for additional information. + +vpp cmake configuration files +----------------------------- + +The top of the vpp project cmake hierarchy lives in .../src/CMakeLists.txt. +This file defines the vpp project, and (recursively) includes two kinds +of files: rule/function definitions, and target lists. + +- 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 + +- Build target lists come from CMakeLists.txt files found in subdirectories, which are named in the SUBDIRS list in .../src/CMakeLists.txt + +:: + + ############################################################################## + # subdirs - order matters + ############################################################################## + if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux") + find_package(OpenSSL REQUIRED) + set(SUBDIRS + vppinfra svm vlib vlibmemory vlibapi vnet vpp vat vcl plugins + vpp-api tools/vppapigen tools/g2 tools/elftool tools/perftool) + elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin") + set(SUBDIRS vppinfra) + else() + message(FATAL_ERROR "Unsupported system: ${CMAKE_SYSTEM_NAME}") + endif() + + foreach(DIR ${SUBDIRS}) + add_subdirectory(${DIR}) + endforeach() + +- 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 + + +:: + + ############################################################################## + # find and add all plugin subdirs + ############################################################################## + FILE(GLOB files RELATIVE + ${CMAKE_CURRENT_SOURCE_DIR} + ${CMAKE_CURRENT_SOURCE_DIR}/*/CMakeLists.txt + ) + foreach (f ${files}) + get_filename_component(dir ${f} DIRECTORY) + add_subdirectory(${dir}) + endforeach() + +How to write a plugin CMakeLists.txt file +----------------------------------------- + +It's really quite simple. Follow the pattern: + +:: + + add_vpp_plugin(mactime + SOURCES + mactime.c + node.c + + API_FILES + mactime.api + + INSTALL_HEADERS + mactime_all_api_h.h + mactime_msg_enum.h + + API_TEST_SOURCES + mactime_test.c + ) + +Adding a target elsewhere in the source tree +-------------------------------------------- + +Within reason, adding a subdirectory to the SUBDIRS list in +.../src/CMakeLists.txt is perfectly OK. The indicated directory will +need a CMakeLists.txt file. + +Here's how we build the g2 event data visualization tool: + +:: + + option(VPP_BUILD_G2 "Build g2 tool." OFF) + if(VPP_BUILD_G2) + find_package(GTK2 COMPONENTS gtk) + if(GTK2_FOUND) + include_directories(${GTK2_INCLUDE_DIRS}) + add_vpp_executable(g2 + SOURCES + clib.c + cpel.c + events.c + main.c + menu1.c + pointsel.c + props.c + g2version.c + view1.c + + LINK_LIBRARIES vppinfra Threads::Threads m ${GTK2_LIBRARIES} + NO_INSTALL + ) + endif() + endif() + +The g2 component is optional, and is not built by default. There are +a couple of ways to tell cmake to include it in build.ninja [or in Makefile.] + +When invoking cmake manually [rarely done and not very easy], specify +-DVPP_BUILD_G2=ON: + +:: + + $ cmake ... -DVPP_BUILD_G2=ON + +Take a good look at .../build-data/packages/vpp.mk to see where and +how the top-level Makefile and .../build-root/Makefile set all of the +cmake arguments. One strategy to enable an optional component is fairly +obvious. Add -DVPP_BUILD_G2=ON to vpp_cmake_args. + +That would work, of course, but it's not a particularly elegant solution. + +Tinkering with build options: ccmake +------------------------------------ + +The easy way to set VPP_BUILD_G2 - or frankly **any** cmake +parameter - is to install the "cmake-curses-gui" package and use +it. + +- Do a straightforward vpp build using the top level Makefile, "make build" or "make build-release" +- Ajourn to .../build-root/build-vpp-native/vpp or .../build-root/build-vpp_debug-native/vpp +- Invoke "ccmake ." to reconfigure the project as desired + +Here's approximately what you'll see: + +:: + + CCACHE_FOUND /usr/bin/ccache + CMAKE_BUILD_TYPE + CMAKE_INSTALL_PREFIX /scratch/vpp-gate/build-root/install-vpp-nati + DPDK_INCLUDE_DIR /scratch/vpp-gate/build-root/install-vpp-nati + DPDK_LIB /scratch/vpp-gate/build-root/install-vpp-nati + MBEDTLS_INCLUDE_DIR /usr/include + MBEDTLS_LIB1 /usr/lib/x86_64-linux-gnu/libmbedtls.so + MBEDTLS_LIB2 /usr/lib/x86_64-linux-gnu/libmbedx509.so + MBEDTLS_LIB3 /usr/lib/x86_64-linux-gnu/libmbedcrypto.so + MUSDK_INCLUDE_DIR MUSDK_INCLUDE_DIR-NOTFOUND + MUSDK_LIB MUSDK_LIB-NOTFOUND + PRE_DATA_SIZE 128 + VPP_API_TEST_BUILTIN ON + VPP_BUILD_G2 OFF + VPP_BUILD_PERFTOOL OFF + VPP_BUILD_VCL_TESTS ON + VPP_BUILD_VPPINFRA_TESTS OFF + + CCACHE_FOUND: Path to a program. + Press [enter] to edit option Press [d] to delete an entry CMake Version 3.10.2 + Press [c] to configure + Press [h] for help Press [q] to quit without generating + Press [t] to toggle advanced mode (Currently Off) + +Use the cursor to point at the VPP_BUILD_G2 line. Press the return key +to change OFF to ON. Press "c" to regenerate build.ninja, etc. + +At that point "make build" or "make build-release" will build g2. And so on. + +Note that toggling advanced mode ["t"] gives access to substantially +all of the cmake option, discovered directories and paths. diff --git a/docs/gettingstarted/developers/buildsystem/index.rst b/docs/gettingstarted/developers/buildsystem/index.rst index 38ba9724c68..908e91e1fc1 100644 --- a/docs/gettingstarted/developers/buildsystem/index.rst +++ b/docs/gettingstarted/developers/buildsystem/index.rst @@ -3,9 +3,12 @@ Build System ============ -This guide describes the vpp build system in detail. +This guide describes the vpp build system in detail. As of this writing, +the build systems uses a mix of make / Makefiles, cmake, and ninja to +achieve excellent build performance. .. toctree:: mainmakefile + cmakeandninja buildrootmakefile |