mirror of https://github.com/flatcar/scripts.git synced 2026-05-05 04:06:33 +02:00

James Le Cuirot 21699f8433

Move and rename package repositories (part 2)

Catalyst 4 has totally changed the way repositories are handled. It only
works when the name of the directory containing the repository matches
the configured name of that repository. We already renamed coreos to
coreos-overlay accordingly, but we actually want entirely different
names and more convenient locations too.

The repositories are now known as gentoo-subset and flatcar-overlay, and
they live under scripts/repos. Using the same name as upstream Gentoo
would have been problematic, and just "flatcar" would have looked
awkward in documentation.

I have removed code referencing /mnt/host/source/config rather than fix
it up, as this is no location is no longer used anywhere.

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

2024-07-23 09:06:03 +01:00

4.9 KiB

Raw Permalink Blame History

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:

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.
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.
Add prefix wrappers for all portage tools (similar to board wrappers), not just emerge.
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 flatcar-overlay, gentoo-subset, 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:

A name for the prefix. Should be a single word and is used for generating protage wrappers.
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.

4.9 KiB Raw Permalink Blame History