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
⚠️ 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:
- Start an ephemeral
LXDcontainer - Install a fresh ROS 2
- Upload your workspace inside the container
- Install your build time rosdep dependencies (make sure to keep your
package.xmlupdated!) - Build you workspace inside the container
- Download the
build/andinstall/directories of the built workspace on your host under:build_in_containerandinstall_in_container/
colcon test-in-container performs the following steps to build your workspace:
- Start an ephemeral
LXDcontainer - Install a fresh ROS 2
- Upload your workspace as well as your
build_in_containerandinstall_in_container/directories inside the container - Install your test time rosdep dependencies (make sure to keep your
package.xmlupdated!) - Test you workspace inside the container
- Download the test results directory of the built workspace on your host under:
test_results_in_container/
colcon release-in-container performs the following steps to release your workspace's packages:
- Start an ephemeral
LXDcontainer - Install a fresh ROS 2
- Install the necessary software to generate a Debian file
- Upload your workspace inside the container
- Install your build time rosdep dependencies (make sure to keep your
package.xmlupdated!) - Generate the Debian for each of the selected packages
- Download the results of the releases on your host under:
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:
- Build, test and release ROS 2 package in a clean environment
- Build, test and release a ROS 2 package for a different ROS distribution
- Make sure that your
package.xmlare up to date - Build, test and release a ROS 2 workspace with a ROS 2 version you haven't installed
- And more!
If 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent