Stefan: Argent Avasile management of the system.

2026-09-25T20:29:20Z

Argent Avasile management of the system.

New page

=== Avasile ===

First of all, the holy '''avasile --help'''.

Vasile stands for "Versatile Advanced Script for ISOs and Latest Enhancements", and avasile is "Argent Vasile". It does two different jobs:

* for users: it puts your system in one of the Argent '''modes''' (user mode, devmode, srcmode, ...), which decide if you install binaries, compile, or both
* for developers: it builds packages and live ISO images in a clean chroot

The mode switches and the build commands need root. If you run them as a normal user, avasile tries to restart itself with sudo. avasile refuses to run on a live ISO.

To see every command avasile runs, step by step, add <code>AVASILE_VERBOSE=1</code> in front:

<code>AVASILE_VERBOSE=1 avasile --devmode</code>

== Which mode am I on? ==

<code>avasile --status</code>

It prints one of:

* <code>avasile is on --usermode</code>
* <code>avasile is on --devmode!</code>
* <code>avasile is on --srcmode!</code>
* <code>avasile is on your own custom mode!</code>
* <code>avasile is not on any known modes</code>

The mode is simply which Argent make.conf your <code>/etc/portage/make.conf/</code> points to. See the System Administration page for what that means for <code>/etc/portage</code>.

== The modes ==

{| class="wikitable"
! Mode !! Binaries !! Compiling !! Portage tree !! Who is it for
|-
| <code>--usermode</code> || only binaries || never || minimal (no ebuilds) || everybody, Gentoo newcomers
|-
| <code>--devmode</code> || when they match your config || when they don't || full || developers, advanced users
|-
| <code>--srcmode</code> || no || everything || full || people who want a pure Gentoo
|-
| <code>--custom</code> || optional || yes || full || people who want their own /etc/portage
|}

'''Every mode switch starts from zero.''' <code>--usermode</code>, <code>--devmode</code>, <code>--srcmode</code> and <code>--custom</code> first remove:

* the Gentoo portage tree (<code>/var/db/repos/gentoo</code>), except its <code>packages</code> and <code>distfiles</code>
* the argent-ws overlay (<code>/var/db/repos/argent-ws</code>), except its <code>packages</code> and <code>distfiles</code>
* the whole <code>/etc/portage</code> and <code>/opt/argentws-build</code>, '''including every file you made in there''' (your <code>100-my.*</code> files, your <code>01-my.make.conf</code>, your <code>repos.conf</code> additions)

and then download everything again. '''Keep a copy of your own files before you switch.''' It also needs internet and takes a while.

After the download, every mode:

* makes <code>/etc/portage</code> a symlink to <code>/opt/argentws-build/conf/intel/portage</code>
* points <code>/etc/portage/make.conf/00-main.conf</code> to the make.conf of that mode
* sets the profile <code>default/linux/amd64/23.0/desktop/plasma/systemd</code>
* runs <code>env-update</code>
* refreshes the keys used to verify binary packages (unless you add <code>--skip-keys</code>)

If you run it from inside <code>/etc/portage</code>, avasile moves you to <code>/etc</code> first, since that directory is about to disappear.

=== User mode ===

<code>avasile --usermode</code>

This is the default Argent. Only binary packages from our binhost, nothing gets compiled. The Gentoo tree and the argent-ws overlay are downloaded minimal, only <code>profiles</code>, <code>metadata</code> and <code>eclass</code>, so they take very little space.

'''Don't change anything in <code>/etc/portage</code> in this mode.'''

You can also consider user mode your '''system rescue mode'''. Whatever you did to your configuration, <code>avasile --usermode</code> throws it away and puts your system back in complete obedience to the Argent remote repositories and configuration, the same ones our binaries were built with. When your system is lost, this is how you get it back on track. After that:

<code>epkg upgrade</code>

and your packages follow our binhost again.

=== Development mode ===

<code>avasile --devmode</code>

Binaries when they match your configuration, compiling when they don't, and what you compile is saved in <code>/var/cache/binpkgs</code>. You get the full Gentoo tree and the full argent-ws overlay. You can change USE flags and keywords, in your own files, like <code>/etc/portage/package.use/100-my.package.use</code>.

This is the mode you need for <code>epkg compile</code>, <code>epkg recompile-depend</code> and the rest of the developer commands.

=== Source mode ===

<code>avasile --srcmode</code>

Pure Gentoo: no binaries, everything is compiled from ebuilds, still synced with our overlay and our configuration.

'''epkg refuses to run in this mode''', you use <code>emerge</code>, <code>equery</code>, <code>eix</code>, <code>qlist</code> and the rest of the Gentoo tools directly. You need to know them well.

