## Notice: This repository is deprecated. It is outdated and will not be supported anymore.
It is recommended to use a native cross-compilation method, which can be up to 8 times faster.
See details in this ROS Discourse discussion:
https://discourse.ros.org/t/call-for-help-maintainership-of-the-ros-cross-compile-tool/26511
# ROS / ROS 2 Cross Compile Tool
[](https://cross_compile.readthedocs.io/en/latest/?badge=latest)
A tool to automate compiling ROS and ROS 2 workspaces to non-native architectures.
:construction: `ros_cross_compile` relies on running emulated builds
using QEmu, #69 tracks progress toward enabling cross-compilation.
## Supported targets
This tool supports compiling a workspace for all combinations of the following:
* Architecture: `armhf`, `aarch64`, `x86_64`
* ROS Distro
* ROS: `melodic`, `noetic`
* ROS 2: `foxy`, `galactic`, `humble`, `rolling`
* OS: `Ubuntu`, `Debian`
NOTE: ROS 2 supports Debian only as a Tier 3 platform.
This means that there are not `apt` repositories available for the ROS 2 Core on this platform.
Because of that, when targeting Debian for a ROS 2 workspace, you must also include the source for the core as well.
It is recommended to use a release branch of `ros2.repos` from https://github.com/ros2/ros2 to do so, rather than `master`, so that you are not affected by development branch bugs and API changes.
## Supported hosts
This tool officially supports running on the following host systems.
Note that many others likely work, but these are being thoroughly tested.
* Ubuntu 20.04 Focal
* OSX Mojave
## Installation
### Prerequisites
This tool requires that you have already installed
* [Docker](https://docs.docker.com/install/)
* Follow the instructions to add yourself to the `docker` group as well, so you can run containers as a non-root user
* Python 3.7 or higher
If you are using a Linux host, you must also install QEmu (Docker for OSX performs emulation automatically):
```sh
sudo apt-get install qemu-user-static
```
### Installing ros_cross_compile
To install the stable release,
```sh
pip3 install ros_cross_compile
```
If you would like the latest nightly build, you can get it from Test PyPI
```sh
pip3 install --index-url https://test.pypi.org/simple/ ros_cross_compile
```
## How it works, high level
1. Collect dependencies
1. Create a Docker image that has `rosdep`
1. Run the `rosdep` image against your target workspace to output a script that describes how to install its dependencies
1. Create "sysroot image" that has everything needed for building target workspace
1. Use a base image for the target architecture (aarch64, armhf, ...)
1. Install build tools (compilers, cmake, colcon, etc)
1. Run the dependency installer script collected in Step 1 (if dependency list hasn't changed since last run, this uses the Docker cache)
1. Build
1. Runs the "sysroot image" using QEmu emulation
1. `colcon build`
1. (Optional) Create runtime image
1. Creates a docker image that can be used on the target platform to run the build. See "Runtime Image" section.
## Usage
This package installs the `ros_cross_compile` command.
The command's first argument is the path to your ROS workspace.
Here is a simple invocation for a standard workflow.
```bash
ros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu --rosdistro foxy
```
For information on all available options, run `ros_cross_compile -h`.
See the following sections for information on the more complex options.
### Package Selection and Build Customization
To choose which packages to install dependencies for, this tool runs `colcon list` on your workspace.
To build, it runs `colcon build`.
You can provide arbitrary arguments to these commands via the [colcon `defaults.yaml`](https://colcon.readthedocs.io/en/released/user/configuration.html#defaults-yaml).
You can either specify the name of this file via `ros_cross_compile --colcon-defaults /path/to/defaults.yaml`, or if not specified, a file called `defaults.yaml` will be used if present.
For example, there are repositories checked out in your workspace that contain packages that are not needed for your application - some repos provide many packages and you may only want one!
In this scenario there is a "bringup" package that acts as the entry point to your application:
```yaml
# my_workspace/defaults.yaml
list:
# only install dependencies for source packages that my package depends on
packages-up-to: [my_application_bringup]
build:
# only build up to my package
packages-up-to: [my_application_bringup]
# example of a boolean commandline argument
merge-install: true
```
Other configurations can be passed and used as command line args. Examples are CMake build arguments, like the build type or the verb configurations for the event handlers:
```yaml
# my_workspace/defaults.yaml
build:
cmake-args: ["-DCMAKE_BUILD_TYPE=Release"]
event-handlers: ["console_direct+"]
```
### Custom rosdep script
Your ROS application may need nonstandard rosdep rules.
If so, you have the option to provide a script to be run before the `rosdep install` command collects keys.
This script has access to the "Custom data directory" same as the "Custom setup script", see the following sections. If you need any extra files for setting up rosdep, they can be accessed via this custom data directory.
Note that:
1. Rosdeps for melodic collected in an Ubuntu focal container for all other ROS distros
rosdeps collected in an Ubuntu Focal container, so scripts must be compatible with that
Here is an example script for an application that adds extra rosdep source lists
```bash
cp ./custom-data/rosdep-rules/raspicam-node.yaml /etc/ros/rosdep/custom-rules/raspicam-node.yaml
echo "yaml file:/etc/ros/rosdep/custom-rules/raspicam-node.yaml" > /etc/ros/rosdep/sources.list.d/22-raspicam-node.list
```
Tool invocation for this example:
```bash
ros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \
--custom-rosdep-script /path/to/rosdep-script.sh \
--custom-data-dir /arbitrary/local/directory
```
### Custom setup script
Your ROS application may have build needs that aren't covered by `rosdep install`.
If this is the case (for example you need to add extra apt repos), use the option `--custom-setup-script` to execute arbitrary code in the sysroot container.
The path provided may be absolute, or relative to the current directory.
Keep in mind
* It's up to the user to determine whether the script is compatible with chosen base platform
* Make sure to specify non-interactive versions of commands, for example `apt-get install -y`, or the script may hang waiting for input
* You cannot make any assumptions about the state of the apt cache, so run `apt-get update` before installing packages
* The script runs as root user in the container, so you don't need `sudo`
Below is an example script for an application that installs some custom Raspberry Pi libraries.
```bash
apt-get update
apt-get install -y software-properties-common
# Install Raspberry Pi library that we have not provided a rosdep rule for
add-apt-repository ppa:rpi-distro/ppa
apt-get install -y pigpio
```
Additionally, a custom setup script may control the build environment by populating the `/custom-data/setup.bash` file which will be sourced before building.
### Custom post-build script
You may want to perform arbitrary post-processing on your build outputs, in the event of a sucessful build - use `--custom-post-build-script` for this.
Keep in mind that it is run at the root of the built workspace.
Following is an example setup that allows a user to run [colcon bundle](https://github.com/colcon/colcon-bundle) to create a portable bundle of the cross-compiled application.
Here are the contents of `./postbuild.sh`
```bash
#!/bin/bash
set -eux
apt-get update
apt-get install -y wget
wget http://packages.osrfoundation.org/gazebo.key -O - | apt-key add -
apt-get install -y python3-apt
pip3 install -u setuptools pip
pip3 install -U colcon-ros-bundle
colcon bundle \
--build-base build_"${TARGET_ARCH}" \
--install-base install_"${TARGET_ARCH}" \
--bundle-base bundle_"${TARGET_ARCH}"
```
Now, run
```
ros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \
--custom-post-build-script ./postbuild.sh
```
After the build completes, you should see the bundle outputs in `bundle_aarch64`
### Custom data directory
Your custom setup or rosdep script (see preceding sections) may need some data that is not otherwise accessible.
For example, you need to copy some precompiled vendor binaries to a specific location, or provide custom rosdep rules files.
For this use case, you can use the option `--custom-data-dir` to point to an arbitrary path.
The sysroot build copies this directory into the build environment, where it's available for use by your custom setup script at `./custom-data/`.
**Example:**
Custom data directory (`/arbitrary/local/directory`)
```
/arbitrary/local/directory/
+-- my-data/
| +-- something.txt
```
Setup Script (`/path/to/custom-setup.sh`)
```bash
#!/bin/bash
cat custom-data/something.txt
```
Tool invocation:
```bash
ros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \
--custom-setup-script /path/to/custom-setup.sh \
--custom-data-dir /arbitrary/local/directory
```
Now, during the sysroot creation process, you should see the contents of `something.txt` printed during the execution of the custom script.
NOTE: for trivial text files, as in the preceding example, you could have created those files fully within the `--custom-setup-script`. But for large or binary data such as precompiled libraries, this feature comes to the rescue.
### Runtime Image
`ros_cross_compile` can optionally create and tag a Docker image that contains the build output and its runtime dependencies.
The argument `--runtime-tag` takes a single value, which is the tag used for the output image.
```
OUTPUT_IMAGE=my_registry/image_name:image_tag
ros_cross_compile $workspace --runtime-tag $OUTPUT_IMAGE
```
One way to deploy this image is to push it to a registry, from where it can be pulled onto a target platform
```
docker push $OUTPUT_IMAGE
```
The image contains any necessary emulation binaries to run locally if desired for smoke testing.
```
docker run -it $OUTPUT_IMAGE
# In the shell inside the running container, the setup is already sourced for the default entrypoint
ros2 launch my_package my.launch.py
```
Note: Currently this feature is a thin layer on top of the image used for building, so it is not a fully minimal image - it contains build tools, build dependencies, and test dependencies in addition to the necessary runtime dependencies.
Future work is planned to slim down this output image to a properly minimal runtime.
This work is tracked in https://github.com/ros-tooling/cross_compile/issues/263.
## Tutorial
For a new user, this section walks you through a representative use case, step by step.
This tutorial demonstrates how to cross-compile the [ROS 2 Demo Nodes](https://github.com/ros-tooling/demos) against ROS 2 Foxy, to run on an ARM64 Ubuntu system.
You can generalize this workflow to use on any workspace for your project.
NOTE: this tutorial assumes a Debian-based (including Ubuntu) Linux distribution as the host platform.
### Creating a simple source workspace
Create a directory for your workspace and checkout the sources
```
mkdir -p cross_compile_ws/src
cd cross_compile_ws
git clone -b foxy https://github.com/ros2/demos src/demos
```
Create a file `defaults.yaml` in this directory with the following contents. This file narrows down the set of built packages, rather than building every single package in the source repository. This file is optional - see preceding section "Package Selection and Build Customization
" for more information.
```
build:
# only build the demo_nodes_cpp package, to save time building all of the demos
packages-up-to:
- demo_nodes_cpp
# make a merged install space, which is easier to distribute
merge-install: true
# add some output for readability
event-handlers:
- console_cohesion+
- console_package_list+
```
### Running the cross-compilation
```bash
ros_cross_compile . --rosdistro foxy --arch aarch64 --os ubuntu --colcon-defaults ./defaults.yaml
```
Here is a detailed look at the arguments passed to the script (`ros_cross_compile -h` will print all valid choices for each option):
* `.`
* The first argument to `ros_cross_compile` is the directory of the workspace to be built. This could be any relative or absolute path, in this case it's just `.`, the current working directory.
* `--rosdistro foxy`
* You may specify either a ROS and ROS 2 distribution by name, for example `noetic` (ROS) or `galactic` (ROS 2).
* `--arch aarch64`
* Target the ARMv8 / ARM64 / aarch64 architecture (which are different names for effectively the same thing).
* `--os ubuntu`
* The target OS is Ubuntu - the tool chooses the OS version automatically based on the ROS Distro's target OS. In this case for ROS 2 Foxy - Ubuntu 20.04 Focal Fossa.
### Outputs of the build
Run the following command
```bash
ls cross_compile_ws
```
If the build succeeded, the directory looks like this:
```
build_aarch64/
cc_internals/
defaults.yaml
install_aarch64/
log/
src/
```
* The created directory `install_aarch64` is the installation of your ROS workspace for your target architecture.
* `cc_internals` is used by `ros_cross_compile` to cache artifacts between builds - as a user you will not need to inspect it
You can verify that the build created binaries for the target architecture (note "ARM aarch64" in below output. Your `sha1` may differ):
```bash
$ file install_aarch64/demo_nodes_cpp/lib/demo_nodes_cpp/talker
install_aarch64/demo_nodes_cpp/lib/demo_nodes_cpp/talker: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=f086db477d6f5f919414d63911366077f1051b80, for GNU/Linux 3.7.0, not stripped
```
### Using the build on a target platform
Copy `install_aarch64` onto the target system into a location of your choosing. It contains the binaries for _your_ workspace.
If your workspace has any dependencies that are outside the source tree - that is, if `rosdep` had anything to install during the build - then you still need to install these dependencies on the target system.
Note first: if you need `rosdep` to install packages via the package manager, then your system will need its package manager sources (APT for Ubuntu). See [Setup Sources](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html#setup-sources) portion of ROS 2 installation instructions for an example of how to do this on Ubuntu.
```bash
# Run this on the target system, which must have rosdep already installed
# remember `rosdep init`, `rosdep update`, `apt-get update` if you need them
rosdep install --from-paths install_aarch64/share --ignore-src --rosdistro foxy -y
```
Now you may use the ROS installation as you would on any other system
```bash
source install_aarch64/setup.bash
ros2 run demo_nodes_cpp talker
# and in a different shell
ros2 run demo_nodes_cpp listener
```
## Troubleshooting
If you are running in docker with `/var/run/docker.sock` mounted and see the following error:
> No src/ directory found at /ws, did you remember to mount your workspace?
You may need to try running in docker-in-docker. This approach is demonstrated to work in gitlab-ci with a privileged runner and the following `gitlab.yml` as an example:
```yaml
image: teracy/ubuntu:18.04-dind-19.03.3
services:
- docker:19.03.3-dind
variables:
# Disable TLS or we get SSLv1 errors. We shouldn't need this since we mount the /certs volume.
# We also need to connect to the docker daemon via DOCKER_HOST.
DOCKER_TLS_CERTDIR: ""
DOCKER_HOST: tcp://docker:2375
build-stuff:
stage: build
tags:
- ros
before_script:
# Install packages
- apt update
- apt install -qq -y qemu-user-static python3-pip rsync
# Set up the workspace
- cd ${CI_PROJECT_DIR}/..
- rm -rf cross_compile_ws/src
- mkdir -p cross_compile_ws/src
- cp -r ${CI_PROJECT_DIR} cross_compile_ws/src/
- rsync -a ${CI_PROJECT_DIR}/../cross_compile_ws ${CI_PROJECT_DIR}
- cd ${CI_PROJECT_DIR}
# Install ros_cross_compile
- pip3 install ros_cross_compile
script:
- ros_cross_compile cross_compile_ws --arch aarch64 --os ubuntu --rosdistro melodic
artifacts:
paths:
- $CI_PROJECT_DIR/cross_compile_ws/install_aarch64
expire_in: 1 week
```
## License
This library is licensed under the Apache 2.0 License.
## Build status
| ROS 2 Release | Branch Name | Development | Source Debian Package | X86-64 Debian Package | ARM64 Debian Package | ARMHF Debian package |
| ------------- | --------------- | ----------- | --------------------- | --------------------- | -------------------- | -------------------- |
| Latest | `master` | [](https://github.com/ros-tooling/cross_compile/actions) | N/A | N/A | N/A | N/A |
| Foxy | `foxy-devel` | [](http://build.ros2.org/job/Ddev__cross_compile__ubuntu_focal_amd64) | [](http://build.ros2.org/job/Dsrc_uB__cross_compile__ubuntu_focal__source) | [](http://build.ros2.org/job/Dbin_uB64__cross_compile__ubuntu_focal_amd64__binary) | N/A | N/A |
[ros2_dev_setup]: https://index.ros.org/doc/ros2/Installation/Latest-Development-Setup/
Raw data
{
"_id": null,
"home_page": "https://github.com/ros-tooling/cross_compile",
"name": "ros-cross-compile",
"maintainer": "ROS Tooling Working Group",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "ros-tooling@googlegroups.com",
"keywords": "ROS,ROS2",
"author": "ROS Tooling Working Group",
"author_email": "ros-tooling@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/cd/02/0cb6c754c09dd2b6ad573adf86ea4d1568279530e499ccd4a46684fae47b/ros_cross_compile-0.10.0.tar.gz",
"platform": null,
"description": "## Notice: This repository is deprecated. It is outdated and will not be supported anymore.\nIt is recommended to use a native cross-compilation method, which can be up to 8 times faster.\nSee details in this ROS Discourse discussion:\nhttps://discourse.ros.org/t/call-for-help-maintainership-of-the-ros-cross-compile-tool/26511\n\n# ROS / ROS 2 Cross Compile Tool\n\n\n[](https://cross_compile.readthedocs.io/en/latest/?badge=latest)\n\nA tool to automate compiling ROS and ROS 2 workspaces to non-native architectures.\n\n:construction: `ros_cross_compile` relies on running emulated builds\nusing QEmu, #69 tracks progress toward enabling cross-compilation.\n\n\n## Supported targets\n\nThis tool supports compiling a workspace for all combinations of the following:\n\n* Architecture: `armhf`, `aarch64`, `x86_64`\n* ROS Distro\n * ROS: `melodic`, `noetic`\n * ROS 2: `foxy`, `galactic`, `humble`, `rolling`\n* OS: `Ubuntu`, `Debian`\n\nNOTE: ROS 2 supports Debian only as a Tier 3 platform.\nThis means that there are not `apt` repositories available for the ROS 2 Core on this platform.\nBecause of that, when targeting Debian for a ROS 2 workspace, you must also include the source for the core as well.\nIt is recommended to use a release branch of `ros2.repos` from https://github.com/ros2/ros2 to do so, rather than `master`, so that you are not affected by development branch bugs and API changes.\n\n## Supported hosts\n\nThis tool officially supports running on the following host systems.\nNote that many others likely work, but these are being thoroughly tested.\n\n* Ubuntu 20.04 Focal\n* OSX Mojave\n\n## Installation\n\n### Prerequisites\n\nThis tool requires that you have already installed\n* [Docker](https://docs.docker.com/install/)\n * Follow the instructions to add yourself to the `docker` group as well, so you can run containers as a non-root user\n* Python 3.7 or higher\n\nIf you are using a Linux host, you must also install QEmu (Docker for OSX performs emulation automatically):\n\n```sh\nsudo apt-get install qemu-user-static\n```\n\n### Installing ros_cross_compile\n\nTo install the stable release,\n\n```sh\npip3 install ros_cross_compile\n```\n\nIf you would like the latest nightly build, you can get it from Test PyPI\n\n```sh\npip3 install --index-url https://test.pypi.org/simple/ ros_cross_compile\n```\n\n## How it works, high level\n\n1. Collect dependencies\n 1. Create a Docker image that has `rosdep`\n 1. Run the `rosdep` image against your target workspace to output a script that describes how to install its dependencies\n1. Create \"sysroot image\" that has everything needed for building target workspace\n 1. Use a base image for the target architecture (aarch64, armhf, ...)\n 1. Install build tools (compilers, cmake, colcon, etc)\n 1. Run the dependency installer script collected in Step 1 (if dependency list hasn't changed since last run, this uses the Docker cache)\n1. Build\n 1. Runs the \"sysroot image\" using QEmu emulation\n 1. `colcon build`\n1. (Optional) Create runtime image\n 1. Creates a docker image that can be used on the target platform to run the build. See \"Runtime Image\" section.\n\n## Usage\n\nThis package installs the `ros_cross_compile` command.\nThe command's first argument is the path to your ROS workspace.\n\nHere is a simple invocation for a standard workflow.\n\n```bash\nros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu --rosdistro foxy\n```\n\nFor information on all available options, run `ros_cross_compile -h`.\nSee the following sections for information on the more complex options.\n\n### Package Selection and Build Customization\n\nTo choose which packages to install dependencies for, this tool runs `colcon list` on your workspace.\nTo build, it runs `colcon build`.\n\nYou can provide arbitrary arguments to these commands via the [colcon `defaults.yaml`](https://colcon.readthedocs.io/en/released/user/configuration.html#defaults-yaml).\n\nYou can either specify the name of this file via `ros_cross_compile --colcon-defaults /path/to/defaults.yaml`, or if not specified, a file called `defaults.yaml` will be used if present.\n\nFor example, there are repositories checked out in your workspace that contain packages that are not needed for your application - some repos provide many packages and you may only want one!\nIn this scenario there is a \"bringup\" package that acts as the entry point to your application:\n\n```yaml\n# my_workspace/defaults.yaml\nlist:\n # only install dependencies for source packages that my package depends on\n packages-up-to: [my_application_bringup]\nbuild:\n # only build up to my package\n packages-up-to: [my_application_bringup]\n # example of a boolean commandline argument\n merge-install: true\n```\n\nOther configurations can be passed and used as command line args. Examples are CMake build arguments, like the build type or the verb configurations for the event handlers:\n\n```yaml\n# my_workspace/defaults.yaml\nbuild:\n cmake-args: [\"-DCMAKE_BUILD_TYPE=Release\"]\n event-handlers: [\"console_direct+\"]\n```\n\n### Custom rosdep script\n\nYour ROS application may need nonstandard rosdep rules.\nIf so, you have the option to provide a script to be run before the `rosdep install` command collects keys.\n\nThis script has access to the \"Custom data directory\" same as the \"Custom setup script\", see the following sections. If you need any extra files for setting up rosdep, they can be accessed via this custom data directory.\n\nNote that:\n1. Rosdeps for melodic collected in an Ubuntu focal container for all other ROS distros \n rosdeps collected in an Ubuntu Focal container, so scripts must be compatible with that\n\nHere is an example script for an application that adds extra rosdep source lists\n\n```bash\ncp ./custom-data/rosdep-rules/raspicam-node.yaml /etc/ros/rosdep/custom-rules/raspicam-node.yaml\necho \"yaml file:/etc/ros/rosdep/custom-rules/raspicam-node.yaml\" > /etc/ros/rosdep/sources.list.d/22-raspicam-node.list\n```\n\nTool invocation for this example:\n\n```bash\nros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \\\n --custom-rosdep-script /path/to/rosdep-script.sh \\\n --custom-data-dir /arbitrary/local/directory\n```\n\n### Custom setup script\n\nYour ROS application may have build needs that aren't covered by `rosdep install`.\nIf this is the case (for example you need to add extra apt repos), use the option `--custom-setup-script` to execute arbitrary code in the sysroot container.\n\nThe path provided may be absolute, or relative to the current directory.\n\nKeep in mind\n* It's up to the user to determine whether the script is compatible with chosen base platform\n* Make sure to specify non-interactive versions of commands, for example `apt-get install -y`, or the script may hang waiting for input\n* You cannot make any assumptions about the state of the apt cache, so run `apt-get update` before installing packages\n* The script runs as root user in the container, so you don't need `sudo`\n\nBelow is an example script for an application that installs some custom Raspberry Pi libraries.\n\n```bash\napt-get update\napt-get install -y software-properties-common\n\n# Install Raspberry Pi library that we have not provided a rosdep rule for\nadd-apt-repository ppa:rpi-distro/ppa\napt-get install -y pigpio\n```\n\nAdditionally, a custom setup script may control the build environment by populating the `/custom-data/setup.bash` file which will be sourced before building.\n\n### Custom post-build script\n\nYou may want to perform arbitrary post-processing on your build outputs, in the event of a sucessful build - use `--custom-post-build-script` for this.\nKeep in mind that it is run at the root of the built workspace.\n\nFollowing is an example setup that allows a user to run [colcon bundle](https://github.com/colcon/colcon-bundle) to create a portable bundle of the cross-compiled application.\n\nHere are the contents of `./postbuild.sh`\n\n```bash\n#!/bin/bash\nset -eux\n\napt-get update\napt-get install -y wget\nwget http://packages.osrfoundation.org/gazebo.key -O - | apt-key add -\n\napt-get install -y python3-apt\npip3 install -u setuptools pip\npip3 install -U colcon-ros-bundle\n\ncolcon bundle \\\n --build-base build_\"${TARGET_ARCH}\" \\\n --install-base install_\"${TARGET_ARCH}\" \\\n --bundle-base bundle_\"${TARGET_ARCH}\"\n```\n\nNow, run\n\n```\nros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \\\n --custom-post-build-script ./postbuild.sh\n```\n\nAfter the build completes, you should see the bundle outputs in `bundle_aarch64`\n\n\n### Custom data directory\n\nYour custom setup or rosdep script (see preceding sections) may need some data that is not otherwise accessible.\nFor example, you need to copy some precompiled vendor binaries to a specific location, or provide custom rosdep rules files.\nFor this use case, you can use the option `--custom-data-dir` to point to an arbitrary path.\nThe sysroot build copies this directory into the build environment, where it's available for use by your custom setup script at `./custom-data/`.\n\n**Example:**\n\nCustom data directory (`/arbitrary/local/directory`)\n```\n/arbitrary/local/directory/\n+-- my-data/\n| +-- something.txt\n```\n\nSetup Script (`/path/to/custom-setup.sh`)\n\n```bash\n#!/bin/bash\ncat custom-data/something.txt\n```\n\nTool invocation:\n\n```bash\nros_cross_compile /path/to/my/workspace --arch aarch64 --os ubuntu \\\n --custom-setup-script /path/to/custom-setup.sh \\\n --custom-data-dir /arbitrary/local/directory\n```\n\nNow, during the sysroot creation process, you should see the contents of `something.txt` printed during the execution of the custom script.\n\nNOTE: for trivial text files, as in the preceding example, you could have created those files fully within the `--custom-setup-script`. But for large or binary data such as precompiled libraries, this feature comes to the rescue.\n\n\n### Runtime Image\n\n`ros_cross_compile` can optionally create and tag a Docker image that contains the build output and its runtime dependencies.\n\nThe argument `--runtime-tag` takes a single value, which is the tag used for the output image.\n\n```\nOUTPUT_IMAGE=my_registry/image_name:image_tag\nros_cross_compile $workspace --runtime-tag $OUTPUT_IMAGE\n```\n\nOne way to deploy this image is to push it to a registry, from where it can be pulled onto a target platform\n\n```\ndocker push $OUTPUT_IMAGE\n```\n\nThe image contains any necessary emulation binaries to run locally if desired for smoke testing.\n\n```\ndocker run -it $OUTPUT_IMAGE\n# In the shell inside the running container, the setup is already sourced for the default entrypoint\nros2 launch my_package my.launch.py\n```\n\nNote: Currently this feature is a thin layer on top of the image used for building, so it is not a fully minimal image - it contains build tools, build dependencies, and test dependencies in addition to the necessary runtime dependencies.\nFuture work is planned to slim down this output image to a properly minimal runtime.\nThis work is tracked in https://github.com/ros-tooling/cross_compile/issues/263.\n\n\n## Tutorial\n\nFor a new user, this section walks you through a representative use case, step by step.\n\nThis tutorial demonstrates how to cross-compile the [ROS 2 Demo Nodes](https://github.com/ros-tooling/demos) against ROS 2 Foxy, to run on an ARM64 Ubuntu system.\nYou can generalize this workflow to use on any workspace for your project.\n\nNOTE: this tutorial assumes a Debian-based (including Ubuntu) Linux distribution as the host platform.\n\n### Creating a simple source workspace\n\nCreate a directory for your workspace and checkout the sources\n\n```\nmkdir -p cross_compile_ws/src\ncd cross_compile_ws\ngit clone -b foxy https://github.com/ros2/demos src/demos\n```\n\nCreate a file `defaults.yaml` in this directory with the following contents. This file narrows down the set of built packages, rather than building every single package in the source repository. This file is optional - see preceding section \"Package Selection and Build Customization\n\" for more information.\n\n```\nbuild:\n # only build the demo_nodes_cpp package, to save time building all of the demos\n packages-up-to:\n - demo_nodes_cpp\n # make a merged install space, which is easier to distribute\n merge-install: true\n # add some output for readability\n event-handlers:\n - console_cohesion+\n - console_package_list+\n\n```\n\n### Running the cross-compilation\n\n```bash\nros_cross_compile . --rosdistro foxy --arch aarch64 --os ubuntu --colcon-defaults ./defaults.yaml\n```\n\nHere is a detailed look at the arguments passed to the script (`ros_cross_compile -h` will print all valid choices for each option):\n\n* `.`\n * The first argument to `ros_cross_compile` is the directory of the workspace to be built. This could be any relative or absolute path, in this case it's just `.`, the current working directory.\n* `--rosdistro foxy`\n * You may specify either a ROS and ROS 2 distribution by name, for example `noetic` (ROS) or `galactic` (ROS 2).\n* `--arch aarch64`\n * Target the ARMv8 / ARM64 / aarch64 architecture (which are different names for effectively the same thing).\n* `--os ubuntu`\n * The target OS is Ubuntu - the tool chooses the OS version automatically based on the ROS Distro's target OS. In this case for ROS 2 Foxy - Ubuntu 20.04 Focal Fossa.\n\n### Outputs of the build\n\nRun the following command\n\n```bash\nls cross_compile_ws\n```\n\nIf the build succeeded, the directory looks like this:\n\n```\nbuild_aarch64/\ncc_internals/\ndefaults.yaml\ninstall_aarch64/\nlog/\nsrc/\n```\n\n* The created directory `install_aarch64` is the installation of your ROS workspace for your target architecture.\n* `cc_internals` is used by `ros_cross_compile` to cache artifacts between builds - as a user you will not need to inspect it\n\nYou can verify that the build created binaries for the target architecture (note \"ARM aarch64\" in below output. Your `sha1` may differ):\n\n```bash\n$ file install_aarch64/demo_nodes_cpp/lib/demo_nodes_cpp/talker\ninstall_aarch64/demo_nodes_cpp/lib/demo_nodes_cpp/talker: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=f086db477d6f5f919414d63911366077f1051b80, for GNU/Linux 3.7.0, not stripped\n```\n\n### Using the build on a target platform\n\nCopy `install_aarch64` onto the target system into a location of your choosing. It contains the binaries for _your_ workspace.\n\nIf your workspace has any dependencies that are outside the source tree - that is, if `rosdep` had anything to install during the build - then you still need to install these dependencies on the target system.\n\nNote first: if you need `rosdep` to install packages via the package manager, then your system will need its package manager sources (APT for Ubuntu). See [Setup Sources](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html#setup-sources) portion of ROS 2 installation instructions for an example of how to do this on Ubuntu.\n\n```bash\n# Run this on the target system, which must have rosdep already installed\n# remember `rosdep init`, `rosdep update`, `apt-get update` if you need them\nrosdep install --from-paths install_aarch64/share --ignore-src --rosdistro foxy -y\n```\n\nNow you may use the ROS installation as you would on any other system\n\n```bash\nsource install_aarch64/setup.bash\nros2 run demo_nodes_cpp talker\n\n# and in a different shell\nros2 run demo_nodes_cpp listener\n```\n\n## Troubleshooting\n\nIf you are running in docker with `/var/run/docker.sock` mounted and see the following error:\n> No src/ directory found at /ws, did you remember to mount your workspace?\n\nYou may need to try running in docker-in-docker. This approach is demonstrated to work in gitlab-ci with a privileged runner and the following `gitlab.yml` as an example:\n\n```yaml\nimage: teracy/ubuntu:18.04-dind-19.03.3\n\nservices:\n - docker:19.03.3-dind\n\nvariables:\n # Disable TLS or we get SSLv1 errors. We shouldn't need this since we mount the /certs volume.\n # We also need to connect to the docker daemon via DOCKER_HOST.\n DOCKER_TLS_CERTDIR: \"\"\n DOCKER_HOST: tcp://docker:2375\n\nbuild-stuff:\n stage: build\n tags:\n - ros\n before_script:\n # Install packages\n - apt update\n - apt install -qq -y qemu-user-static python3-pip rsync\n\n # Set up the workspace\n - cd ${CI_PROJECT_DIR}/..\n - rm -rf cross_compile_ws/src\n - mkdir -p cross_compile_ws/src\n - cp -r ${CI_PROJECT_DIR} cross_compile_ws/src/\n - rsync -a ${CI_PROJECT_DIR}/../cross_compile_ws ${CI_PROJECT_DIR}\n - cd ${CI_PROJECT_DIR}\n\n # Install ros_cross_compile\n - pip3 install ros_cross_compile\n script:\n - ros_cross_compile cross_compile_ws --arch aarch64 --os ubuntu --rosdistro melodic\n artifacts:\n paths:\n - $CI_PROJECT_DIR/cross_compile_ws/install_aarch64\n expire_in: 1 week\n```\n\n## License\n\nThis library is licensed under the Apache 2.0 License.\n\n## Build status\n\n| ROS 2 Release | Branch Name | Development | Source Debian Package | X86-64 Debian Package | ARM64 Debian Package | ARMHF Debian package |\n| ------------- | --------------- | ----------- | --------------------- | --------------------- | -------------------- | -------------------- |\n| Latest | `master` | [](https://github.com/ros-tooling/cross_compile/actions) | N/A | N/A | N/A | N/A |\n| Foxy | `foxy-devel` | [](http://build.ros2.org/job/Ddev__cross_compile__ubuntu_focal_amd64) | [](http://build.ros2.org/job/Dsrc_uB__cross_compile__ubuntu_focal__source) | [](http://build.ros2.org/job/Dbin_uB64__cross_compile__ubuntu_focal_amd64__binary) | N/A | N/A |\n\n\n[ros2_dev_setup]: https://index.ros.org/doc/ros2/Installation/Latest-Development-Setup/\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "A tool to build ROS workspaces for various target architectures and platforms.",
"version": "0.10.0",
"split_keywords": [
"ros",
"ros2"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4ea23c92f93270007ef520df15cdd378",
"sha256": "f9526174635f99ae026542e07b37cb51c4b4aa0051d96c9714e7d257990e7ef3"
},
"downloads": -1,
"filename": "ros_cross_compile-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ea23c92f93270007ef520df15cdd378",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 4276510,
"upload_time": "2022-12-12T15:30:29",
"upload_time_iso_8601": "2022-12-12T15:30:29.232935Z",
"url": "https://files.pythonhosted.org/packages/f7/d9/cea95fe5c710f883d5c41277c6a5c79a10efdb4cd70ea3a12354e0eb07a1/ros_cross_compile-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "f64f1bd9e8f85e91c35ff0b116da6954",
"sha256": "0d55cb2fd9220de86f5719c5df675ed0a1a88be180495ec6ec57f2cb7efd4cfe"
},
"downloads": -1,
"filename": "ros_cross_compile-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "f64f1bd9e8f85e91c35ff0b116da6954",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4257318,
"upload_time": "2022-12-12T15:30:35",
"upload_time_iso_8601": "2022-12-12T15:30:35.191175Z",
"url": "https://files.pythonhosted.org/packages/cd/02/0cb6c754c09dd2b6ad573adf86ea4d1568279530e499ccd4a46684fae47b/ros_cross_compile-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-12 15:30:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ros-tooling",
"github_project": "cross_compile",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "ros-cross-compile"
}
JSON
