.\" Copyright 2021-2022 Timo Röhling <roehling@debian.org>
.\" SPDX-License-Identifier: MIT
.TH ROSBUILDER 1 "" "0.11.1" ""
.SH NAME
rosbuilder \- execute appropriate build commands for ROS packages
.SH SYNOPSIS
.SY rosbuilder
.OP \fIoptions\fR
.YS
.SH DESCRIPTION
.B rosbuilder
is invoked internally by the
.B ros
buildsystem. You can use this in your
.I debian/rules
with
.BR dh " " --buildsystem=ros .
.SH OPTIONS
.TP
.BR \-h ", " \-\-help
show this help message and exit
.TP
.BR \-\-sourcedir " " \fIDIR\fR
root directory of the source package
.TP
.BR \-\-search\-depth " " \fIN\fR
limit maximum depth to
.I N
directory levels when searching for packages
recursively (default: 2)
.TP
.B \-\-unlimited\-search\-depth
do not limit maximum depth when searching for packages
.TP
.BR \-\-builddir " " \fIDIR\fR
build directory
.TP
.BR \-\-destdir " " \fIDIR\fR
installation directory
.TP
.B \-\-verbose
make verbose output
.TP
.B \-\-detect
detect if ROS packages are to be built
.TP
.B \-\-build\-types
list detected build types
.TP
.B \-\-build\-order
list packages in build order
.SH ENVIRONMENT
The
.B rosbuilder
behavior can be customized by setting various environment variables in
.IR debian/rules .
.PP
Remember to prefix the declarations with the
.B export
keyword,
or the variables will not propagate to the environment properly.
.SS General behavior
.TP
.B ROS_DESTDIR
override the location for the staged installation
.TP
.B ROS_IGNORE_TEST_RESULTS
do not fail the build if the
.B dh_auto_test
step fails for the listed packages. If set to the special value
.BR 1 ,
test failures for all packages will be ignored.
.TP
.B ROS_PYTHON_VERSION
set to
.B 2
or
.B 3
to force the respective Python version for the build
.TP
.B ROS_SKIP_PACKAGES
do not build the listed packages at all
.TP
.B ROS_SKIP_TESTS
skip tests for the listed packages. If set to the special
value
.BR 1 ,
all package tests will be skipped. This is equivalent to
passing
.B nocheck
via
.BR DEB_BUILD_OPTIONS .
.SS Customizing dh_auto_*
For the
.BR configure ", " build ", " test ", and " install
steps, there are hooks to run additional commands before and after each step.
Also, either additional arguments can be passed to the
.B dh_auto_*
helpers or the whole step can be replaced by a different command.
.TP
.BI "ROS_" step "_ARGS"
pass additional arguments to a dh step. The placeholder
.I step
stands for one of CONFIGURE, BUILD, TEST, INSTALL, or CLEAN, all in upper-case.
.TP
.BI "ROS_" step "_" type "_ARGS"
pass additional arguments to a dh step, but only for packages with
a particular build type. Known build types are AMENT_CMAKE, AMENT_PYTHON,
CATKIN, and CMAKE.
.TP
.BI "ROS_" step "_COMMAND_PREFIX"
prepend the given command and its arguments to a dh step. This is intended for
wrapper commands which execute the remainder of their arguments, such as
.BR xvfb-run ,
which can be used to run tests in a virtual X server.
.TP
.BI "ROS_" step "_" type "_COMMAND_PREFIX"
prepend the given command and its arguments to a dh step, but only for a
particular build type.
.TP
.BI ROS_EXECUTE_BEFORE_ step
execute additional commands before a dh step. The value is subject to
some variable expansion (see below) and treated as shell command line.
.TP
.BI ROS_EXECUTE_AFTER_ step
execute additional commands before a dh step
.TP
.BI ROS_EXECUTE_BEFORE_ step "_" type
execute additional commands before a dh step for packages of build type
.IR type .
.TP
.BI ROS_EXECUTE_AFTER_ step "_" type
execute additional commands after a dh step for packages of build type
.IR type .
.TP
.BI ROS_EXECUTE_CUSTOM_ step
replace the dh step by a custom shell command line. This will replace the
entire command line, so any
.B COMMAND_PREFIX
will be ignored as well.
.TP
.BI ROS_EXECUTE_CUSTOM_ step _ type
replace the dh step for packages of build type
.I type
by a custom shell command line. This will replace the entire command line,
so any
.B COMMAND_PREFIX
will be ignored as well.
.SS Variable expansions for shell command lines
.B rosbuilder
supports a few placeholders in custom command lines. All values will be quoted
as required to prevent spurious shell expansions.
.TP
.B "{dir}"
the source directory of the currently processed ROS package
.TP
.B "{builddir}"
the temporary build directory of the currently processed ROS package
.TP
.B "{destdir}"
the location for the staged installation
.TP
.B "{package}"
the name of the currently processed ROS package
.TP
.B "{package_id}"
the sanitized package name, suitable for use as variable identifier
.TP
.B "{version}"
the version number of the currently procssed ROS package
.TP
.B "{build_type}"
the build type of the currently processed ROS package
.SH AUTHOR
The
.B dh-ros
helper and
.B rosbuilder
was written by
.MT roehling@debian.org
Timo R\[u00F6]hling
.ME
for Debian.
.SH SEE ALSO
.BR debhelper (7)