# 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 if not all C/C++ projects). It is a set of scripts enhancing CMake and adding convenience functionality for package authors. Knowing the basics of CMake will be very helpful, 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 basic build information is then gathered in two files: the package.xml and the CMakeLists.txt. 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 as well as 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.5)
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 config (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. Although it is possible to follow calls to ament_package() by calls to install functions copying files and directories, it is simpler to just keep ament_package() the last call.

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

There are two main targets to build: libraries and executables which are built by add_library and add_executable respectively.

With the separation of header files and implementation in C/C++, it is not always necessary to add both files as argument to add_library/ add_executable.

The following best practice is proposed:

• if you are building a library, put all headers which should be usable by clients 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 cpp files are explicitly referenced in the call to add_library or add_executable

• allow to find headers via

target_include_directories(my_target
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>

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 aside from rosidl_generate_interfaces for generators 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().