The Builder is a powerful tool for effortlessly building Linux system images based on config directories. It serves as the primary build tooling for the gardenlinux project.
By default, the Builder runs inside rootless Podman, enabling building without requiring elevated permissions.
The Builder has minimal dependencies and only requires a working container engine. We recommend using rootless Podman. Please refer to the Podman rootless setup guide for instructions on setting it up.
To utilize the Builder, follow these steps:
wget https://github.com/gardenlinux/builder/releases/download/latest/build
./build ${target}
By default, the Builder uses podman
as the container engine. If you prefer using a different container engine, you can specify it using the --container-engine
option.
A config directory serves as the input for the Builder and is used to create a Linux system image. It consists of the following components:
features
directory: Contains sub-directories for each feature. You can create your own features by referring to features.md.
cert
directory (optional): If you plan to use secure boot, include a cert
directory.
In addition to the above components, your configuration directory must include the following configuration scripts:
get_commit
: This script should output the Git commit used to tag the build artifacts.get_repo
: This script should output the apt package repository to use.get_timestamp
: This script should output the timestamp to be used instead of the real system time, ensuring reproducibility of builds.get_version
: This script should output the version of the package repository to use. For example, use trixie
for Debian or today
for Garden Linux.keyring.gpg
: The PGP key used to validate the package repository. For Debian, you can obtain this key from the debian-archive-keyring package.For a quick start guide on setting up your own config directory with your own features checkout getting_started.md.
If you're new to configuring the Builder, you can find a minimal example config directory at gardenlinux/builder_example. For a more comprehensive example, refer to the main gardenlinux repository.
Feel free to explore these examples to gain a better understanding of how to effectively structure your own config directory.
To test changes made to the builder locally you can simply create a symlink to the build script inside the builder directory inside a config directory. This will automatically be detected by the build script and the builder re-build iff necessary.
e.g.: if you have the gardenlinux and builder repos both inside the same parent directory and you want to work on the builder you would do the following:
cd gardenlinux
ln -f -s ../builder/build build
Now you can make your modifications inside the builder directory and running ./build ${target}
inside the gardenlinux repo will use the local builder, rebuilding the build container if necessary.