catkin build – Build Packages

https://catkin-tools.readthedocs.io/en/latest/verbs/catkin_build.html

catkin build – Build Packages 

build 动词用于在 catkin 工作区中构建一个或多个包。 像大多数动词一样，构建是上下文感知的，可以从初始化工作区包含的任何目录中执行。 如果工作区尚未初始化，则 build 可以使用默认配置对其进行初始化，但前提是从工作区根调用它。 也可以使用 --workspace 选项从任意工作目录构建特定的工作区。

export ROS_DISTRO=indigo                                 # 设置ROS发行版本

mkdir -p /tmp/ros_tutorials_ws/src                       # 创建工作空间

cd /tmp/ros_tutorials_ws/src                             # 导航到源空间

rosinstall_generator --deps ros_tutorials > .rosinstall  #  获取包列表

wstool update                                            # Checkout all packages

cd /tmp/ros_tutorials_ws                       # Navigate to ros workspace root

catkin init                                              # Initialize workspace

Basic Usage

预览构建

在工作区中实际构建任何东西之前，预览将构建哪些包以及以什么顺序构建是很有用的。 这可以通过 --dry-run 选项完成：

cd /tmp/ros_tutorials_ws  # Navigate to workspace
catkin build --dry-run    # Show the package build order

除了列出包名称和构建它们的顺序之外，它还显示每个包的构建类型。

Building a Workspace

当没有包作为参数给出时，catkin build 构建整个工作区。 它会自动为构建空间 build space和开发空间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

构建完成后，构建空间包含包含每个包的中间构建产品的目录，而开发空间包含一个 FHS 布局，所有最终构建产品都写入其中。

catkin build 的产品与 catkin_make 的行为有很大不同，例如，它会将所有构建文件和中间构建产品放在一个组合的构建空间中，或者 catkin_make_isolated 将为开发空间中的每个包提供一个独立的 FHS 目录。

Status Line

使用默认选项运行 catkin build 时，它会显示类似于以下内容的“live实时”状态行：

[build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...

状态行停留在屏幕底部，显示整个构建的持续更新进度以及仍在运行的active build jobs活动构建作业。 它由以下信息组成：

• [build - <T>] – 左侧的第一个块表示到目前为止已用的总构建时间 <T>（以秒为单位）。.
• [<M>/<N> complete] – 左起第二个块表示构建进度，以完成包的数量表示，<M> 占要构建的包总数 <N>。
• [<M>/<N> jobs] – 左起第三个区块表示在低级别工作人员的总数 <N> 中活动的总低级别工作 <M> 的数量。
• [<N> queued] – 左起第四个块表示已经满足依赖关系并准备构建的作业 <N> 的数量。
• [<N> failed] – 左起第五个块表示失败的作业 <N> 的数量。 该块仅在一个或多个作业失败时出现。[<package>:<stage> (<P>%) - <T>] – 其余块显示活动作业的详细信息。 其中包括阶段的完成百分比 <P>（如果可用）以及构建包所用的时间 <T>。

必要时，可以通过将 --no-status 选项传递给 catkin build 来禁用状态行。 在不支持重置和重写状态行所需的 ASCII 转义序列的程序中运行 catkin build 时，有时需要这样做。

Console Messages

通常，除非发生错误，否则会收集每个包构建过程的输出，但不会将其打印到控制台。 打印的只是一对消息，指定包构建的开始和结束。 对于 genmsg 包，其格式如下：

每当构建作业写入 stderr 时都会打印错误消息。 在这种情况下，一旦作业完成，构建动词将在警告标头下自动打印捕获的 stderr 缓冲区，类似于以下内容：

请注意，第一行显示了交错日志文件的路径，该文件在构建空间被清理之前一直存在。 此外，如果包失败，则 stderr 的输出将打印在 Errors 标头下。

____________________________________________________________________________

Errors     << {JOB}:{STAGE} {LOGFILE PATH}

{ERRORS}

{REPRODUCTION COMMAND}

............................................................................

Failed     << {JOB}:{STAGE}    [ Exited with code {EXIT CODE} ]

Failed     << {JOB}            [ {TIME} seconds ]

使用 -v 或 --verbose 选项时，可以显示来自底层作业的所有消息。 这将在构建作业开始和完成时打印正常消息，以及块中每个构建命令的交错输出到 stdout 和 stderr。

所有输出都可以使用 --interleave-output 选项交错打印。 在这种情况下，每一行都以它来自的作业和阶段作为前缀。

Build Summary

在每次构建结束时，都会打印一个简短的构建摘要，以确保不会遗漏异常。 此摘要显示总运行时间、成功作业的数量、产生警告的作业数量以及由于依赖关系失败而未尝试的作业数量。

[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.

还可以使用 --summarize 命令打印更详细的摘要，该命令列出工作区中每个包的结果。

Building Subsets of Packages

考虑一个 Catkin 工作空间，其中的源空间填充了以下尚未构建的 Catkin 包：

$ 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

也可以通过在构建动词后将它们指定为位置参数来构建特定的包：

cd /tmp/ros_tutorials_ws # Navigate to workspace

catkin build roslib      # Build roslib and its dependencies

如上所示，在总共 36 个包中，将只构建 4 个包（roslib 及其依赖项）。

Context-Aware Building

catkin build 除了构建所有的包或者指定的具有各种依赖需求的包外，还可以确定包含当前工作目录的包。 这相当于在命令行上指定包的名称，通过将 --this 选项传递给 catkin build 来完成，如下所示：

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

假设您按照 roslib 构建了每个包，但该包有一个构建错误。 修复错误后，您可以再次运行相同的构建命令，但构建动词提供了在这种情况下节省时间的选项。 如果从头重新开始，roslib 的依赖项的任何产品都不会被重新构建，但是底层构建系统仍然需要一些时间来验证每个包。

但是，可以通过直接跳转到给定的包来跳过这些检查。 您可以使用 --start-with 选项在解决问题后从中断的地方继续构建。  catkin build --start-with roslib

cd /tmp/ros_tutorials_ws         # Navigate to workspace

catkin build --start-with roslib # Build roslib and its dependents

Building Single Packages

如果您只对在工作区中构建单个包感兴趣，您还可以使用 --no-deps 选项和包名称。 这将跳过包的所有依赖项，构建给定的包，然后退出。

cd /tmp/ros_tutorials_ws      # Navigate to workspace

catkin build roslib --no-deps # Build roslib only

Building and Running Tests

为给定的包运行测试通常是通过调用一个特殊的 make 目标来完成的，比如 test 或 run_tests。 catkin 包都定义了 run_tests 目标，该目标聚合所有类型的测试并将它们一起运行。 因此，为了让测试为您的包构建和运行，您需要将这个额外的 run_tests 或测试目标作为命令行选项传递给它们。

要对工作区中的所有 catkin 包运行 catkin 测试，请使用以下命令：

$ catkin run_tests

Or the longer version:

$ catkin build [...] --catkin-make-args run_tests

要为特定的 catkin 包运行 catkin 测试，请从该包中的目录：

$ catkin run_tests --no-deps --this

对于定义测试目标的非 catkin 包，您可以执行以下操作：

$ catkin build [...] --make-args test

如果您只想对一个包运行测试，那么您应该构建该包，并使用附加的 make 参数将构建范围缩小到该包：

$ # First build the package

$ catkin build package

...

$ # Then run its tests

$ catkin build package --no-deps --catkin-make-args run_tests

$ # Or for non-catkin packages

$ catkin build package --no-deps --make-args test

对于 catkin 包和 run_tests 目标，失败的测试不会导致非零退出代码。 因此，如果您想检查失败的测试，请使用 catkin_test_results 命令，如下所示：

$ catkin_test_results build/<package name>

除非所有测试都通过，否则结果代码将为非零。

Advanced Options

Temporarily Changing Build Flags

虽然构建配置标志被设置并存储在构建上下文中，但在使用构建动词时可以临时覆盖或增加它们。

$ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"

Building With Warnings

有时在整个 catkin 工作区启用附加警告的情况下进行编译会很有用。 为此，请使用类似于此的命令：

$ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"

此命令将 -DCMAKE_C_FLAGS=... 参数传递给 cmake 的所有调用。

Configuring Build Jobs

默认情况下，在具有 N 个内核的计算机上构建 catkin 将并行构建最多 N 个包，并将使用内部作业服务器在它们之间分配 N 个 make 作业。 如果您的平台不支持作业服务器调度，catkin build 将通过 -jN -lN 为每个包生成。

您可以使用 -p 或 --parallel-packages 选项控制允许并行构建的最大包数，您可以使用 -j 或 --jobs 选项更改可用作业的数量。

默认情况下，这些作业选项不会传递给底层 make 命令。 要禁用作业服务器，您可以使用 --no-jobserver 选项，并且您可以使用 --make-args 选项直接将标志传递给 make。

作业标志（-jN 和/或 -lN）可以通过将它们提供给 catkin build 来直接传递给 make，但其他 make 参数需要传递给 --make-args 选项。

Configuring Memory Use

除了 CPU 和负载限制之外，catkin build 还可以使用隐藏的 --mem-limit 标志根据可用内存限制正在运行的作业数量。 此标志需要安装 Python psutil 模块，并且在没有交换分区的系统或需要限制内存使用的其他情况下很有用。

内存由百分比或字节数指定。

例如，要指定当使用 50% 的可用内存时 catkin build 不应启动额外的并行作业，您可以运行：

$ catkin build --mem-limit 50%

或者，如果在使用超过 4GB 的内存时不应启动其他作业，您可以指定：

$ catkin build --mem-limit 4G

完整的命令行接口

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] [--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 [PKGNAME ...]]

在 catkin 工作区中构建一个或多个包。这会为 catkin 工作区中的所有或指定包调用 `CMake`、`make` 和可选的 `make install`。传递给这个动词的参数可以临时覆盖存储在 catkin 配置文件中的持久选项。如果要保存这些选项，请使用 --save-config 参数。要查看当前配置，请使用 `catkin config` 命令。

可选参数：:

  -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)

  --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 differnt 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.