CMake Basics

1. Non-trivial C++ projects require the use of multiple source files and libraries that all must be combined together
   • Libraries may be located in different locations on different people's computers
   • People may want to use different compilers with different types of compiler options
   • People may want to customize your program by selecting different options at compile time
   • You may want someone to be able to run their code on a different operating system (not us) or even a computer with a different system architecture system (definitely us)
2. There are also a large number of options that affect the behavior of the compiler that need to be managed
3. Without a build tools, you would have to manually enter the commands to compile the program
   • And not just you, everyone who wants to use your code

4.The ideal of a working project is to have your code be able to compile and do all setup related steps in a single command

• Computers are good at automating repetitive and tedious tasks!

• While there is no mandated file layout, there are common best practices.
• the below structure is an example for a project called project_name.
• The project creates a library called mylibrary and an executable called Name.

project_name
├── CMakeLists.txt
├── include
│   └── mylibrary
│       └── header.hpp
├── src
│   ├── libfile1.cpp
│   ├── libfile2.cpp
│   └── Name_main.cpp
└── tests
    └── mytest.cpp

1. All CMake projects have a CMakeLists.txt in the base directory.
   • This file is the primary file used to setup the build system.
2. CMakeLists.txt is responsible for:
   • Finding build dependencies of the project.
   • Determining compile options.
   • Determining what files must be compiled to create the libraries and executables produced by the project.
   • Providing instructions for how to install the libraries and executables.
3. The include/mylibrary directory is there so that every project using the library can include headers by doing #include"mylibrary/header.hpp"
   • The project is setup to search for include files in include/. The directory structure means that the files themselves are under mylibrary/header.hpp
4. The tests directory holds the unit tests
5. Overall, as the project becomes more complex you may add more directories
   • In this example, we keep all .cpp files under src but other projects could do it differently by, for example, splitting the locations of library .cpp files and executable .cpp files

1. Below is a template for CMakeLists.txt as well as comments describing each aspect

   # Lines that begin with a # are comments
   # set the minimum required version of cmake, usually the first line
   cmake_minimum_required(VERSION 3.22)
   
   # project_name sets the name of the project and causes cmake to
   # find the c and c++ compilers
   project(project_name)
   
   # Find your dependencies.
   # Many libraries ship with files that allow CMake to find them
   # Then general behavior is to call "find_package" but the options
   # provided are package specific.  Usually there is then a CMAKE variable
   # That is defined to reference the library
   # here: we find the eigen library as per the instruction
   # https://eigen.tuxfamily.org/dox/TopicCMakeGuide.html
   find_package(Eigen3 3.3 REQUIRED NO_MODULE)
   
   # Create a library.  Can specify if it is shared or static but usually
   # you don't need or want to.
   # name is the name of the library without the extension or lib prefix
   # name creates a cmake "target"
   add_library(libname src/libfile1.cpp src/libfile2.cpp)
   
   # Use target_include_directories so that #include"mylibrary/header.hpp" works
   # The use of the <BUILD_INTERFACE> and <INSTALL_INTERFACE> is because when
   # Using the library from the build directory or after installation
   # During build, the headers are read from the source code directory
   # When used from the installed location, headers are in the
   # system include/ directory
   target_include_directories(libname
       PUBLIC
       $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/>
       $<INSTALL_INTERFACE:include/>)
   
   # specify additional compilation flags for the library
   # Public causes the flags to propagate to anything
   # that links against this library
   target_compile_options(libname PUBLIC -Wall -Wextra -pedantic)
   
   # Enable c++17 support.
   # Public causes the features to propagate to anything
   # that links against this library
   target_compile_features(libname PUBLIC cxx_std_17)
   
   # Create an executable from the following source code files
   # The Name of the executable creates a cmake "target"
   add_executable(Name src/Name_main.cpp)
   
   # Use target_link_libraries to add dependencies to a "target"
   # (e.g., a library or executable)
   # This will automatically add all required library files
   # that need to be linked
   # and paths to th locations of header files
   target_link_libraries(Name Eigen3::Eigen libname)
   
   # install the include files by copying the whole include directory
   install(DIRECTORY include/mylibrary DESTINATION include)
   
   # Create a CMake Exported Target containing the lib and exe.
   # Also create CMake Export called projet_name-targets
   # The CMake Export contains files that allow other CMake projects
   # to find this project. It must be installed separately.
   install(TARGETS Name libname EXPORT project_name-targets)
   
   # The project_name-targets created by install(TARGETS) needs to be installed.
   # install(EXPORT ...) will generate a file called project_name-config.cmake
   # that contains the exported targets.
   # After installation this file will then be found when calling
   # find_package(project_name) from another cmake project
   # A user can then target_link_libraries(target project_name::library)
   # to use the libraries installed here
   install(EXPORT project_name-targets
           FILE project_name-config.cmake
           NAMESPACE project_name::
           DESTINATION lib/cmake/${PROJECT_NAME})
   

2. After writing a CMakeLists.txt configure the project and build it.

   cmake -B build .
   cmake --build build
   

3. The above commands are equivalent to the following:

   mkdir build
   cd build
   cmake ..
   make
   

CMake has the ability to generate doxygen documentation automatically during the build

find_package(Doxygen)

# Building documentation should be optional.
# To build documentation pass -DBUILD_DOCS=ON when generating the build system
option(BUILD_DOCS "Build the documentation" OFF)

# build just because Doxygen is missing
if(${DOXYGEN_FOUND} AND ${BUILD_DOCS})
    # Turn the README.md into the homepage of the doxygen docs
    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)

    # Tell Doxygen where to find the documentation
    doxygen_add_docs(doxygen include/ src/ README.md ALL)

    # The documentation will be in the build/html directory
    # The main page is build/html/index.html
endif()

CMake provides a framework for calling unit tests called CTest that enables coordinating tests with the build system in a testing-framework agnostic manner

include(CTest)

# CTest sets BUILD_TESTING to on. To disable tests add -DBUILD_TESTING=OFF when invoking cmake
if(BUILD_TESTING)
    # Find the Unit testing framework. In this example, Catch2
    find_package(Catch2 3 REQUIRED)

    # A test is just an executable that is linked against the unit testing library
    add_executable(my_test_exe tests/mytest.cpp)
    target_link_libraries(my_test_exe Catch2::Catch2WithMain AnyOtherLibrariesAsNeeded)

    # register the test with CTest, telling it what executable to run
    add_test(NAME the_test_name COMMAND my_test_exe)
endif()

To run the tests, enter the build/ directory and run ctest --verbose.

• If a library that you write had dependencies, sometimes the users of your library will also need these dependencies.
• In this case, you can provide a custom project_name-config.cmake file that automatically finds the required dependencies when find_package is called.
• Rather than making the exports file the project_name-config.cmake that is run when find_package is called, We instead install the exports file as project_name-targets.cmake. We then create and install a custom file that finds the dependencies and then includes the exports file.

• Here is an example CMakeLists.txt snippet.

  install(DIRECTORY include/mylibrary DESTINATION include)
  
  install(TARGETS Name libname EXPORT project_name-targets)
  
  install(EXPORT project_name-targets
           FILE project_name-targets.cmake
           NAMESPACE project_name::
           DESTINATION lib/cmake/${PROJECT_NAME})
  
  configure_file(project_name-config.cmake.in project_name-config.cmake @ONLY)
  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/project_name-config.cmake
          DESTINATION lib/cmake/${PROJECT_NAME})
  

• The install(EXPORT) now creates a file called project_name-targets.cmake which contains the exported targets

• You now provide a file called project_name-config.cmake.in with the following contents

  # You can access variables from CMake by using the
  # @var_name@ syntax. These variables will be replaced with there value
  # from the current CMake session (useful for configuration)
  include(CMakeFindDependencyMacro)
  find_dependency(a_dep_your_library_needs REQUIRED)
  
  # Once all dependencies are found, include the exported targets
  # We expect that the project_name-targets.cmake file is installed
  # next to project_name-config.cmake (this file)
  include(${CMAKE_CURRENT_LIST_DIR}/project_name-targets.cmake)
  

