Skip to main content

Local Docker Pkg Build using MRS Tools

This guide explains how to use the MRS CI scripts to generate a .deb package for a ROS-based project directly on your local machine using Docker. This ensures a clean build environment identical to the one used in the official build farm.

1. Clone the CI Scripts​

The MRS CI scripts contain the Docker wrappers and entrypoint logic required for the build process.

cd ~/git
git clone https://github.com/ctu-mrs/ci_scripts
cd ci_scripts
git checkout ros2
note

Ensure you checkout the correct branch for your target environment. Use the ros2 branch for ROS 2 packages and the master branch for ROS 1 packages.

2. Set Local Environment Variable​

The CI scripts are designed to run in GitHub Actions by default. Setting RUN_LOCALLY bypasses CI-specific checks, such as SSH key verification for private repositories.

export RUN_LOCALLY=true
note

Environment variables are session-specific. If you open a new terminal tab, you must run this export command again.

3. Configure the Target Repository Path​

The build script needs to know where your source code is located on your host machine to mount it into the Docker container.

  • Open the build configuration file:
vim package_build/ros_build/build.sh
  • Locate the REPOSITORY_FOLDER assignment (typically around line 30).
  • Change it to the absolute path of your ROS package.

Example for mrs_lib:

# Change this line:
[ -z $REPOSITORY_FOLDER ] && REPOSITORY_FOLDER=~/git/mrs_lib

4. Prime the Docker Image​

Before building, you must pull or build the base image that contains the necessary build tools and ROS distribution.

./docker/prime_image/prime_image.sh

5. Execute the Build​

Run the build script. This command launches the Docker container and executes the entrypoint.sh logic inside the isolated environment.

./package_build/ros_build/build.sh

The Internal Build Process​

The entrypoint.sh script automates the following steps inside the container:

  • Metadata Generation: Runs bloom-generate rosdebian to create the debian/ folder logic.
  • Dependency Resolution: Uses rosdep to install all system and ROS dependencies defined in your package.xml.
  • Compilation & Packaging: Invokes fakeroot debian/rules binary to compile the code and wrap it into a .deb file.

Rosdep Dependency Resolving​

If the build fails because dependencies are not resolved, verify your package.xml. ROS uses Rosdep keys, which often differ from the actual Debian package names.

Finding the Correct Key​

To check if rosdep can resolve a specific Debian package, use the following command (e.g., checking for libtbb-dev):

rosdep db | grep libtbb-dev

Example Outcome:

tbb -> libtbb-dev

This means you must use the key tbb in your package.xml, not the Debian name libtbb-dev:

<depend>tbb</depend>
Adding Missing Dependencies​

If a dependency is not found by rosdep, it can be added to the MRS system by updating our handcrafted rosdep file: MRS Handcrafted Rosdep File

6. Retrieve the Artifacts​

After the process completes, the resulting Debian package and build logs are moved to your system's temporary directory.

cd /tmp/artifacts
ls -lh

You can now install the generated package using:

sudo apt install ./ros-<distro>-<your-package-name>_*.deb