You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Iron.
About the build system
Under everything is the build system.
catkin from ROS 1, we have created a set of packages under the moniker
Some of the reasons for changing the name to
ament are that we wanted it to not collide with
catkin (in case we want to mix them at some point) and to prevent confusion with existing
ament’s primary responsibility is to make it easier to develop and maintain ROS 2 core packages.
However, this responsibility extends to any user who is willing to make use of our build system conventions and tools.
Additionally it should make packages conventional, such that developers should be able to pick up any
ament based package and make some assumptions about how it works, how to introspect it, and how to build or use it.
ament consists of a few important repositories which are all in the
ament GitHub organization:
Located on GitHub at ament/ament_package, this repository contains a single ament Python package that provides various utilities for ament packages, e.g. templates for environment hooks.
All ament packages must contain a single package.xml file at the root of the package regardless of their underlying build system. The package.xml “manifest” file contains information that is required in order to process and operate on a package. This package information includes things like the package’s name, which is globally unique, and the package’s dependencies. The package.xml file also serves as the marker file which indicates the location of the package on the file system.
Parsing of the package.xml files is provided by
catkin_pkg (as in ROS 1), while functionality to locate packages by searching the file system for these package.xml files is provided by build tools such as
Package manifest file which marks the root of a package and contains meta information about the package including its name, version, description, maintainer, license, dependencies, and more. The contents of the manifest are in machine readable XML format and the contents are described in the REPs 127 and 140, with the possibility of further modifications in future REPs.
So anytime some package is referred to as an ament package, it means that it is a single unit of software (source code, build files, tests, documentation, and other resources) which is described using a package.xml manifest file.
- ament package
Any package which contains a package.xml and follows the packaging guidelines of
ament, regardless of the underlying build system.
Since the term ament package is build system agnostic, there can be different kinds of ament packages, e.g. ament CMake package, ament Python package, etc.
Here is a list of common package types that you might run into in this software stack:
- CMake package
Any package containing a plain CMake project and a package.xml manifest file.
- ament CMake package
A CMake package that also follows the
- Python package
Any package containing a setuptools based Python project and a package.xml manifest file.
- ament Python package
A Python package that also follows the
Located on GitHub at ament/ament_cmake, this repository contains many “ament CMake” and pure CMake packages which provide the infrastructure in CMake that is required to create “ament CMake” packages.
In this context “ament CMake” packages means:
ament packages that are built using CMake.
So the packages in this repository provide the necessary CMake functions/macros and CMake Modules to facilitate creating more “ament CMake” (or
Packages of this type are identified with the
<build_type>ament_cmake</build_type> tag in the
<export> tag of the package.xml file.
The packages in this repository are extremely modular, but there is a single “bottleneck” package called
Anyone can depend on the
ament_cmake package to get all of the aggregate functionality of the packages in this repository.
Here a list of the packages in the repository along with a short description:
aggregates all other packages in this repository, users need only to depend on this
provides convenience CMake functions which automatically handle a lot of the tedious parts of writing a package’s
provides all built-in core concepts for
ament, e.g. environment hooks, resource indexing, symbolic linking install and others
adds convenience functions for making gmock based unit tests
adds convenience functions for making gtest based automated tests
adds convenience functions for making nosetests based python automated tests
provides CMake functions for packages that contain Python code
aggregates different kinds of tests, e.g. gtest and nosetests, under a single target using CTest
ament_cmake_core package contains a lot of the CMake infrastructure that makes it possible to cleanly pass information between packages using conventional interfaces.
This makes the packages have more decoupled build interfaces with other packages, promoting their reuse and encouraging conventions in the build systems of different packages.
For instance, it provides a standard way to pass include directories, libraries, definitions, and dependencies between packages so that consumers of this information can access this information in a conventional way.
ament_cmake_core package also provides features of the
ament build system like symbolic link installation, which allows you to symbolically link files from either the source space or the build space into the install space rather than copying them.
This allows you to install once and then edit non-generated resources like Python code and configuration files without having to rerun the install step for them to take effect.
This feature essentially replaces the “devel space” from
catkin because it has most of the advantages with few of the complications or drawbacks.
Another feature provided by
ament_cmake_core is the package resource indexing which is a way for packages to indicate that they contain a resource of some type.
The design of this feature makes it much more efficient to answer simple questions like what packages are in this prefix (e.g.
/usr/local) because it only requires that you list the files in a single possible location under that prefix.
You can read more about this feature in the design docs for the resource index.
ament_cmake_core also provides environment setup files and package specific environment hooks.
The environment setup files, often named something like
setup.bash, are a place for package developers to define changes to the environment that are needed to utilize their package.
The developers are able to do this using an “environment hook” which is basically an arbitrary bit of shell code that can set or modify environment variables, define shell functions, setup auto-completion rules, etc…
This feature is how, for example, ROS 1 set the
ROS_DISTRO environment variable without
catkin knowing anything about the ROS distribution.
Located on GitHub at ament/ament_lint, this repository provides several packages which provide linting and testing services in a convenient and consistent manner.
Currently there are packages to support C++ style linting using
uncrustify, static C++ code checks using
cppcheck, checking for copyright in source code, Python style linting using
pep8, and other things.
The list of helper packages will likely grow in the future.
A build tool performs the task of building a workspace of packages together at once with a single invocation.
For ROS 2 releases up to Ardent, the build tool providing this functionality is called
As of ROS 2 Bouncy,
ament_tools has been superseded by
colcon, as described in the universal build tool article.