Quickstart¶
This chapter gives a high-level overview of how to use catkin_tools
and the
catkin
command. This shows how to use the different command verbs to create
and manipulate a workspace. For a more in-depth explanation of the mechanics of
catkin workspaces, see Workspace Mechanics, and for thorogh
usage details see the individual verb documentation.
TL;DR¶
The following is an example workflow and sequence of commands using default settings:
source /opt/ros/indigo/setup.bash # Source ROS indigo to use Catkin
mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
cd /tmp/quickstart_ws # Navigate to the workspace root
catkin init # Initialize it with a hidden marker file
cd /tmp/quickstart_ws/src # Navigate to the source space
catkin create pkg pkg_a # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list # List the packages in the workspace
catkin build # Build all packages in the workspace
source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
catkin clean --all # Clean all the build products
Initializing a New Workspace¶
While initialization of a workspace can be done automatically with catkin
build
, it’s good practice to initialize a catkin workspace explicitly.
This is done by simply creating a new workspace with an empty source space
(named src
by default) and calling catkin init
from the workspace root:
source /opt/ros/indigo/setup.bash # Source ROS indigo to use Catkin
mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
cd /tmp/quickstart_ws # Navigate to the workspace root
catkin init # Initialize it with a hidden marker file
Now the directory /tmp/quickstart-init
has been initialized and catkin
init
has printed the standard configuration summary to the console with the
default values. This summary describes the layout of the workspace as well as
other important settings which influence build and execution behavior.
Once a workspace has been initialized, the configuration summary can be
displayed by calling catkin config
without arguments from anywhere under
the root of the workspace. Doing so will not modify your workspace. The
catkin
command is context-sensitive, so it will determine which workspace
contains the current working directory.
An important property which deserves attention is the summary value labeled
Extending
. This describes other collections of libraries and packages which
will be visible to your workspace. This is process called “workspace chaining.”
The value can be come from a few different sources, and can be classified in
one of the three following ways:
- No chaining
- Implicit chaining via
CMAKE_PREFIX_PATH
environment or cache variable - Explicit chaining via
catkin config --extend
For more information on the configuration summary and workspace chaining, see Configuration Summary. For information on manipulating these options, see the config verb.
Note
Calling catkin init
“marks” a directory path by creating a hidden
directory called .catkin_tools
. This hidden directory is used to
designate the parent as the root of a Catkin workspace as well as store
persistent information about the workspace configuration.
Adding Packages to the Workspace¶
In order to build software with Catkin, it needs to be added to the workspace’s
source space. You can either download some existing packages, or create one
or more empty ones. As shown above, the default path for a Catkin source
space is ./src relative to the workspace root. A standard Catkin package is
simply a directory with a CMakeLists.txt
file and a package.xml
file.
For more information on Catkin packages see workspace mechanics. The shell interaction below shows the creation of four
empty packages: pkg_a
, pkg_b
, pkg_c
, and pkg_d
:
cd /tmp/quickstart_ws/src # Navigate to the source space
catkin create pkg pkg_a # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list # List the packages in the workspace
After these operations, your workspace’s local directory structure would look like the followng (to two levels deep):
cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2 # Show prebuild directory tree
.
├── .catkin_tools
│ ├── default
│ └── README
└── src
├── pkg_a
├── pkg_b
├── pkg_c
└── pkg_d
7 directories, 1 file
Now that there are some packages in the workspace, Catkin has something to build.
Note
Catkin utilizes an “out-of-source” and “aggregated” build pattern. This means that not only will temporary or final build products never be placed in a package’s source directory (or anywhere in the source space for that matter), but also all build directories are aggregated in the build space and all final build products (executables, libraries, etc.) will be put in the devel space.
Building the Workspace¶
Since the catkin workspace has already been initialized, you can call catkin
build
from any directory contained within it. If it had not been initialized,
then catkin build
would need to be called from the workspace root. Based on
the default configuration, it will locate the packages in the source space
and build each of them.
catkin build # Build all packages in the workspace
Calling catkin build
will generate build
and devel
directories (as
described in the config summary above) and result in a directory structure like
the following (to one level deep):
cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2 # Show postbuild directory tree
.
├── build
│ ├── .built_by
│ ├── .catkin_tools.yaml
│ ├── _logs
│ ├── pkg_a
│ ├── pkg_b
│ ├── pkg_c
│ └── pkg_d
├── .catkin_tools
│ ├── default
│ └── README
├── devel
│ ├── .built_by
│ ├── .catkin
│ ├── env.sh
│ ├── etc
│ ├── lib
│ ├── .rosinstall
│ ├── setup.bash
│ ├── setup.sh
│ ├── _setup_util.py
│ ├── setup.zsh
│ └── share
└── src
├── pkg_a
├── pkg_b
├── pkg_c
└── pkg_d
17 directories, 11 files
Intermediate build products (CMake cache files, Makefiles, object files, etc.)
are generated in the build
directory, or build space and final build
products (libraries, executables, config files) are generated in the devel
directory, or devel space. For more information on building and customizing
the build configuration see the build verb and
config verb documentation.
Loading the Workspace Environment¶
In order to properly “use” the products of the workspace, it’s environment needs
to be loaded. Among other environment variables, sourcing a Catkin setup file
modifies the CMAKE_PREFIX_PATH
environment variable, which will affect
workspace chaining as described in the earlier section.
Setup files are located in one of the result spaces generated by your workspace. Both the devel space or the install space are valid result spaces. In the default build configuration, only the devel space is generated. You can load the environment for your respective shell like so:
source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
At this point you should be able to use products built by any of the packages in your workspace.
Note
Any time the member packages change in your workspace, you will need to re-run the source command.
Loading the environment from a Catkin workspace can set arbitrarily many environment variables, depending on which “environment hooks” the member packages define. As such, it’s important to know which workspace environment is loaded in a given shell.
It’s not unreasonable to automatically source a given setup file in each shell
for convenience, but if you do so, it’s good practice to pay attention to the
Extending
value in the Catkin config summary. Any Catkin setup file will
modify the CMAKE_PREFIX_PATH
environment variable, and the config summary
should catch common inconsistencies in the environment.
Cleaning Workspace Products¶
Instead of using dangerous commands like rm -rf build devel
in your
workspace when cleaning build products, you can use the catkin clean --all
command. Just like the other verbs, catkin clean
is context-aware, so it
only needs to be called from a directory under the workspace root.
In order to clean the build space and devel space for the workspace, you can use the following command:
catkin clean --all # Clean all the build products
For more information on less aggressive cleaning options see the clean verb documentation.