catkin build
– Build Packages¶
The build
verb is used to build one or more packages in a catkin workspace.
Like most verbs, build
is context-aware and can be executed from within any directory contained by an initialized workspace.
If a workspace is not yet initialized, build
can initialize it with the default configuration, but only if it is called from the workspace root.
Specific workspaces can also be built from arbitrary working directories with the --workspace
option.
Note
To set up a workspace and clone the repositories used in the following examples, you can use rosinstall_generator and wstool. The following clones all of the ROS packages necessary for building the introductory ROS tutorials:
export ROS_DISTRO=noetic # Set ROS distribution
mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
cd /tmp/ros_tutorials_ws/src # Navigate to source space
rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages
wstool update # Checkout all packages
cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
catkin init # Initialize workspace
Basic Usage¶
Previewing The Build¶
Before actually building anything in the workspace, it is useful to preview which packages will be built and in what order.
This can be done with the --dry-run
option:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build --dry-run # Show the package build order
In addition to the listing the package names and in which order they would be built, it also displays the build type of each package.
Building a Workspace¶
When no packages are given as arguments, catkin build
builds the entire workspace.
It automatically creates directories for a build space and a devel space:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build # Build all the packages in the workspace
ls build # Show the resulting build space
ls devel # Show the resulting devel space
After the build finishes, the build space contains directories containing the intermediate build products for each package, and the devel space contains an FHS layout into which all the final build products are written.
Note
The products of catkin build
differ significantly from the behavior of catkin_make
, for example, which would have all of the build files and intermediate build products in a combined build space or catkin_make_isolated
which would have an isolated FHS directory for each package in the devel space.
Status Line¶
When running catkin build
with default options, it displays a “live” status line similar to the following:
[build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
The status line stays at the bottom of the screen and displays the continuously-updated progress of the entire build as well as the active build jobs which are still running. It is composed of the following information:
[build - <T>]
– The first block on the left indicates the total elapsed build time<T>
in seconds thus far.[<M>/<N> complete]
– The second block from the left indicates the build progress in terms of the number of completed packages,<M>
out of the total number of packages to be built<N>
.[<M>/<N> jobs]
– The third block from the left indicates the number of active total low-level jobs<M>
out of the total number of low-level workers<N>
.[<N> queued]
– The fourth block from the left indicates the number of jobs<N>
whose dependencies have already been satisfied and are ready to be built.[<N> failed]
– The fifth block from the left indicates the number of jobs<N>
which have failed. This block only appears once one or more jobs has failed.[<package>:<stage> (<P>%) - <T>]
– The remaining blocks show details on the active jobs. These include the percent complete,<P>
, of the stage, if available, as well as the time elapsed building the package,<T>
.
When necessary, the status line can be disabled by passing the --no-status
option to catkin build
.
This is sometimes required when running catkin build
from within a program that doesn’t support the ASCII escape sequences required to reset and re-write the status line.
Console Messages¶
Normally, unless an error occurs, the output from each package’s build process is collected but not printed to the console.
All that is printed is a pair of messages designating the start and end of a package’s build.
This is formatted like the following for the genmsg
package:
...
Starting >>> {JOB}
...
Finished <<< {JOB} [ {TIME} seconds ]
...
Error messages are printed whenever a build job writes to stderr
.
In such cases, the build
verb will automatically print the captured stderr
buffer under a Warnings
header once the job has completed, similarly to below:
____________________________________________________________________________
Warnings << {JOB}:{STAGE} {LOGFILE PATH}
{WARNINGS}
{REPRODUCTION COMMAND}
............................................................................
Finished << {JOB} [ {TIME} seconds ]
Note that the first line displays the path to the interleaved log file, which persists until the build space is cleaned.
Additionally, if a package fails, the output to stderr
is printed under the Errors
header.
____________________________________________________________________________
Errors << {JOB}:{STAGE} {LOGFILE PATH}
{ERRORS}
{REPRODUCTION COMMAND}
............................................................................
Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
Failed << {JOB} [ {TIME} seconds ]
All of the messages from the underlying jobs can be shown when using the -v
or --verbose
option.
This will print the normal messages when a build job starts and finishes as well as the interleaved output to stdout
and stderr
from each build command in a block.
All output can be printed interleaved with the --interleave-output
option.
In this case, each line is prefixed with the job and stage from which it came.
Build Summary¶
At the end of each build, a brief build summary is printed to guarantee that anomalies aren’t missed. This summary displays the total run-time, the number of successful jobs, the number of jobs which produced warnings, and the number of jobs which weren’t attempted due to failed dependencies.
[build] Runtime: 1.9 seconds total.
[build] Summary: 4 of 7 jobs completed.
[build] Warnings: None.
[build] Abandoned: 1 jobs were abandoned.
[build] Failed: 2 jobs failed.
A more detailed summary can also be printed with the --summarize
command, which lists the result for each package in the workspace.
Building Subsets of Packages¶
Consider a Catkin workspace with a source space populated with the following Catkin packages which have yet to be built:
$ pwd
/tmp/path/to/my_catkin_ws
$ ls ./*
./src:
catkin console_bridge genlisp genpy
message_runtime ros_comm roscpp_core std_msgs
common_msgs gencpp genmsg message_generation
ros ros_tutorials rospack
Building Specific Packages¶
Specific packages can also be built by specifying them as positional arguments after the build
verb:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build roslib # Build roslib and its dependencies
As shown above, only 4 packages (roslib
and its dependencies), of the total 36 packages would be built.
Context-Aware Building¶
In addition to building all packages or specified packages with various dependency requirements, catkin build
can also determine the package containing the current working directory.
This is equivalent to specifying the name of the package on the command line, and is done by passing the --this
option to catkin build
like the following:
cd /tmp/ros_tutorials_ws # Navigate to workspace
cd src/ros/roslib # Navigate to roslib source directory
ls # Show source directory contents
catkin build --this # Build roslib and its dependencies
Skipping Packages¶
Suppose you built every package up to roslib
, but that package had a build error.
After fixing the error, you could run the same build command again, but the build
verb provides an option to save time in this situation.
If re-started from the beginning, none of the products of the dependencies of roslib
would be re-built, but it would still take some time for the underlying build system to verify that for each package.
Those checks could be skipped, however, by jumping directly to a given package.
You could use the --start-with
option to continue the build where you left off after fixing the problem.
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build --start-with roslib # Build roslib and its dependents
Note
catkin build
will assume that all dependencies leading up to the package
specified with the --start-with
option have already been successfully
built.
Building Single Packages¶
If you’re only interested in building a single package in a workspace, you can also use the --no-deps
option along with a package name.
This will skip all of the package’s dependencies, build the given package, and then exit.
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build roslib --no-deps # Build roslib only
Advanced Options¶
Temporarily Changing Build Flags¶
While the build configuration flags are set and stored in the build context, it’s possible to temporarily override or augment them when using the build
verb.
$ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
Building With Warnings¶
It can sometimes be useful to compile with additional warnings enabled across your whole catkin workspace. To achieve this, use a command similar to this:
$ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
This command passes the -DCMAKE_C_FLAGS=...
argument to all invocations of cmake
.
Configuring Build Jobs¶
By default catkin build
on a computer with N
cores will build up to N
packages in parallel and will distribute N
make
jobs among them using an internal job server.
If your platform doesn’t support job server scheduling, catkin build
will pass -jN -lN
to make
for each package.
You can control the maximum number of packages allowed to build in parallel by using the -p
or --parallel-packages
option and you can change the number of make
jobs available with the -j
or --jobs
option.
By default, these jobs options aren’t passed to the underlying make
command.
To disable the job server, you can use the --no-jobserver
option, and you can pass flags directly to make
with the --make-args
option.
Note
Jobs flags (-jN
and/or -lN
) can be passed directly to make
by
giving them to catkin build
, but other make
arguments need to be
passed to the --make-args
option.
Configuring Memory Use¶
In addition to CPU and load limits, catkin build
can also limit the number of running jobs based on the available memory, using the hidden --mem-limit
flag.
This flag requires installing the Python psutil
module and is useful on systems without swap partitions or other situations where memory use needs to be limited.
Memory is specified either by percent or by the number of bytes.
For example, to specify that catkin build
should not start additional parallel jobs when 50% of the available memory is used, you could run:
$ catkin build --mem-limit 50%
Alternatively, if it should not start additional jobs when over 4GB of memory is used, you can specify:
$ catkin build --mem-limit 4G
Full Command-Line Interface¶
usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
[--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
[--unbuilt] [--start-with PKGNAME | --start-with-this]
[--continue-on-failure] [--force-cmake] [--pre-clean]
[--no-install-lock] [--save-config] [-j JOBS]
[-p PACKAGE_JOBS] [-l LOAD_AVERAGE]
[--jobserver | --no-jobserver]
[--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
| --no-cmake-args] [--make-args ARG [ARG ...] |
--no-make-args] [--catkin-make-args ARG [ARG ...] |
--no-catkin-make-args] [--verbose] [--interleave-output]
[--no-status] [--summarize] [--no-summarize]
[--override-build-tool-check]
[--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
[PKGNAME ...]
Build one or more packages in a catkin workspace. This invokes `CMake`,
`make`, and optionally `make install` for either all or the specified packages
in a catkin workspace. Arguments passed to this verb can temporarily override
persistent options stored in the catkin profile config. If you want to save
these options, use the --save-config argument. To see the current config, use
the `catkin config` command.
optional arguments:
-h, --help show this help message and exit
--workspace WORKSPACE, -w WORKSPACE
The path to the catkin_tools workspace or a directory
contained within it (default: ".")
--profile PROFILE The name of a config profile to use (default: active
profile)
--dry-run, -n List the packages which will be built with the given
arguments without building them.
--get-env PKGNAME Print the environment in which PKGNAME is built to
stdout.
Packages:
Control which packages get built.
PKGNAME Workspace packages to build, package dependencies are
built as well unless --no-deps is used. If no packages
are given, then all the packages are built.
--this Build the package containing the current working
directory.
--no-deps Only build specified packages, not their dependencies.
--unbuilt Build packages which have yet to be built.
--start-with PKGNAME Build a given package and those which depend on it,
skipping any before it.
--start-with-this Similar to --start-with, starting with the package
containing the current directory.
--continue-on-failure, -c
Try to continue building packages whose dependencies
built successfully even if some other requested
packages fail to build.
Build:
Control the build behavior.
--force-cmake Runs cmake explicitly for each catkin package.
--pre-clean Runs `make clean` before building each package.
--no-install-lock Prevents serialization of the install steps, which is
on by default to prevent file install collisions
Config:
Parameters for the underlying build system.
--save-config Save any configuration options in this section for the
next build invocation.
-j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
active packages. (default is cpu count)
-p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
Maximum number of packages allowed to be built in
parallel (default is cpu count)
-l LOAD_AVERAGE, --load-average LOAD_AVERAGE
Maximum load average before no new build jobs are
scheduled
--jobserver Use the internal GNU Make job server which will limit
the number of Make jobs across all active packages.
--no-jobserver Disable the internal GNU Make job server, and use an
external one (like distcc, for example).
--env-cache Re-use cached environment variables when re-sourcing a
resultspace that has been loaded at a different stage
in the task.
--no-env-cache Don't cache environment variables when re-sourcing the
same resultspace.
--cmake-args ARG [ARG ...]
Arbitrary arguments which are passed to CMake. It
collects all of following arguments until a "--" is
read.
--no-cmake-args Pass no additional arguments to CMake.
--make-args ARG [ARG ...]
Arbitrary arguments which are passed to make. It
collects all of following arguments until a "--" is
read.
--no-make-args Pass no additional arguments to make (does not affect
--catkin-make-args).
--catkin-make-args ARG [ARG ...]
Arbitrary arguments which are passed to make but only
for catkin packages. It collects all of following
arguments until a "--" is read.
--no-catkin-make-args
Pass no additional arguments to make for catkin
packages (does not affect --make-args).
Interface:
The behavior of the command-line interface.
--verbose, -v Print output from commands in ordered blocks once the
command finishes.
--interleave-output, -i
Prevents ordering of command output when multiple
commands are running at the same time.
--no-status Suppresses status line, useful in situations where
carriage return is not properly supported.
--summarize, --summary, -s
Adds a build summary to the end of a build; defaults
to on with --continue-on-failure, off otherwise
--no-summarize, --no-summary
Explicitly disable the end of build summary
--override-build-tool-check
use to override failure due to using different build
tools on the same workspace.
--limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
Limit the update rate of the status bar to this
frequency. Zero means unlimited. Must be positive,
default is 10 Hz.
--no-notify Suppresses system pop-up notification.