ament_cmake user documentation

ament_cmake is the build system for CMake based packages in ROS 2 (in particular, it will be used for most C/C++ projects). It is a set of scripts enhancing CMake and adding convenience functionality for package authors. Before using ament_cmake, it is very helpful to know the basics of CMake. An official tutorial can be found here.

Basics 

A basic CMake outline can be produced using ros2 pkg create <package_name> on the command line. The build information is then gathered in two files: the package.xml and the CMakeLists.txt, which must be in the same directory. The package.xml must contain all dependencies and a bit of metadata to allow colcon to find the correct build order for your packages, to install the required dependencies in CI, and to provide the information for a release with bloom. The CMakeLists.txt contains the commands to build and package executables and libraries and will be the main focus of this document.

Basic project outline 

The basic outline of the CMakeLists.txt of an ament package contains:

cmake_minimum_required(VERSION 3.8)
project(my_project)

ament_package()

The argument to project will be the package name and must be identical to the package name in the package.xml.

The project setup is done by ament_package() and this call must occur exactly once per package. ament_package() installs the package.xml, registers the package with the ament index, and installs configuration (and possibly target) files for CMake so that it can be found by other packages using find_package. Since ament_package() gathers a lot of information from the CMakeLists.txt it should be the last call in your CMakeLists.txt.

ament_package can be given additional arguments:

CONFIG_EXTRAS: a list of CMake files (.cmake or .cmake.in templates expanded by configure_file()) which should be available to clients of the package. For an example of when to use these arguments, see the discussion in Adding resources. For more information on how to use template files, see the official documentation.
CONFIG_EXTRAS_POST: same as CONFIG_EXTRAS, but the order in which the files are added differs. While CONFIG_EXTRAS files are included before the files generated for the ament_export_* calls the files from CONFIG_EXTRAS_POST are included afterwards.

Instead of adding to ament_package, you can also add to the variable ${PROJECT_NAME}_CONFIG_EXTRAS and ${PROJECT_NAME}_CONFIG_EXTRAS_POST with the same effect. The only difference is again the order in which the files are added with the following total order:

files added by CONFIG_EXTRAS
files added by appending to ${PROJECT_NAME}_CONFIG_EXTRAS
files added by appending to ${PROJECT_NAME}_CONFIG_EXTRAS_POST
files added by CONFIG_EXTRAS_POST

Compiler and linker options 

ROS 2 targets compilers which comply with the C++17 and C99 standard. Newer versions might be targeted in the future and are referenced here. Therefore it is customary to set the corresponding CMake flags:

if(NOT CMAKE_C_STANDARD)
  set(CMAKE_C_STANDARD 99)
endif()
if(NOT CMAKE_CXX_STANDARD)
  set(CMAKE_CXX_STANDARD 17)
endif()

To keep the code clean, compilers should throw warnings for questionable code and these warnings should be fixed.

It is recommended to at least cover the following warning levels:

For Visual Studio: the default W1 warnings
For GCC and Clang: -Wall -Wextra -Wpedantic are highly recommended and -Wshadow is advisable

It is currently recommended to use add_compile_options to add these options for all targets. This avoids cluttering the code with target-based compile options for all executables, libraries, and tests:

if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
  add_compile_options(-Wall -Wextra -Wpedantic)
endif()

Finding dependencies 

Most ament_cmake projects will have dependencies on other packages. In CMake, this is accomplished by calling find_package. For instance, if your package depends on rclcpp, then the CMakeLists.txt file should contain:

find_package(rclcpp REQUIRED)

Note

It should never be necessary to find_package a library that is not explicitly needed but is a dependency of another dependency that is explicitly needed. If that is the case, file a bug against the corresponding package.

Adding targets 

In CMake nomenclature, targets are the artifacts that this project will create. Either libraries or executables can be created, and a single project can contain zero or many of each of them.

These are created with a call to add_library, which should contain both the name of the target and the source files that should be compiled to create the library.

With the separation of header files and implementation in C/C++, it is not usually necessary to add header files as arguments to add_library.

The following best practice is proposed:

Put all headers which should be usable by clients of this library (and therefore must be installed) into a subdirectory of the include folder named like the package, while all other files (.c/.cpp and header files which should not be exported) are inside the src folder
Only .c/.cpp files are explicitly referenced in the call to add_library
Find headers to your library my_library via

target_include_directories(my_library
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
    "$<INSTALL_INTERFACE:include/${PROJECT_NAME}>")

This adds all files in the folder ${CMAKE_CURRENT_SOURCE_DIR}/include to the public interface during build time and all files in the include folder (relative to ${CMAKE_INSTALL_DIR}) when being installed.

ros2 pkg create creates a package layout that follows these rules.

Note

Since Windows is one of the officially supported platforms, to have maximum impact, any package should also build on Windows. The Windows library format enforces symbol visibility; that is, every symbol which should be used from a client has to be explicitly exported by the library (and symbols need to be implicitly imported).

Since GCC and Clang builds do not generally do this, it is advised to use the logic in the GCC wiki. To use it for a package called my_library:

Copy the logic in the link into a header file called visibility_control.hpp.
Replace DLL by MY_LIBRARY (for an example, see visibility control of rviz_rendering).
Use the macros “MY_LIBRARY_PUBLIC” for all symbols you need to export (i.e. classes or functions).

In the project CMakeLists.txt use:

target_compile_definitions(my_library PRIVATE "MY_LIBRARY_BUILDING_LIBRARY")

For more details, see Windows Symbol Visibility in the Windows Tips and Tricks document.

These should be created with a call to add_executable, which should contain both the name of the target and the source files that should be compiled to create the executable. The executable may also have to be linked with any libraries created in this package by using target_link_libraries.

Since executables aren’t generally used by clients as a library, no header files need to be put in the include directory.

In the case that a package has both libraries and executables, make sure to combine the advice from both “Libraries” and “Executables” above.

Linking to dependencies 

There are two ways to link your targets against a dependency.

The first and recommended way is to use the ament macro ament_target_dependencies. As an example, suppose we want to link my_library against the linear algebra library Eigen3.

find_package(Eigen3 REQUIRED)
ament_target_dependencies(my_library PUBLIC Eigen3)

It includes the necessary headers and libraries and their dependencies to be correctly found by the project.

The second way is to use target_link_libraries.

Modern CMake prefers to use only targets, exporting and linking against them. CMake targets may be namespaced, similar to C++. Prefer to use the namespaced targets if they are available. For instance, Eigen3 defines the target Eigen3::Eigen.

In the example of Eigen3, the call should then look like

target_link_libraries(my_library PUBLIC Eigen3::Eigen)

This will also include necessary headers, libraries and their dependencies. Note that this dependency must have been previously discovered via a call to find_package.

Installing 

When building a reusable library, some information needs to be exported for downstream packages to easily use it.

First, install the headers files which should be available to clients. The include directory is custom to support overlays in colcon; see https://colcon.readthedocs.io/en/released/user/overriding-packages.html#install-headers-to-a-unique-include-directory for more information.

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

Next, install the targets and create the export target (export_${PROJECT_NAME}) that other code will use to find this package. Note that you can use a single install call to install all of the libraries in the project.

install(
  TARGETS my_library
  EXPORT export_${PROJECT_NAME}
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
  RUNTIME DESTINATION bin
)

ament_export_targets(export_${PROJECT_NAME} HAS_LIBRARY_TARGET)
ament_export_dependencies(some_dependency)

Here is what’s happening in the snippet above:

The ament_export_targets macro exports the targets for CMake. This is necessary to allow your library’s clients to use the target_link_libraries(client PRIVATE my_library::my_library) syntax. If the export set includes a library, add the option HAS_LIBRARY_TARGET to ament_export_targets, which adds potential libraries to environment variables.
The ament_export_dependencies exports dependencies to downstream packages. This is necessary so that the user of the library does not have to call find_package for those dependencies, too.

Warning

Calling ament_export_targets, ament_export_dependencies, or other ament commands from a CMake subdirectory will not work as expected. This is because the CMake subdirectory has no way of setting necessary variables in the parent scope where ament_package is called.

Note

Windows DLLs are treated as runtime artifacts and installed into the RUNTIME DESTINATION folder. It is therefore advised to keep the RUNTIME install even when developing libraries on Unix based systems.

The EXPORT notation of the install call requires additional attention: It installs the CMake files for the my_library target. It must be named exactly the same as the argument in ament_export_targets. To ensure that it can be used via ament_target_dependencies, it should not be named exactly the same as the library name, but instead should have a prefix like export_ (as shown above).
All install paths are relative to CMAKE_INSTALL_PREFIX, which is already set correctly by colcon/ament.

There are two additional functions which are available, but are superfluous for target based installs:

ament_export_include_directories("include/${PROJECT_NAME}")
ament_export_libraries(my_library)

The first macro marks the directory of the exported include directories. The second macro marks the location of the installed library (this is done by the HAS_LIBRARY_TARGET argument in the call to ament_export_targets). These should only be used if the downstream projects can’t or don’t want to use CMake target based dependencies.

Some of the macros can take different types of arguments for non-target exports, but since the recommended way for modern Make is to use targets, we will not cover them here. Documentation of these options can be found in the source code itself.

When installing an executable, the following stanza must be followed exactly for the rest of the ROS tooling to find it:

install(TARGETS my_exe
    DESTINATION lib/${PROJECT_NAME})

In the case that a package has both libraries and executables, make sure to combine the advice from both “Libraries” and “Executables” above.

Linting and Testing 

In order to separate testing from building the library with colcon, wrap all calls to linters and tests in a conditional:

if(BUILD_TESTING)
  find_package(ament_cmake_gtest REQUIRED)
  ament_add_gtest(<tests>)
endif()

Linting 

It’s advised to use the combined call from ament_lint_auto:

find_package(ament_lint_auto REQUIRED)
ament_lint_auto_find_test_dependencies()

This will run linters as defined in the package.xml. It is recommended to use the set of linters defined by the package ament_lint_common. The individual linters included there, as well as their functions, can be seen in the ament_lint_common docs.

Linters provided by ament can also be added separately, instead of running ament_lint_auto. One example of how to do so can be found in the ament_cmake_lint_cmake documentation.

Testing 

Ament contains CMake macros to simplify setting up GTests. Call:

find_package(ament_cmake_gtest)
ament_add_gtest(some_test <test_sources>)

to add a GTest. This is then a regular target which can be linked against other libraries (such as the project library). The macros have additional parameters:

APPEND_ENV: append environment variables. For instance you can add to the ament prefix path by calling:

find_package(ament_cmake_gtest REQUIRED)
ament_add_gtest(some_test <test_sources>
  APPEND_ENV PATH=some/addtional/path/for/testing/resources)

APPEND_LIBRARY_DIRS: append libraries so that they can be found by the linker at runtime. This can be achieved by setting environment variables like PATH on Windows and LD_LIBRARY_PATH on Linux, but this makes the call platform specific.
ENV: set environment variables (same syntax as APPEND_ENV).
TIMEOUT: set a test timeout in second. The default for GTests is 60 seconds. For example:

ament_add_gtest(some_test <test_sources> TIMEOUT 120)

SKIP_TEST: skip this test (will be shown as “passed” in the console output).
SKIP_LINKING_MAIN_LIBRARIES: Don’t link against GTest.
WORKING_DIRECTORY: set the working directory for the test.

The default working directory otherwise is the CMAKE_CURRENT_BINARY_DIR, which is described in the CMake documentation.

Similarly, there is a CMake macro to set up GTest including GMock:

find_package(ament_cmake_gmock REQUIRED)
ament_add_gmock(some_test <test_sources>)

It has the same additional parameters as ament_add_gtest.

Extending ament 

It is possible to register additional macros/functions with ament_cmake and extend it in several ways.

Adding a function/macro to ament 

Extending ament will often times mean that you want to have some functions available to other packages. The best way to provide the macro to client packages is to register it with ament.

This can be done by appending the ${PROJECT_NAME}_CONFIG_EXTRAS variable, which is used by ament_package() via

list(APPEND ${PROJECT_NAME}_CONFIG_EXTRAS
  path/to/file.cmake"
  other/pathto/file.cmake"
)

Alternatively, you can directly add the files to the ament_package() call:

ament_package(CONFIG_EXTRAS
  path/to/file.cmake
  other/pathto/file.cmake
)

Adding to extension points 

In addition to simple files with functions that can be used in other packages, you can also add extensions to ament. Those extensions are scripts which are executed with the function which defines the extension point. The most common use-case for ament extensions is probably registering rosidl message generators: When writing a generator, you normally want to generate all messages and services with your generator also without modifying the code for the message/service definition packages. This is possible by registering the generator as an extension to rosidl_generate_interfaces.

As an example, see

ament_register_extension(
  "rosidl_generate_interfaces"
  "rosidl_generator_cpp"
  "rosidl_generator_cpp_generate_interfaces.cmake")

which registers the macro rosidl_generator_cpp_generate_interfaces.cmake for the package rosidl_generator_cpp to the extension point rosidl_generate_interfaces. When the extension point gets executed, this will trigger the execution of the script rosidl_generator_cpp_generate_interfaces.cmake here. In particular, this will call the generator whenever the function rosidl_generate_interfaces gets executed.

The most important extension point for generators, aside from rosidl_generate_interfaces, is ament_package, which will simply execute scripts with the ament_package() call. This extension point is useful when registering resources (see below).

ament_register_extension is a function which takes exactly three arguments:

extension_point: The name of the extension point (most of the time this will be one of ament_package or rosidl_generate_interfaces)
package_name: The name of the package containing the CMake file (i.e. the project name of the project where the file is written to)
cmake_filename: The CMake file executed when the extension point is run

Note

It is possible to define custom extension points in a similar manner to ament_package and rosidl_generate_interfaces, but this should hardly be necessary.

Adding extension points 

Very rarely, it might be interesting to define a new extension point to ament.

Extension points can be registered within a macro so that all extensions will be executed when the corresponding macro is called. To do so:

Define and document a name for your extension (e.g. my_extension_point), which is the name passed to the ament_register_extension macro when using the extension point.
In the macro/function which should execute the extensions call:

ament_execute_extensions(my_extension_point)

Ament extensions work by defining a variable containing the name of the extension point and filling it with the macros to be executed. Upon calling ament_execute_extensions, the scripts defined in the variable are then executed one after another.

Adding resources 

Especially when developing plugins or packages which allow plugins it is often essential to add resources to one ROS package from another (e.g. a plugin). Examples can be plugins for tools using the pluginlib.

This can be achieved using the ament index (also called “resource index”).

The ament index explained 

For details on the design and intentions, see here

In principle, the ament index is contained in a folder within the install/share folder of your package. It contains shallow subfolders named after different types of resources. Within the subfolder, each package providing said resource is referenced by name with a “marker file”. The file may contain whatever content necessary to obtain the resources, e.g. relative paths to the installation directories of the resource, it may also be simply empty.

To give an example, consider providing display plugins for RViz: When providing RViz plugins in a project named my_rviz_displays which will be read by the pluginlib, you will provide a plugin_description.xml file, which will be installed and used by the pluginlib to load the plugins. To achieve this, the plugin_description.xml is registered as a resource in the resource_index via

pluginlib_export_plugin_description_file(rviz_common plugins_description.xml)

When running colcon build, this installs a file my_rviz_displays into a subfolder rviz_common__pluginlib__plugin into the resource_index. Pluginlib factories within rviz_common will know to gather information from all folders named rviz_common__pluginlib__plugin for packages that export plugins. The marker file for pluginlib factories contains an install-folder relative path to the plugins_description.xml file (and the name of the library as marker file name). With this information, the pluginlib can load the library and know which plugins to load from the plugin_description.xml file.

As a second example, consider the possibility to let your own RViz plugins use your own custom meshes. Meshes get loaded at startup time so that the plugin owner does not have to deal with it, but this implies RViz has to know about the meshes. To achieve this, RViz provides a function:

register_rviz_ogre_media_exports(DIRECTORIES <my_dirs>)

This registers the directories as an ogre_media resource in the ament index. In short, it installs a file named after the project which calls the function into a subfolder called rviz_ogre_media_exports. The file contains the install folder relative paths to the directories listed in the macros. On startup time, RViz can now search for all folders called rviz_ogre_media_exports and load resources in all folders provided. These searches are done using ament_index_cpp (or ament_index_py for Python packages).

In the following sections we will explore how to add your own resources to the ament index and provide best practices for doing so.

Querying the ament index 

If necessary, it is possible to query the ament index for resources via CMake. To do so, there are three functions:

ament_index_has_resource: Obtain a prefix path to the resource if it exists with the following parameters:

var: the output parameter: fill this variable with FALSE if the resource does not exist or the prefix path to the resource otherwise
resource_type: The type of the resource (e.g. rviz_common__pluginlib__plugin)
resource_name: The name of the resource which usually amounts to the name of the package having added the resource of type resource_type (e.g. rviz_default_plugins)

ament_index_get_resource: Obtain the content of a specific resource, i.e. the contents of the marker file in the ament index.

var: the output parameter: filled with the content of the resource marker file if it exists.
resource_type: The type of the resource (e.g. rviz_common__pluginlib__plugin)
resource_name: The name of the resource which usually amounts to the name of the package having added the resource of type resource_type (e.g. rviz_default_plugins)
PREFIX_PATH: The prefix path to search for (usually, the default ament_index_get_prefix_path() will be enough).

Note that ament_index_get_resource will throw an error if the resource does not exist, so it might be necessary to check using ament_index_has_resource.

ament_index_get_resources: Get all packages which registered resources of a specific type from the index

var: Output parameter: filled with a list of names of all packages which registered a resource of resource_type
resource_type: The type of the resource (e.g. rviz_common__pluginlib__plugin)
PREFIX_PATH: The prefix path to search for (usually, the default ament_index_get_prefix_path() will be enough).

Adding to the ament index 

Defining a resource requires two bits of information:

a name for the resource which must be unique,
a layout of the marker file, which can be anything and could also be empty (this is true for instance for the “package” resource marking a ROS 2 package)

For the RViz mesh resource, the corresponding choices were:

rviz_ogre_media_exports as name of the resource,
install path relative paths to all folders containing resources. This will already enable you to write the logic for using the corresponding resource in your package.

To allow users to easily register resources for your package, you should furthermore provide macros or functions such as the pluginlib function or rviz_ogre_media_exports function.

To register a resource, use the ament function ament_index_register_resource. This will create and install the marker files in the resource_index. As an example, the corresponding call for rviz_ogre_media_exports is the following:

ament_index_register_resource(rviz_ogre_media_exports CONTENT ${OGRE_MEDIA_RESOURCE_FILE})

This installs a file named like ${PROJECT_NAME} into a folder rviz_ogre_media_exports into the resource_index with content given by variable ${OGRE_MEDIA_RESOURCE_FILE}. The macro has a number of parameters that can be useful:

the first (unnamed) parameter is the name of the resource, which amounts to the name of the folder in the resource_index
CONTENT: The content of the marker file as string. This could be a list of relative paths, etc. CONTENT cannot be used together with CONTENT_FILE.
CONTENT_FILE: The path to a file which will be use to create the marker file. The file can be a plain file or a template file expanded with configure_file(). CONTENT_FILE cannot be used together with CONTENT.
PACKAGE_NAME: The name of the package/library exporting the resource, which amounts to the name of the marker file. Defaults to ${PROJECT_NAME}.
AMENT_INDEX_BINARY_DIR: The base path of the generated ament index. Unless really necessary, always use the default ${CMAKE_BINARY_DIR}/ament_cmake_index.
SKIP_INSTALL: Skip installing the marker file.

Since only one marker file exists per package, it is usually a problem if the CMake function/macro gets called twice by the same project. However, for large projects it might be best to split up calls registering resources.

Therefore, it is best practice to let a macro registering a resource such as register_rviz_ogre_media_exports.cmake only fill some variables. The real call to ament_index_register_resource can then be added within an ament extension to ament_package. Since there must only ever be one call to ament_package per project, there will always only be one place where the resource gets registered. In the case of rviz_ogre_media_exports this amounts to the following strategy:

The macro register_rviz_ogre_media_exports takes a list of folders and appends them to a variable called OGRE_MEDIA_RESOURCE_FILE.
Another macro called register_rviz_ogre_media_exports_hook calls ament_index_register_resource if ${OGRE_MEDIA_RESOURCE_FILE} is non-empty.
The register_rviz_ogre_media_exports_hook.cmake file is registered as an ament extension in a third file register_rviz_ogre_media_exports_hook-extras.cmake via calling

ament_register_extension("ament_package" "rviz_rendering"
  "register_rviz_ogre_media_exports_hook.cmake")

The files register_rviz_ogre_media_exports.cmake and register_rviz_ogre_media_exports_hook-extra.cmake are registered as CONFIG_EXTRA with ament_package().