meta-ros: OpenEmbedded Layers for ROS 1 and ROS 2 on Yocto

What meta-ros solves, and who it is for

Building a robot image for an embedded board usually means two build systems that were not designed for each other. ROS expects a normal Linux userland with its own package manager; the Yocto Project builds a root filesystem from BitBake recipes and cross-compiles everything for the target. meta-ros closes that gap by describing ROS packages as OpenEmbedded recipes, so a ROS node becomes just another entry in your image recipe.

The README frames the goal plainly: it "enables developers to create custom, Linux-based robotic systems, taking advantage of capabilities of ROS and the flexibility of the Yocto Project." The audience is therefore narrow and specific. It is for engineers who already maintain a Yocto layer stack and need ROS inside the resulting image, not for someone who wants to run a tutorial node on a laptop. If your deployment target is a board with a fixed, reproducible filesystem, this is the layer set that addresses it. If your target is a desktop or a server with a general-purpose distribution, the layer buys you nothing and costs you a cross-build environment.

How the layers and generated recipes fit together

The repository is not one layer. It is a series. The `meta-ros-common` layer holds recipes shared by every ROS distribution: third-party libraries and tools that ROS depends on, plus ROS-specific image and package group recipes. Each ROS distribution then gets its own sub-directory containing a layer, and inside that layer you find BitBake configuration files describing the distro and which ROS packages may be built.

Most of the individual package recipes are not written by hand. The README states that the project was converted to use recipes generated by superflore, and those generated recipes live in the `recipes-*` directories. When a generated recipe needs a correction, the change goes into a `bbappend` file under `recipes-bbappends` rather than into the generated recipe itself. That split matters in practice: it tells you where to look when a package builds wrongly, and it tells you that regenerating recipes will not silently discard local fixes, because the fixes live in a separate file.

Branching follows the same logic. The `master` branch tracks the Yocto release series currently under development. Branches named after Yocto releases track updates during that release's support lifecycle and have linear history. The `-next` branches hold commits pending merge, and the README warns that their history may be rewritten as patches are tested and revised, so they are not something to pin a product to. The `build` branch carries the mcf tool and the `.mcf` configuration files found in the `files`, `files-contrib` and `files-unsupported` directories. The top-level repository layout matches this: `meta-ros-common/`, `meta-ros1/`, `meta-ros2/`, and per-distro directories such as `meta-ros2-humble/`, `meta-ros2-jazzy/`, `meta-ros2-kilted/`, `meta-ros2-lyrical/` and `meta-ros2-rolling/`.

Installing meta-ros and running a first kas build

The README does not walk through a manual layer checkout. It points to the kas tool as the easiest path, and says the instructions live in the `build` branch at `kas/README.md`. The README's own recommendation is to start with Kirkstone (Yocto Project) combined with Humble (ROS 2).

Because the repository is a set of layers rather than a package you install, there is no single install command. The documented entry point is the kas configuration in that branch. A typical kas invocation looks like the following, where the `.mcf`-derived configuration file supplies the repository list and build settings:

kas build kas/README.md

That command as written is not the real one; treat it as a placeholder only if you have already read `kas/README.md` in the `build` branch, which is where the actual configuration file name and parameters are defined. The README does not reproduce those parameters, so this article cannot either.

What you should expect after a successful build is a Yocto image containing the ROS packages that the selected distro layer declares as buildable. Before that point, the layer list has to include `meta-ros-common` plus the layer for your ROS distribution, and your `bblayers.conf` has to reference them. The README does not document a rollback procedure for a failed build, and it does not list required host packages, so budget time for the usual Yocto host setup that the README leaves to the Yocto Project itself.

The support table is the real constraint

The most useful part of the README is a matrix of end-of-life dates for combinations of Yocto releases and ROS distributions, and it is also the part most likely to rule you out. The table shows Wrynose (LTS) alongside ROS 2 Humble, Jazzy, Kilted and Lyrical, and Scarthgap (LTS) alongside the same distros. Whinlatter, Walnascar and Styhead rows are struck through, meaning those combinations are past their end-of-life dates.

