Manual rootFS generation
We use catalyst to generate our rootFS images. Catalyst is a build tool made by Gentoo which is used to build Gentoo (and anything based on it). This page will walk you through making a root image of your own.
First time setup
dev-util/catalyst on your system.
dev-util/catalyst may be masked when you read this. Make sure to unmask it by adding
dev-util/catalyst ** to
Create the directory
mkdir -p /var/tmp/catalyst/builds/default
/var/cache/distfiles is created:
mkdir -p /var/cache/distfiles
Next, clone our catalyst repository:
git clone https://gitlab.com/xenia-group/catalyst
Enter the directory:
Symlink the config directory:
ln -sf $PWD/config /var/tmp/catalyst/
With catalyst setup, download a stage3. To find which one is needed, look in the spec file you are building under
source_subpath. For openrc, it is usually a standard openrc stage3. For systemd, it is usually systemd-mergedusr.
Finally, add the Xenia overlay to your system.
Create a snapshot
Run a portage sync:
Create the snapshot:
catalyst -s stable
There will be an entry like the following:
NOTICE:catalyst:Wrote snapshot to /var/tmp/catalyst/snapshots/gentoo-202a513901854da4c0f3bce7cfd8242e8194689d.sqfs
Get the snapshot hash (in this case
202a513901854da4c0f3bce7cfd8242e8194689d), and replace
[SNAPSHOT_HASH] with the hash:
Pick a spec file
Xenia has multiple spec files. For example, there is
stage4-openrc.spec which will build an openrc GNOME image of Xenia. Or, there is
stage4-systemd-plasma.spec, which will build a systemd Plasma/KDE image of Xenia.
Spec file setup
In the spec file selected earlier, change all instances of
[CATALYST_DIR] with the directory the catalyst repo is - in this case
Build the stage4:
-a here means no auto-resume. We specify this in-case of an error which requires a full rebuild. Auto-resume may be handy if you need to stop for whatever reason and come back later, so feel free to remove this flag
catalyst -a -f [your spec file].spec
If there is any errors building, the first port of call is to download a new stage3. If this doesn’t work, try running catalyst again without -a. This will get around any issues with post-install of packages (
gtk+ being the main culprit here).
The stage4 will now be in
/var/tmp/catalyst/builds/default/stage4-[arch]-[target].tar.xz. The target will be the target set in the spec file. The arch will be the architecture of the image (amd64 is most common here, unless
stage4-arm64-* is being used as a spec file).
This process will be very slow the first time you build the stage4 - you will be compiling GCC, LLVM, a DE etc. However, catalyst keeps binary packages! So your next build will be very quick.
You can learn about customising your own rootFS here.
Converting to squashFS
The stage4 you have made is currently a tarball. Let’s convert it to a squashFS:
mksquashfs /var/tmp/catalyst/tmp/default/stage4-[arch]-[target] root.img -comp xz
First, host a server where your
root.img is located:
python3 -m http.server
This part is unfinished! There will be better update documentation soon
If you have an existing installation, you can simply replace
/roots with your own. If you don’t, follow the guided installation, replacing the root image URL with your own.