DOC ONLY: cmake / ninja build system doc

Change-Id: I69cdcf3f0940f8a5f60203034688a0c63446f65c
Signed-off-by: Dave Barach <dave@barachs.net>

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