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

First, install 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 /etc/portage/package.accept_keywords/catalyst

Create the directory /var/tmp/catalyst/builds/default:

mkdir -p /var/tmp/catalyst/builds/default

Make sure /var/cache/distfiles is created:

mkdir -p /var/cache/distfiles

Next, clone our catalyst repository:

git clone

Enter the directory:

cd catalyst

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:

snapshot_treeish: 202a513901854da4c0f3bce7cfd8242e8194689d

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 /home/xenia/catalyst/:

stage4/root_overlay: /home/xenia/catalyst/overlay
stage4/fsscript: /home/xenia/catalyst/


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:

rm root.img
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 root.img in /roots with your own. If you don’t, follow the guided installation, replacing the root image URL with your own.