`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 packages
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.

catkin build – Build Packages¶

Basic Usage¶

Previewing The Build¶

Building a Workspace¶

Status Line¶

Console Messages¶

Build Summary¶

Building Subsets of Packages¶

Building Specific Packages¶

Context-Aware Building¶

Skipping Packages¶

Building Single Packages¶

Advanced Options¶

Temporarily Changing Build Flags¶

Building With Warnings¶

Configuring Build Jobs¶

Configuring Memory Use¶

Full Command-Line Interface¶

`catkin build` – Build Packages¶