Table of Contents
This will provide you with a quick summary of how to get up and running using an ament workspace. It will be a practical tutorial and is not designed to replace the core documentation.
As of ROS 2 Bouncy the recommended build tool is
colcon described in the colcon tutorial.
The current default branch as well as releases after Bouncy do not include
Ament is an iteration on the catkin meta-build tool. For more information on the design of ament see this document.
The source can be found in the ament GitHub organization.
An ament workspace is a directory with a particular structure.
Commonly there is a
Inside that subdirectory is where the source code will be located.
Typically the directory starts otherwise empty.
Ament does out of source builds.
By default it will create a
install directory as peers of the
build directory will be where intermediate files are stored.
For each package a subfolder will be created in which e.g. CMake is being invoked.
install directory is where each package will be installed to.
NB: Compared to catkin there is no
To make the basic structure in the directory
mkdir -p ~/ros2_ws/src cd ~/ros2_ws
This is the directory structure of
~/ros2_ws that you can expect at this point:
. └── src 1 directory, 0 files
To start off we need to setup an underlay without any of ROS2 installed.
Note: if you do not have
vcs installed, instructions are here.
wget https://raw.githubusercontent.com/ros2/ros2/master/ros2.repos vcs import src < ros2.repos
This is the directory structure of
~/ros2_ws that you can expect after adding sources (note the exact structure and number of directories/files may change over time):
. ├── ros2.repos └── src ├── ament │ ├── ament_cmake │ ├── ament_index | ... │ ├── osrf_pycommon │ └── uncrustify ├── eProsima │ ├── Fast-CDR │ └── Fast-RTPS ├── ros │ ├── class_loader │ └── console_bridge └── ros2 ├── ament_cmake_ros ├── common_interfaces ├── demos ... ├── urdfdom ├── urdfdom_headers └── vision_opencv 51 directories, 1 file
Since this is a bootstrap environment we need to call ament.py by its full path.
Note: In the future once ament is either installed on your system or in an underlayed workspace this will no longer be necessary.
Since there is no
devel space in ament and it requires installing each package it supports the option
This allows the installed files to be changed by changing the files in the
source space (e.g. Python files or other not compiled resourced) for faster iteration.
src/ament/ament_tools/scripts/ament.py build --build-tests --symlink-install
To run the tests you just built, with the
--build-tests option above, run the following:
If you have built (and installed) a workspace before including the tests (using
build --build-tests) you can skip the build and install step to speed up the process:
src/ament/ament_tools/scripts/ament.py test --skip-build --skip-install
When ament has completed building successfully the output will be in the
To use the executables and libraries you need to e.g. add the
install/bin directory to your path.
Ament will have generated bash files in the
install directory to help setup the environment.
These files will both add the required elements to your path and library paths as well as provide any exported bash or shell commands exported by packages.
NB: This is slightly different than catkin.
local_setup.* file is slightly different than the
setup.* file in that it will only apply settings from the current workspace.
When using more than one workspace you will still source the
setup.* files to get the environment including all parent workspaces.
Ament uses the same
package.xml specification as defined for catkin in REP 140.
You can create your own package inside the
src directory however it is recommended to use an overlay when you are going to iterate only on a few packages.
Now that you have setup your bootstrap underlay you will also find
ament is on your path.
Lets make a new overlay directory
mkdir -p ~/ros2_overlay_ws/src cd ~/ros2_overlay_ws/src
And to get started we’ll overlay the ros2/examples repository:
# If you know that you're using the latest branch of all # repositories in the underlay, you can also get the latest # version of the ros2/examples repository, with this command: # git clone https://github.com/ros2/examples.git # Otherwise, clone a copy from the underlay source code: git clone ~/ros2_ws/src/ros2/examples
And build the overlay, but let’s build with debug so we can make sure to get debug symbols:
cd ~/ros2_overlay_ws ament build --cmake-args -DCMAKE_BUILD_TYPE=Debug
Now this overlay is on top of the existing overlay so you’ll find that
which talker currently refers to the one from the underlay.
If you source
~/ros2_overlay_ws/install/local_setup.bash it will change to refer to talker in the overlay.
If you are returning with a new terminal to your development and want to pick up developing on your overlay you can simply source
~/ros2_overlay_ws/install/setup.bash which will source all parent workspaces environments automatically.
You can create your own package.
The equivalent of
catkin_create_package will be ported to ament but is not available yet.
Ament supports multiple build types.
The recommended build types are
Also supported are pure
It’s expected to add support for more build types.
An example of an
ament_python build is the ament_tools package, where the setup.py is the primary entry point for building.
A package such as demo_nodes_cpp uses the
ament_cmake build type, and uses CMake as the build tool.
If you do not want to build a specific package place an empty file named
AMENT_IGNOREin the directory and it will not be indexed.
“Catch all” options like –cmake-args should be placed after other options, or delimited with ‘–’:
ament build . --force-cmake-configure --cmake-args -DCMAKE_BUILD_TYPE=Debug -- --ament-cmake-args -DCMAKE_BUILD_TYPE=Release
If you want to run a single particular test from a package:
ament test --only-packages YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG