SDK bootstrap process
This document aims to provide a high-level overview of the SDK build (“bootstrap”) process.
SDK bootstrapping is implemented in
bootstrap_sdk and happens in 4 stages. Gentoo’s catalyst is used to run each of the stages in an isolated chroot. Each stage requires a “seed” tarball which contains the root filesystem used by that stage. The first stage will use an existing SDK as its seed (i.e. root FS); stages 2 to 4 will use the output of the previous stage as its seed (root FS).
SDK bootstrap phases
The SDK bootstrap will use a previous SDK release for bootstrapping. By default, the version of the SDK is used in which the
bootstrap_sdk script is run.
Each stage will
- unpack the seed
- bind-mount package repositories to the seed, mount proc
- copy the stage’s script into the unpacked seed
- chroot into the seed
- run the stage’s script, creating the root FS for the next step in
/tmp/stageXroot(with X bein 1 to 4, depending on stage)
- clean up and archive the stage’s
/tmp/stageXrootto be used as the succeeding stage’s seed
The output of the 4th stage, i.e. the archived contents of
/tmp/stage4root, resembles the full-built SDK.
Stage 1 - Create minimal toolchain to bootstrap the SDK toolchain
Stage 1 is somewhat of a preparation phase and does not actually involve any components to be found in the final SDK. This stage takes the seed tarball - which must be a previously released Flatcar SDK - and builds a minimal toolchain from the seed (with
- this toolchain, i.e. the output of Stage 1, will be built from the “old” package versions from the seed SDK. Contents of
../third_party/portage-stableare ignored in this step. Instead, the ebuild repos included in the seed SDK are used (FIXME: Not entirely true yet)
- Stage 1 does not feature strong library link isolation. All packages installed to
/tmp/stage1rootwill be linked against libraries in
/instead of libraries in
/tmp/stage1root. Therefore, Stage 1 only uses the “old” seed SDK’s package versions when building the seed for Stage 2.
Stage 2 - Build the toolchain that builds the SDK
Stage 2 uses the minimal (but potentially outdated) toolchain from Stage 1 to build a full-featured (and potentially updated) toolchain used in Stage 3 for building the actual SDK. Stage 2, contrary to Stage 1, offers strong library link isolation - everything installed to
/tmp/stage2root is linked against libraries in
Stage 2 utilises a (slightly modified) bootstrap.sh - the script upstream Gentoo uses to bootstrap a Gentoo distribution.
Stage 3 - Build the base OS
Stage 3 runs
emerge @world to build the base OS into
Stage 4 - Build additional SDK dependencies and cross-compiler toolchains
Stage 4 builds all additional dependencies of the SDK (from coreos-devel/sdk-depends ) that were not included in the base OS packages built in Stage 3. Stage 4 also builds the ARM and x86 cross-compiler toolchains included with the SDK. Finally, Stage 4 archives the portage-stable and coreos-overlay repos used to build this stage, for use in future Stage 1s (see above).
The output of Stage 4 is a full-featured SDK tarball.
Tips and tricks
Some helpful notes when working with
bootstrap_sdk in development.
Continue an aborted SDK build
--version command line flag you can continue an SDK build which was
previously aborted, e.g. after fixing an issue that caused the abort:
$ sudo ./bootstrap_sdk --version <[release-ID]+[timestamp]>
$ sudo ./bootstrap_sdk --version 2783.0.0+2021-02-26-1321