Before going further, ensure to get a functional build environment setup
You must complete the toolkit environment setup before executing any command from this page.
Setup and activate the toolkit environment¶
Setup and activate the CLIP OS toolkit environment in which you will be able
to use all the CLIP OS tools required to build and conveniently manage the
source tree (such as
just to handle the
$ toolkit/setup.sh # This is to be run at least once on your machine. $ source toolkit/activate (toolkit) $ # Your shell prompt is automatically prefixed.
About the CLIP OS toolkit virtualenv setup
The purpose of the script
toolkit/setup.sh is to compile and store the
CLIP OS toolkit environment under the form of a Python virtualenv in
run/venv directory. You might be invited to run it again if the
specification of the toolkit environment has changed over time.
This setup script can take some time (up to a couple of minutes) to complete on the first launch as it will automatically trigger the compilation of some CPython packages required by the CLIP OS toolkit. Thanks for your patience.
Instrumentation features for testing¶
Default builds of the project are meant to be set up with a production-ready
configuration. There is currently no password-based local login available in
this configuration. Thus if you want to test the project in QEMU, you will have
to enable some instrumentation features. A good default
set of instrumentation features is provided in the
toolkit/instrumentation.toml.example example file which can be used as is
by copying it to the source tree root folder:
(toolkit) $ cp toolkit/instrumentation.toml.example instrumentation.toml
The default configuration will keep most system configuration unchanged and will give you local password-less root access.
Any change of instrumentation features requires a full project rebuild.
Building the full project¶
You will then be able to use the
justfile’s to run commands to build CLIP
OS. Building the CLIP OS project requires multiple successive steps that are
described in Justfiles. All commands are run
from the project root directory.
To list the available just recipes:
(toolkit) $ just --list
To run all steps required to build CLIP OS:
(toolkit) $ sujust all
As some tasks need root privileges to function properly you must pay
attention to which
just commands needs
root privileges as there are
just commands (such as helpers for source repository and branch
manipulation) which do not require
On most distributions, the default configuration will reset the
PATH environment variable set by the CLIP OS toolkit environment to a
fixed default value when calling
To workaround this issue without modifying your
the CLIP OS toolkit environment sets an alias for the sudo command to keep
On some distributions (e.g., Debian), the default user
does not include the
/usr/sbin folders. Please add those
to your user
$PATH. For example:
$ export PATH="$PATH:/sbin:/usr/sbin"
Building a QEMU image and running using QEMU/KVM¶
TPM emulation support
TPM emulation support is required to test the project under QEMU. To enable
it, you may install
swtpm using either instructions
INSTALL file on their respective GitHub repositories or the AUR
packages for Arch Linux users.
Alternatively, you may enable the
instrumentation feature which will allow the initramfs to ask for a
passphrase at bootup if TPM support is not available. The default passphrase
To build a QCOW2 QEMU disk image and to setup a EFI & QEMU/KVM enabled virtual
(toolkit) $ sujust qemu
Local login disabled by default
The default build configuration will create production images with root access disabled. See the Instrumentation features for testing paragraph for instructions to create an instrumented build.