The README states that releases and distros not shown in the table can be presumed unsupported. That is a hard boundary, not a suggestion. The support-level legend explains what the words mean: `full` means the configuration is fully supported; a struck-through value means the configuration is never built and is only updated to fix breaking changes introduced upstream, such as a component's `master` branch being renamed to `main` or `git://` needing to be replaced by `https://`. Two further levels exist: a best-effort configuration has an end-of-life ROS distro or OpenEmbedded release series, so only a best effort is made to have all its packages build, and a contrib configuration has been contributed but is not built.

Read that legend before you plan anything. A package that exists in the layer tree but sits in a best-effort or contrib configuration is not something you should assume will compile for your board. The honest position is that meta-ros supports a bounded set of combinations well and lets the rest decay.

Maintenance status and what upgrading costs you

The repository is not archived, but the last push was on 2015-05-07, and the most recent release listed is v0.2 from the same date. The README content describes a far newer state of the project, including ROS 2 distros such as Jazzy and Lyrical and Yocto releases such as Wrynose and Scarthgap, and it notes that the last official milestone was Milestone 17 on 2022-06-05. Those two pictures do not line up, and anyone evaluating the project has to reconcile them before depending on it.

Upgrade cost follows from the branch model. Moving to a new Yocto release means moving to the branch named after it, and the README says those branches track updates during their support lifecycle with linear history. Because most recipes are generated by superflore rather than hand-written, an upgrade is partly a regeneration exercise plus a review of the `bbappend` files that carry local corrections. The README does not describe a migration procedure between branches, and it does not promise that a `bbappend` written for one branch applies unchanged to the next.

The licence is MIT, and the repository carries a `COPYING.MIT` file at the top level. That covers the layer metadata itself. It says nothing about the licences of the ROS packages, third-party libraries or board support packages that end up in your image; those are separate and are recorded in the individual recipes. This is not legal advice, and a product shipping a Yocto image should have its licence manifest reviewed by someone qualified to do it.

When meta-ros is the wrong tool

If you do not already build with Yocto, meta-ros adds a build system rather than removing one. Standing up an OpenEmbedded environment, cross-toolchain and image configuration to run a few ROS nodes is a large amount of work for a small result, and the README's own getting-started advice assumes you are already in that world.

A second case is a target that the support table does not cover. The README says unlisted combinations can be presumed unsupported, and the struck-through rows show that this is enforced rather than aspirational. Building against an end-of-life Yocto series to get a particular ROS distro puts you in the best-effort category, where the project makes no promise that all packages build.

A third case is a package that the generated recipes skip. The contributing section of the README explicitly lists "adding support for ROS packages that are currently skipped" as a way to help, which is an admission that some packages are not covered. If your application depends on one of them, you are writing and maintaining that recipe yourself, and the layer set is no longer saving you effort for that dependency.

How meta-ros compares with installing ROS directly

The obvious alternative is not another OpenEmbedded layer; it is skipping the layer entirely and installing ROS from its own packages onto a general-purpose Linux distribution. The difference is in what gets built and when.

With meta-ros, ROS packages are compiled from source as part of the image build, cross-compiled for the target, and pinned by recipe version alongside the rest of the root filesystem. The result is one reproducible artifact: the same commit of the layer stack yields the same image, and there is no package manager resolving dependencies on the device at first boot. The cost is build time, a heavier toolchain, and the constraint that everything must have a recipe.

With a direct ROS install, you get the upstream binary packages and the upstream release cadence, and you add or remove nodes on the device without rebuilding an image. The cost is that the device now needs a writable root filesystem, a package manager and network access for updates, and the exact set of installed packages is a property of that device rather than of a build input. For a development workstation or a robot that is serviced over the network, that is usually the better trade. For a shipped product where the filesystem should be read-only and identical across units, the layer approach is the one that gives you that property. The two are not interchangeable, and choosing between them is really a choice about whether the device or the build server owns the package set.

Editorial conclusion

Adopt meta-ros if you are already building a Yocto image and want ROS packages as BitBake recipes rather than a separate ROS install. Do not adopt it if you want ROS on a stock Ubuntu machine, or if your target is a Yocto release the README table does not list as supported. Before committing, verify which branch matches your Yocto release, check the support level for your ROS distro in that branch, and confirm whether the packages you need are among those the generated recipes cover or among the ones the project lists as skipped.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes