MicroROS Build Action

| |

---

This is a GitHub Action for building micro-ROS as a static C library.
This is a Docker container action.

Inputs

Name	Description	Required	Default
microros_dir	Micro-ROS directory. This directory should contain the source directory, the my_colcon.meta, and my_toolchain.cmake files.	Yes	N/A
microros_source_dir	Micro-ROS source directory. The path should be relative to the micro-ROS directory. This directory should contain the micro-ROS setup repository and any extra packages that micro-ROS should be built with.	No	"src"
microros_setup_path	Path to the micro-ROS setup repository. The path should be relative to the micro-ROS source directory.	No	"micro_ros_setup"
environment_setup_script	Path to environment setup script. This script should perform any steps required to set up the environment for building micro-ROS for your specific platform.	No	RP2040 setup script.
clone_microros_setup	Whether to clone the micro-ROS setup repository. Set to "false" if the repository is added as a submodule or otherwise exists at the provided path.	Yes	"true"
colcon_meta_file	Name of the colcon.meta file. This file should be in the micro-ROS directory.	No	"my_colcon.meta"
toolchain_cmake_file	Name of the toolchain file. This file should be in the micro-ROS directory.	No	"my_toolchain.cmake"
extra_build_packages	A space-separated list of packages that are to be built with the library. These packages should be in the micro-ROS source directory. The packages should be in a directory with the same name as the package.	No	""

Outputs

Name	Description
library_build_dir	Relative path to the build directory. The libmicroros.a file and the include directory will be in this directory.

Notes

Some extra notes on configuration and usage.

The Environment Setup Script

The environment setup script, as described above, should setup the environment for building micro-ROS for the specific that you're building micro-ROS for.
This may include installing compilers, SDKs, toolchains, setting environment variables, etc. An example of such a file can be found in the form of the default setup script for the RP2040 (see rp2040_env_setup.sh). This script installs the Pico SDK, along with all other required dependencies.

Full Raspberry Pi Pico Usage Example

To see this action in action (no pun intended) along with the Pico Build Action, take a look at my ROS Robot Project! There you will find this action being used to build micro-ROS for the Raspberry Pi Pico along with the aforementioned Pico Build Action for building the final binaries that can be used on the Pico.

In my ROS Robot Project, I'm using the FreeRTOS kernel to enable multithreading for micro-ROS. Unfortunately, some platform-specific FreeRTOS header files import an autogenerated header from the Pico SDK (version.h). This header is created by the SDK when generating build files. This means that, unless we want to manually copy it in, we have to run the Pico Build Action once before building micro-ROS. We can run Pico Build with the cmake_config_only option set to "true", as we only need the build files to be generated. We will, of course, have to run Pico Build again after building micro-ROS.

This is an incredibly janky solution, but it is the easiest way of doing, unless you want to manually copy the headers in, which is usually not recommended; besides, who wants to do things manually when there's a way to automate it?

No Spaces In Paths

Due to a bug, or rather an oversight, in micro_ros_setup's create_firmware_ws.sh script, you must make sure that there are no spaces in the path to microros_dir. Escaping spaces in the path when passing it to the action does not work as the script uses its present working directory instead of taking the path as an input. I have not tested whether spaces in microros_source_dir or microros_source_dir cause issues, but it's a good idea to avoid spaces in paths altogether.

The Firmware Workspace Creation Script

If you have any extra packages that get built alongside micro-ROS, those packages need to have a firmware workspace creation script located at [PACKAGE DIR]/scripts/create_firmware_ws.sh. This script is executed before building micro-ROS. The build will fail if this script is not found. You can see a generic example of such a script here. This script should be fine for most packages.

Example usage

jobs:
    test_build:
        name: Build example micro-ROS library
        runs-on: ubuntu-latest
        permissions:
            contents: read

        steps:
            - name: Checkout
              uses: actions/checkout@v4
              with:
                  submodules: recursive

            - name: Build MicroROS Library
              id: build
              uses: ./
              with:
                  microros_dir: test_library/libmicroros
                  clone_microros_setup: "true"

Contact

You can contact me via e-mail.
E-mail: samyarsadat@gigawhat.net

If you think that you have found a bug or issue please report it here.

Contributing

Please take a look at CONTRIBUTING.md for contributing.

Credits

Role	Name
Lead Developer	Samyar Sadat Akhavi

Copyright © 2024 Samyar Sadat Akhavi.