=== Custom mode ===

<code>avasile --custom</code>

'''Alpha feature, not yet recommended.'''

Like source mode, but <code>/etc/portage</code> becomes yours:

* your make.conf is <code>make.conf.amd64-custom</code>, a copy of the devmode one, which you can change freely
* <code>/opt/argentws-build</code> is disconnected from our git, so <code>epkg update</code> no longer brings you our configuration
* our <code>package.use</code> and <code>package.accept_keywords</code> files are deleted, you start with your own

<code>avasile --status</code> shows it as "your own custom mode".

=== Decentralized modes ===

<code>avasile --decentralize-user</code>

<code>avasile --decentralize-dev</code>

<code>avasile --decentralize-source</code>

<code>avasile --decentralize-custom</code>

These are for advanced Gentoo users who run their own independent system, with their own binhost configuration. Unlike the modes above, they '''don't delete and don't download anything''': they only switch the make.conf (user, devel, srcmode or custom), set the profile and run <code>env-update</code>. They need <code>/opt/argentws-build</code> to already exist.

Run <code>epkg update</code> (or <code>emerge --sync</code>) after switching.

<code>avasile --decentralize-gentoo</code>

'''One way ticket.''' Your system forgets it was ever Argent: it switches to the custom make.conf, removes the Argent git link and deletes our <code>package.use</code> and <code>package.accept_keywords</code> files. There is no central authority anymore, you are on your own. If you ever want to come back to Argent:

<pre>
cd /etc/portage && git init
git remote add origin https://gitlab.com/argent/argentws-build.git
git pull --depth=1 origin master
git branch -u origin/master master
</pre>

== Resetting ==

<code>avasile --resetmode</code>

Removes the Gentoo tree, the argent-ws overlay and all of <code>/etc/portage</code>, and doesn't put anything back. '''Never leave your system like this''': you can't install, remove or upgrade anything until you choose a mode again (or configure portage by hand).

== Binary package keys ==

Every mode switch refreshes the keyring that portage uses to verify our binary packages (<code>/etc/portage/gnupg</code>, with <code>getuto</code>). If you have no access to the keyservers, skip it:

<code>avasile --devmode --skip-keys</code>

(<code>--no-keys</code> is the same thing.)

If the keyring is broken, rebuild it from scratch:

<code>avasile --regen-keys</code>

This is the same as <code>epkg regen-keys</code>.

=== For developers: building packages and ISOs ===

These two commands are what we use to build Argent itself. They work in a clean chroot made from the '''Argent core squashfs''', so your own system is never touched.

What you need:

* a kernel with <code>CONFIG_OVERLAY_FS</code>, <code>CONFIG_SQUASHFS</code> and <code>CONFIG_BLK_DEV_LOOP</code>, and with <code>/proc/config.gz</code> enabled, avasile checks them there
* <code>sys-boot/grub:2</code>, <code>sys-fs/squashfs-tools</code>, <code>dev-libs/libisoburn</code>, <code>sys-fs/mtools</code>, <code>net-misc/rsync</code>, <code>sys-kernel/dracut</code>, <code>dev-vcs/git</code>
* optionally <code>sys-fs/zerofree</code>, which makes the ISO smaller
* a working directory with the core squashfs and its checksum:

<pre>
argent_ws_1_core_x64.squashfs
argent_ws_1_core_x64.squashfs.md5
</pre>

The core squashfs is a minimal Gentoo stage3, with our <code>argentws-build</code> settings. We don't distribute it, you make it yourself.

'''Run avasile from that directory''', otherwise it doesn't find the squashfs and stops. It also stops if the md5 doesn't match.

== Building packages ==

<code>avasile --makepkg <package(s)></code>

For example:

<code>avasile --makepkg wine playonlinux q4wine</code>

The working directory also needs a <code>packages</code> and a <code>distfiles</code> directory, they are mounted in the chroot as <code>/var/cache/binpkgs</code> and <code>/var/cache/distfiles</code>.

What happens:

* the core squashfs is mounted read only, with an overlay on top of it (<code>rodir</code>, <code>rwdir</code>, <code>workdir</code>, <code>overlaydir</code> in your working directory)
* inside the chroot, <code>avasile --srcmode</code> sets up the full trees and our configuration
* <code>emerge -kav <package(s)></code> builds your packages, using the binaries you already have in <code>packages</code> for the dependencies
* you are dropped into a '''root shell''' in the chroot, to fix build failures, try USE flags and keywords, and so on
* when you exit the shell, everything is unmounted

Everything you change in the chroot stays in <code>rwdir</code>, so the next <code>--makepkg</code> starts from where you left. Delete <code>rwdir</code> and <code>workdir</code> to start from a clean core again.

If you give no package, avasile only prepares the chroot and gives you the shell.

'''Known issue:''' the <code>packages</code> directory is mounted read only in the chroot, so the packages you build there can't be saved into it yet. This will be fixed in avasile.

== Building a live ISO ==

<code>avasile --makeiso</code> (interactive)

<code>avasile --makeiso /etc/portage/sets/artwork</code> (automated)

The arguments are '''files with one package per line''', like our sets in <code>/etc/portage/sets/</code>. You can give more than one, they are all installed together.

What happens:

* a 20 GiB ext4 image is created, and the core squashfs is copied into it
* the kernel <code>kernel-genkernel-x86_64-6.12.110-argent</code> is taken as <code>boot/vmlinuz</code>
* inside the image, <code>avasile --usermode</code> sets up the configuration
* a live initramfs is generated with dracut (<code>dmsquash-live</code>), as <code>boot/initrd</code>
* the EFI (<code>bootx64.efi</code>) and BIOS (<code>core.img</code>, <code>lnxboot.img</code>) boot images are generated
* a live <code>INSTALL_MASK</code> is added (<code>/etc/portage/make.conf/zz-live.conf</code>), so documentation, man pages, debug files and static libraries are not installed on the ISO
* the packages are installed: from your lists with <code>epkg autoinstall</code>, or, without lists, you get a '''root shell''' in the image to install and configure whatever you want, and you exit when you are done
* the live <code>INSTALL_MASK</code> is removed again
* the live services are enabled (<code>argentlive</code>, <code>sddm</code>, <code>NetworkManager</code>, <code>cups</code>, <code>avahi-daemon</code>, the VirtualBox guest services, ...), and PipeWire replaces PulseAudio
* the free space in the image is zeroed (with <code>zerofree</code>), and everything is compressed into a squashfs
* the GRUB configuration is downloaded from <code>https://gitlab.com/argent/boot-core.git</code>
* the ISO is made with <code>grub-mkrescue</code>

The result is in your working directory:

<code>argent-ws-1-x86_64.iso</code>

The binary packages installed in the ISO come from <code>ISO_BINPKGS_SOURCE</code> (see below), mounted read only in the image as <code>/var/cache/binhost/binhost-main</code>. The default is the path on our build server, so '''you have to set it''' to your own packages directory.

If something fails in the middle, <code>--makeiso</code> unmounts everything on exit.

== Environment variables ==

You can change these on the command line, for example:

<code>KERNEL_VERSION=6.12.100 ISO_BINPKGS_SOURCE=/srv/binpkgs avasile --makeiso /etc/portage/sets/artwork</code>

{| class="wikitable"
! Variable !! Default !! What it does
|-
| <code>AVASILE_VERBOSE</code> || <code>0</code> || <code>1</code> prints every command avasile runs
|-
| <code>AVASILE_SKIP_KEYS</code> || <code>0</code> || <code>1</code> is the same as <code>--skip-keys</code>
|-
| <code>KERNEL_VERSION</code> || <code>6.12.110</code> || the Argent kernel used for the ISO
|-
| <code>ISO_BINPKGS_SOURCE</code> || our build server path || the binary packages installed in the ISO
|-
| <code>ISO_BINPKGS_TARGET</code> || <code>/var/cache/binhost/binhost-main</code> || where they are mounted inside the ISO
|-
| <code>ISO_LIVE_CONF</code> || <code>/etc/portage/make.conf/zz-live.conf</code> || the file with the live INSTALL_MASK
|-
| <code>ISO_INSTALL_MASK</code> || docs, man, info, debug, <code>*.la</code>, <code>*.a</code> || what is not installed on the ISO
|-
| <code>PORTAGE_REPO</code> || <code>https://gitlab.com/argent/argentws-build.git</code> || the central configuration repository
|-
| <code>PORTAGE_MAIN_CONFDIR</code> || <code>/opt/argentws-build</code> || where it is cloned
|-
| <code>PORTAGE_GITDIR</code> || <code>/opt/argentws-build/conf/intel/portage</code> || what <code>/etc/portage</code> points to
|-
| <code>PORTAGE_MAIN_CONF</code> || <code>00-main.conf</code> || the name of the main make.conf, when there is none yet
|-
| <code>ARGENT_MAIN_DIR</code> || <code>/var/db/repos/argent-ws</code> || where the argent-ws overlay lives
|}

Avasile System Management - Revision history

Stefan: Argent Avasile management of the system.