colcon verb extension to build and test inside a fresh and isolated ROS environment and transfer the results back to the host.
With this extension, developers can build ROS packages for any ROS 2 distributions directly from colcon independently of the host.
With it, one can validate 'builds' and 'tests' making sure all the dependencies are properly listed in their package.xml
on any ROS 2 distribution.
Validating packages and workspace in an isolated and ephemeral environment is key for distributing and packaging software.
Install the tool:
pip3 install -U git+https://github.com/canonical/colcon-in-container
Install and initialize LXD:
sudo snap install lxd
lxd init --auto
:warning: If you have Docker installed, mind that it causes connectivity issues
Then call colcon with the build-in-container verb:
colcon --log-level=info build-in-container --ros-distro jazzy
See the usage section for advanced information on installation and tool usage.
colcon build-in-container
performs the following steps to build your workspace:
LXD
containerpackage.xml
updated!)build/
and install/
directories of the built workspace on your host under: build_in_container
and install_in_container/
colcon test-in-container
performs the following steps to build your workspace:
LXD
containerbuild_in_container
and install_in_container/
directories inside the containerpackage.xml
updated!)test_results_in_container/
colcon release-in-container
performs the following steps to release your workspace's packages:
LXD
containerpackage.xml
updated!)release_in_container/
To use the extension you will need to install it and also install and initialize LXD. Both steps are described below.
This being a colcon extension, make sure to have colcon installed.
The extension can be installed via pip
using the URL with the following command:
pip3 install -U git+https://github.com/canonical/colcon-in-container
Due to potential conflict with the python dependencies cryptography
and pyopenssl
between a ROS install and the tool, a python virtual environment is recommended.
LXD
can be installed with snap:
sudo snap install lxd
Alternative installation methods are available in the LXD
documentation.
Initialize LXD
with:
lxd init --auto
As an alternative to LXD
, one can use multipass
as
an environment provider.
multipass
is support on Linux, Windows and MacOS.
multipass
can be installed following the documentation.
multipass
VMs attributes can be specified over environment variables:
COLCON_IN_CONTAINER_MULTIPASS_CPUS
, default="2"COLCON_IN_CONTAINER_MULTIPASS_MEMORY
, default="2G"COLCON_IN_CONTAINER_MULTIPASS_DISK
, default="256G"Basic usage:
colcon build-in-container
Advanced usage:
colcon --log-level=info build-in-container --ros-distro jazzy --colcon-build-args "--cmake-args -DCMAKE_BUILD_TYPE=Release" --debug
Usage help:
$ colcon build-in-container --help
usage: colcon build-in-container [-h] [--ros-distro ROS_DISTRO] [--colcon-build-args *] [--debug] [--shell-after] [--paths [PATH [PATH ...]]]
Call a colcon build command inside a fresh container.
options:
-h, --help show this help message and exit
--ros-distro ROS_DISTRO
ROS version, can also be set by the environment variable ROS_DISTRO.
--colcon-build-args *
Pass arguments to the colcon build command
--debug Shell into the environment in case the build fails.
--shell-after Shell into the environment at the end of the build or if there is an error. This flag includes "--debug".
--provider {lxd, multipass} Environment provider.
By default, build-in-container
uses the ROS version from the ROS_DISTRO
environment variable.
This can be overwritten with the option --ros-distro
allowing one to compile for a different ROS distribution than the one associated with the host OS.
Basic usage:
colcon test-in-container
Advanced usage:
colcon --log-level=info test-in-container --ros-distro jazzy --colcon-test-args "--cmake-args -DCMAKE_BUILD_TYPE=Release" --debug
Usage help:
$ colcon test-in-container --help
usage: colcon test-in-container [-h] [--ros-distro ROS_DISTRO] [--colcon-test-args *] [--debug] [--shell-after] [--paths [PATH [PATH ...]]]
Call a colcon test command inside a fresh container.
options:
-h, --help show this help message and exit
--ros-distro ROS_DISTRO
ROS version, can also be set by the environment variable ROS_DISTRO.
--colcon-test-args * Pass arguments to the colcon test command. Arguments matching other
options must be prefixed by a space.
--debug Shell into the environment in case the build fails.
--shell-after Shell into the environment at the end of the build or if there is an
error. This flag includes "--debug".
--provider {lxd, multipass} Environment provider.
By default, buil and test in-container
use the ROS version from the ROS_DISTRO
environment variable.
This can be overwritten with the option --ros-distro
allowing one to test for a different ROS distribution than the one associated with the host OS.
Basic usage:
colcon release-in-container
Advanced usage:
colcon --log-level=info release-in-container --ros-distro jazzy --bloom-generator rosdebian --debug
Usage help:
$ colcon release-in-container --help
usage: colcon release-in-container [-h] [--ros-distro ROS_DISTRO] [--bloom-generator {debian,rosdebian}] [--debug] [--shell-after] [--paths [PATH [PATH ...]]]
Generate Debian package inside a fresh container using bloom and fakeroot.
options:
-h, --help show this help message and exit
--ros-distro ROS_DISTRO
ROS version, can also be set by the environment variable ROS_DISTRO.
--bloom-generator {debian,rosdebian}
Pass arguments to the bloom-generate command
Pass arguments to the colcon build command
--debug Shell into the environment in case the build fails.
--shell-after Shell into the environment at the end of the build or if there is an error. This flag includes "--debug".
--provider {lxd, multipass} Environment provider.
By default, release-in-container
uses the ROS version from the ROS_DISTRO
environment variable.
This can be overwritten with the option --ros-distro
allowing one to release for a different ROS distribution than the one associated with the host OS.
The colcon in-container
extension can be used to:
package.xml
are up to dateIf you have issues with pylxd and openssl:
Pylxd doesn't work from the apt debian or the pip package. You must be installed from source
Please open a GitHub issue if you face any issue with the tool.