• Notice that we created a build directory outside our source directory
  • This is known as an out-of-source build.
  • It is recommended to do out-of-source builds to avoid scattering a bunch of files generated by CMake everywhere in your source tree (a .gitignore nightmare!)
  • It is possible to invoke cmake in the same directory as the source code, which makes a mess

  • I use the following code to prevent me from accidently doing that

    if(${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR})
        message(FATAL_ERROR
        "No in source builds allowed. Create a separate build directory.
        SOURCE_DIR=${CMAKE_SOURCE_DIR}  BINARY_DIR=${CMAKE_BINARY_DIR} ")
    endif()
    

• You can set cmake variables when invoking cmake.
  • Usually you want to cmake -DCMAKE_BUILD_TYPE=<Type> where <Type> is:
    • Debug - compile with debugging options enabled (-g for gcc)
    • Release - compile with optimizations enables (-O3 for gcc)
    • There are other release types as well
  • If you don't specify a build type you get no additional compile flags

  • I typically use the following code to have the build type default to Debug if not otherwise specified

    if(NOT CMAKE_BUILD_TYPE)        # If no build type is set, set one
      set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Type of build." FORCE)
    endif()
    

• Since cmake generates Makefiles, you do not typically need to rerun cmake.
  • Even if you modify CMakeLists.txt, the Makefiles will invoke CMake automatically
• When debugging CMake problems, it can sometimes be helpful to completely delete the contents of the build directory and regenerate everything from scratch

generation

Since CMake is a build-system generator (we are using make as the build system), it is generating build files.

• This means that you are actually using CMake Code to Generate Makefile Code to Compile C++ Code

target

This is anything that will ultimately be created by the build system

• For example: executables and libraries
• When generating Makefiles, targets correspond to makefile targets
  • For example if you add_executable(hello myworld.cpp) then hello is a target and it can be built specifically by using make hello

properties

various entities in CMake have properties that can be set

• For targets, you can set properties using functions that begin with target_set
  • target_set_include_directories(targetname list_of_directories_where_include_files_are_found)
  • target_set_compile_options()
  • target_link_libraries(target lib1target lib2target) a bit of a misnomer (it should really be called target_link_target) this will not only link libraries lib1target and lib2target into target but also add their include paths and some other options to target For example, if lib1target has include files in /home/user/include, targetname will be able to include those files as well.
    1. Directory vs Local
       • CMake commands starting with add (such as add_compile_options generally apply to all CMake files in the current directory or any sub directories. (They technically set properties on these directories)
       • CMake commands starting with target apply only to the target that is specified. They can optionally be transferred to other targets using target_link_libraries

       • Modern CMake Best practices favor using target level properties

         • Allows finer control
         • Passing on these options to dependencies with target_link_libraries means that when executable target_a depends on library_X which depends on library_Y which

         depends on library_Z, target_a is compiled with all the necessary include file paths and library paths just by doing target_link_libraries(target_a library_X)

1. ${VARIABLE} gets the value of a variable. This is a direct-string replacement
   • In most project, you want to avoid variables in CMake as much as possible and instead list files directly
2. Functions in cmake can have a type of named argument, usually in capital letters. So for example message(FATAL_ERROR "The value of VARIABLE is ${VARIABLE}") will cause a fatal cmake error and print The value of VARIABLE is <variable value here>. (this is a decent cmake debugging technique. message(WARNING "The value of VARIABLE is ${VARIABLE}")~ will just print a warning

• If you ever get an error about find_package could not find X then this likely means you are missing a dependency
  • If you are lucky, that package might be available for Ubuntu and you can install it
  • If using ROS2, you can use rosdep install --from-paths src --ignore-src -r -y to install all dependencies of all packages in the source space
• You may occasionally encounter C++ packages that are not ROS packages and are not distributed with Ubuntu, meaning that you will need to compile them yourself
• Due to the popularity of CMake, there is a good chance that this project will be using CMake as it's build system
• By specifying -DCMAKE_PREFIX_PATH=/home/user/location_where_to_install and -DCMAKE_INSTALL_PREFIX=/home/user/location_where_to_install you are able to
  • Compile the package(s) you want
  • Install it to the location you want (-DCMAKE_INSTALL_PREFIX tells CMake to treat the specified path as the base location for all installations rather than the default (which is /) without needing root privileges or affecting the rest of your system
  • Use the installed package in other CMake packages (-DCMAKE_PREFIX_PATH tells CMake to treat the specified directory as if it were / when looking for files)

In CMake you can set options for the compilation both globally and on a per-target level.

• The advantage of setting options globally is that they are used for all targets and can be changed in one place.
• The advantage of setting options locally is that you can use different options for different targets. Additionally, the options can be passed on to targets that depend on the existing target.
• There is some debate about whether setting compiler options and flags globally or locally is best. The CMake community (in my view) favors the local approach, whereas ROS favors the global approach.

Setting the C++ standard has its own syntax in CMake. This is because every compiler has different options, but CMake is cross-platform and provides a common standard-setting method across all compilers.

• In advanced usage, CMake can compute the standard needed, given particular language features that are desired.

• ament makes it easier to install libraries than standard cmake

• After creating the libraries call

  ament_export_targets(my_library-targets HAS_LIBRARY_TARGET)
  ament_export_dependencies(dependency_of_library)
  install(DIRECTORY include/ DESTINATION include)
  install(TARGETS my_library EXPORT my_library-targets)
  

• See Ament Guide for more information

• Preamble, same as a normal

  # minimum cmake Version 3.9, rather outdated
  cmake_minimum_required(VERSION 3.9)
  
  # name of project, must match package.xml
  project(my_project)
  

• Notice that catkin is found just like any other package would be (because a main component of catkin is a cmake code)

• The COMPONENTS part is because catkin sets everythign up so that ROS packages can be brought in as if they were a piece of the catkin cmake package

  find_package(catkin REQUIRED COMPONENTS roscpp)
  

• Next, find other packages that are non-ros, just as you would in a regular cmake file

  find_package(Boost REQUIRED COMPONENTS system)
  

• For ROS messages, services, etc to work, C++/python files encapsulating those messages must be created at compile time (that is, when you run make). These functions are provided by catkin to build the messages files into python and C++ code. This part

  add_message_files()
  add_service_files()
  add_action_files()
  generate_messages()
  generate_dynamic_reconfigure_options()
  

• catkin_package is used to let other packages know how to use your package as a dependency

  ## INCLUDE_DIRS: use if package contains header files
  ## LIBRARIES: libraries created here that dependent projects need
  ## CATKIN_DEPENDS: catkin_packages dependent projects need
  ## DEPENDS: system dependencies of this project that dependent projects also need
  catkin_package(
  #  INCLUDE_DIRS include
  #  LIBRARIES tmp
  #  CATKIN_DEPENDS other_catkin_pkg
  #  DEPENDS system_lib
  )
  

  • The INCLUDE_DIRS is where your package's header files are stored. This let's other catkin packages use these header files
  • The LIBRARIES are for anything you created with add_library that you want other catkin_packages to be able to use
  • The CATKIN_DEPENDS is for any catkin package (added to the find_package(catkin REQUIRED COMPONENTS ...) line that packages that use your project need
  • The DEPENDS line is for any non-catkin package (found via find_package) that a project that uses your project needs

• Rather than using target_include_directories on individual targets, catkin sets include directories that are used by all targets in your package globally. The ${catkin_INCLUDE_DIRS} variable is populated with directories set in catkin_package in all of the packages found by find_package(catkin REQUIRED COMPONENTS)

  include_directories(
  include
   ${catkin_INCLUDE_DIRS}
  )
  

• Targets (i.e., libraries and executables) are added as usual
• Target names are always prefixed by ${PROJECT_NAME} to avoid name conflicts.
  • ${PROJECT_NAME} is a CMAKE variable that is filled in by the call to project() at the beginning of the file
  • catkin_make actually turns all the packages in your workspace into a single giant cmake package, and a single package can't have duplicate target names
  • If you force the users to use either catkin_make_isolated or catkin_tools this usage is unnecessary
• In the model presented here, the library name is the same as the catkin_package name. Many times there is a 1-1 correspondance between a C++ library and a ROS package, but there need not be.

• If setting flags and standards globally, you would use target_compile_features and target_compile_options

  add_library(${PROJECT_NAME} src/${PROJECT_NAME}/tmp.cpp)
  target_compile_features(${PROJECT_NAME} PUBLIC cxx_std_17)
  target_compile_options(${PROJECT_NAME} -Wall -Wextra)
  

• This line says that your library (called ${PROJECT_NAME}) depends on (i.e., will be compiled after) all the targets (i.e., libraries) that the current package exports (via catkin_package) and targets required by anything found with find_package(catkin REQUIRED COMPONENTS).

• It also ensures that any messages/services that are required are built first

  add_dependencies(${PROJECT_NAME} ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
  

• Adding an executable (e.g., a node) is similar to adding a library, but includes a few extra lines.
• I recommend grouping these lines together for all nodes that you add
• The CMake target name is prefixed with ${PROJECT_NAME} to avoid conflicts with other packages.
• The actual name of the node is changed to remove with ${PROJECT_NAME} prefix with set_target_properties
• The node is made to depend on all the imported catkin packages and libraries so it is compiled after them.

• The executable is also linked against any libraries that were exported by the catkin_packages we have included, and any other non-catkin libraries we need

  add_executable(${PROJECT_NAME}_node src/tmp_node.cpp)
  set_target_properties(${PROJECT_NAME}_node PROPERTIES OUTPUT_NAME node PREFIX "")
  add_dependencies(${PROJECT_NAME}_node ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})
  target_link_libraries(${PROJECT_NAME}_node ${catkin_LIBRARIES})
  

• Add libraries from system dependencies (i.e., those found with find_package(Library)) to target_link_libraries
• Add local compile options and features with target_compile_features and target_compile_options
• The installation phase is usually not used during development but becomes important if, for example, you wanted to created a binary version of your package so other people could use it without needing to compile your code.

• To install python scripts, cmake copies them from the source directory to an installation directory

  install(PROGRAMS
  scripts/my_python_script
  DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
  )
  

• To install your nodes list them on the line below:

  install(TARGETS ${PROJECT_NAME}_node
    RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
  )
  

• To install libraries list them below

  install(TARGETS ${PROJECT_NAME}
    ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
    LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
    RUNTIME DESTINATION ${CATKIN_GLOBAL_BIN_DESTINATION}
  )
  

• The header files for your library must also be explicitly installed.

• The version in catkin_pkg only copies files with a .h extension. I remove this restriction as its unnecessary and I end C++ headers with .hpp

  install(DIRECTORY include/${PROJECT_NAME}/
    DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION}
  )