Pyrex

Containerize your bitbake

Requirements

Pyrex has the following system requirements:

• docker or podman
• python 3.6 or later

NOTE: Pyrex will not function properly if docker is installed as snap since it bind mounts files that the snap is not allowed to access. Please install a non-snap version of docker, e.g. apt install docker.io

Quickstart Guide (default layout)

Use this quickstart guide if your project uses the default (poky-style) layout where bitbake and layers are subdirectories of oe-core:

# Clone down Pyrex
git clone https://github.com/garmin/pyrex.git meta-pyrex

# Create the pyrex environment initialization script symbolic link
ln -s meta-pyrex/pyrex-init-build-env

# Create a default pyrex.ini config file
meta-pyrex/mkconfig > ./pyrex.ini

# Set PYREXCONFFILE to the location of the newly created config file
PYREXCONFFILE=./pyrex.ini

# Initialize the build environment
. pyrex-init-build-env

# Everything is setup. OpenEmbedded build commands (e.g. `bitbake`) will now
# run in Pyrex

Quickstart Guide (alternate layout)

Use this quickstart guide if your project uses a different layout where bitbake and oe-core are disjointed. In the example, it is assumed that oe-core and bitbake are both subdirectories of the current working directory, so you will need to change it to match your actual layout:

# Clone down Pyrex
git clone https://github.com/garmin/pyrex.git pyrex

# Create the pyrex environment initialization script symbolic link
ln -s pyrex/pyrex-init-build-env

# Create a default pyrex.ini config file
pyrex/mkconfig > ./pyrex.ini

# Set PYREXCONFFILE to the location of the newly created config file
PYREXCONFFILE=./pyrex.ini

# Tell Pyrex where bitbake and oe-core live
BITBAKEDIR=$(pwd)/bitbake
OEROOT=$(pwd)/oe-core

# Initialize the build environment
. pyrex-init-build-env

# Everything is setup. OpenEmbedded build commands (e.g. `bitbake`) will now
# run in Pyrex

What is Pyrex?

At its core, Pyrex is an attempt to provide a consistent environment in which developers can run Yocto and bitbake commands. Pyrex is targeted at development teams who are doing interactive development with Yocto (although, Pyrex doesn't aim to be a full development environment, see below), and as such makes some different design decisions than other containerized solutions like [CROPS][].

Pyrex works by setting up a container image in which to run commands, then "trapping" the commands such that when the user executes the command in their shell, it is (hopefully) transparently executed inside the container instead.

What isn't Pyrex?

Pyrex isn't designed to be a complete Yocto IDE. The intention of Pyrex is not to run vim, emacs etc. and faithfully reproduce your development PC environment while also creating a reproducible build environment. Instead, Pyrex is designed to allow developers the freedom to use whatever tools and editors they want, run whatever distro they want, and configure their system how they want, but still run the actual Yocto build commands in a controlled environment.

Note that there are some provisions in the Pyrex image for running utilities tied into bitbake that can't easily be run any other way. For example, the commands bitbake -c devshell, bitbake -c devpyshell, and bitbake -c menuconfig (or any other commands that run in [OE_TERMINAL][]) are all supported since there is no other way to easily run them outside the bitbake environment.

Note that because of this philosophy, it may not be possible to run some graphical tools such as hob when using Pyrex.

When should you use Pyrex?

There are a number of situations where Pyrex can be very useful:

1. You have multiple developers building on development machines with different setups (e.g. different distros). In these cases, Pyrex can help ensure that builds are consistent between different developers.
2. You have to build multiple different versions of Yocto. Sadly, it isn't possible to always use the latest and greatest version of Yocto, or even to use the same version of Yocto for all projects within a group. In these cases, Pyrex can be helpful because it will easily allow the different versions to use a container image that suits them without the developers having to think about it too much.

When should you not use Pyrex?

There are some situations where Pyrex may not always make sense:

1. You aren't doing development. If all you need is a reproducible container to build Yocto in (for example, you just want to try out a build to see what Yocto is like), Pyrex is probably not for you. Pyrex has some amount of setup overhead and because of its focus doesn't isolate the container as much as some other solutions. In these cases [CROPS][] is probably a better solution.
2. You are the lone developer. Pyrex is primarily intended to ensure that a group of developers (e.g. a corporate or other group environment) working in Yocto will get consistent builds, regardless of their individual machine setups. This probably isn't much of a concern for an individual.

Using Pyrex

Setup

Using vanilla Pyrex with a stock version of Yocto is pretty straight forward. First, add Pyrex to your project. There are many ways of doing this, but for this example, we will just clone it into a subdirectory of [poky][].

git clone https://github.com/garmin/pyrex.git meta-pyrex

NOTE: Cloning down Pyrex with the name meta-pyrex can be helpful if you want to put it as a subdirectory of poky, since poky's .gitignore will ignore all directories that start with 'meta-'

Next, you will need to create the environment setup script to initialize the Pyrex build environment. This script is equivalent to the oe-init-build-env script provided by poky and should be used by your developers in place of that script when they want to use Pyrex. There are a few ways to create this script, but all of them eventually must source the pyrex-init-build-env script. By default, this script assumes that you will create a symbolic link (named whatever you want) that lives alongside the oe-init-build-env script and points to pyrex-init-build-env. You can do this in our example like so:

ln -s meta-pyrex/pyrex-init-build-env

Alternatively, if you want your script to live somewhere else, or use a non-standard layout, you can write your own environment init script that tells pyrex-init-build-env where everything lives. A crude example script might look like:

# Paths that should be bound into the container. If unspecified, defaults to
# the parent directory of the sourced pyrex-init-build-env script, before
# it is resolved as a symbolic link. You may need to override the default if
# your bitbake directory, build directory, or any of your layer directories are
# not children of the default (and thus, wouldn't be bound into the container).
PYREX_CONFIG_BIND="$(pwd)"

# The path to the build init script. If unspecified, defaults to
# "$OEROOT/oe-init-build-env" or "$(pwd)/oe-init-build-env"
PYREX_OEINIT="$(pwd)/oe-init-build-env"

# The location of Pyrex itself. If not specified, pyrex-init-build-env will
# assume it is the directory where it is currently located (which is probably
# correct)
PYREX_ROOT="$(pwd)/meta-pyrex"

# Alternatively, if it is desired to always use a fixed config file that users
# can't change, set the following:
#PYREXCONFFILE="$(pwd)/pyrex.ini"

# Source the core pyrex environment script. Note that you must pass the
# arguments
. $(pwd)/meta-pyrex/pyrex-init-build-env "$@"

NOTE: While it might be tempting to combine all of these into a one-liner like PYREXCONFFILE="..." . $(pwd)/meta-pyrex/pyrex-init-build-env "$@", they must be specified on separate lines to remain compatible will all shells (i.e. bash in particular won't keep temporary variables specified in this way)

Configuration

Pyrex is configured using a ini-style configuration file. The location of this file is specified by the PYREXCONFFILE environment variable. This environment variable must be set before the environment is initialized.

If you do not yet have a config file, you can use the mkconfig command to use the default one and assign the PYREXCONFFILE variable in a single command like so:

$ export PYREXCONFFILE=`./meta-pyrex/mkconfig ./pyrex.ini`

The configuration file is the ini file format supported by Python's configparser class, with the following notes:

1. The only allowed comment character is #
2. The only allowed key assignment character is = (e.g. key : value is not supported)
3. Extended interpolation is supported. Thus, you can reference other variables in the form ${section:key}
4. All keys are case sensitive

For more information about specific configuration values, see the default pyrex.ini

Binding directories into the container

In order for bitbake running in the container to be able to build, it must have access to the data and config files from the host system. There are two variables that can be set to specify what is bound into the container, the PYREX_CONFIG_BIND environment variable and the run:bind option specified in the config file. Both variables are a whitespace separated list of host paths that should be bound into the container at the same path (e.g. /foo/bar in the host will be bound to /foo/bar in the container engine).

The PYREX_CONFIG_BIND environment variable is intended to spe