flatcar-scripts/PREFIX.md

Prefix - build portable, distro-independent apps

!!! NOTE: Prefix support in the Flatcar SDK is EXPERIMENTAL at this time !!!

Path to stabilisation TODO list

Before prefix build support are considered stable, the below must be implemented:

1. Integrate cb-bootstrap with the Flatcar SDK. Currently, setup_prefix uses cross-boss' cb-bootstrap to set up the prefix environment. Bootstrapping must be fully integrated with the Flatcar SDK before prefix builds are considered stable.
2. Integrate prefix builds with /build/<board> environment and use board cross toolchain. Prefix builds currently use the SDK cross toolchains (/usr/<arch>-gnu/) instead of board toolchains in /build/<board>. Prefix builds must be integrated with the board toolchains and stop using cb-emerge before considered stable.
3. Add prefix wrappers for all portage tools (similar to board wrappers), not just emerge.
4. Add test cases for prefix builds to mantle/kola.

About

Prefix builds let you build and ship applications and all their dependencies in a custom directory. This custom directory is self-contained, all dependencies are included, and binaries are only linked against libraries in the custom directory. The applications' root will be / - i.e. there's no need to chroot into the custom directory.

For example, applications built with the prefix /usr/local/my-app will ship

• binaries in /usr/local/my-app/bin, /usr/local/my-app/usr/bin
• libraries in /usr/local/my-app/lib[64], /usr/local/my-app/usr/lib[64]

These binaries can be called directly, e.g. /usr/local/my-app/usr/bin/myprog. myprog will only use libraries from /usr/local/my-app/lib etc., not from /.

A good use case example for prefix builds is to create distro independent, portable system extensions.

How does it do that?

Prefix uses a staging environment to build binary packages, then installs these to a final environment. The staging environment contains toolchains and all build tools required to create binary packages (a full @system). The final environment only contains run-time dependencies.

Packages are built from ebuilds in coreos-overlay, portage-stable, and prefix-overlay.

A QoL emerge wrapper is included to install packages to the prefix.

Prerequisites

Prefix utilises the cross-boss project to bootstrap prefixes and to build packages. For the time being the user is expected to provide cross-boss manually. By default, a cross-boss sub-directory is expected in the scripts repository root. Cross-boss location can be customised via the --cross_boss_root option to setup_prefix.

• Run git clone https://github.com/chewi/cross-boss in the scripts directory.

Quick-start guide

For working with a prefix, you will need to agree on:

1. A name for the prefix. Should be a single word and is used for generating protage wrappers.
2. A prefix directory where applications and libraries will live on the target system. For use with systemd-sysext this should be a path below /usr or /opt.

For the purpose of the example below we'll use

• my-prefix as the prefix name, and
• /usr/local/my-stuff as prefix directory.

TL;DR

• ./setup_prefix my-prefix /usr/local/my-stuff
• emerge-prefix-my-stuff-amd64-usr python will create a portable python installation in __prefix__/amd64-usr/my-stuff/root.

Step by step

First we'll create the prefix. This will create "staging" and "final" roots and cross-compile a staging environment into "staging".

• In the SDK container, run ./setup_prefix my-prefix /usr/local/my-stuff
• Go fetch a coffee, bootstrapping may take some 20-ish minutes to complete.

setup_prefix will default to amd64-usr architecture and will use

• /build/prefix-<arch>/my-stuff for the staging environment
• __prefix__/<arch>/my-stuff in the scripts directory as install root (aka "final")
• It will also create an emerge wrapper emerge-prefix-my-stuff-<arch> to install packages.

Time to use the wrapper! Let's build a portable python sysext.

• emerge-prefix-my-stuff-amd64-usr python

Now we'll use bake.sh from Flatcar's sysext-bakery to create a python sysext.

wget https://raw.githubusercontent.com/flatcar/sysext-bakery/main/bake.sh
chmod 755 bake.sh
cd __prefix__/amd64-usr/my-stuff
sudo cp -R root python
sudo ../../../bake.sh python

On a Flatcar instance, we now copy the resulting python.raw to /etc/extensions. We merge with systemd-sysext refresh. Then we can run:

• /usr/local/my-stuff/usr/bin/python

Note that this sysext can be used on any Linux distro that ships systemd-sysext. It is self-contained, there are no user space dependencies.