euri-iso/docs/development.md

title, layout, nav_order

title	layout	nav_order
Development	default	8

Development

Repository structure

antergos-iso/
├── buildiso                    # Modified buildiso with --overwrite='*' and branding
├── iso-profiles/
│   ├── antergos/
│   │   ├── profile.yaml        # Packages, services (rootfs + livefs), compression
│   │   ├── root-overlay/       # Merged into rootfs → live session + offline install
│   │   └── live-overlay/       # Merged into live environment only
│   └── common/
│       └── common.yaml         # Shared base packages (kernel, firmware, filesystem)
├── pacman.conf.d/
│   └── iso-x86_64.conf         # Pacman config for ISO build with [antergos-pkgs]
└── .github/workflows/
    ├── build.yml               # ISO build (IA upload step disabled)
    ├── ai-moderator.yml        # Groq-powered community moderator
    └── pages.yml               # Docs deployment to GitHub Pages

Building locally

export WORKSPACE_DIR="$PWD"
sudo -E ./buildiso -p antergos

See Building the ISO for full setup instructions and troubleshooting.

Critical gotchas

./buildiso vs buildiso

Always use the repo's ./buildiso, not the system Artix /usr/bin/buildiso. The system version lacks --overwrite='*' and will fail with file conflicts between calamares and calamares-branding-antergos-next.

sudo -E is required

Without -E, WORKSPACE_DIR is stripped and load_profile() returns empty HAS_LIVE/LIVEUSER, causing build failures immediately.

Pacman config must be user-overridden

buildiso reads from ~/.config/artools/pacman.conf.d/iso-x86_64.conf. If missing, it falls back to the Artix default at /usr/share/artools/pacman.conf.d/iso-x86_64.conf which lacks [antergos-pkgs].

mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/

CI does this automatically.

Repo order in iso-x86_64.conf

[antergos-pkgs] must be listed first in iso-x86_64.conf so custom packages (calamares, branding) take priority over Artix's. If Artix repos are first, our custom packages won't be installed.

Package order matters in profile.yaml

basestrap uses --overwrite='*'. The last package to claim a file wins. Package order in profile.yaml should list calamares BEFORE calamares-branding-antergos-next, so branding files overwrite Calamares defaults, not the other way around.

antergos-release must be in basestrap.conf operations

The filesystem package owns /usr/lib/os-release with "Artix Linux". To replace it with "Antergos NeXT", antergos-release must be listed in the operations list in iso-profiles/antergos/live-overlay/etc/calamares/modules/basestrap.conf. This ensures it's installed during bootstrapping with --overwrite. If it's missing from operations, the installed system will show "Artix Linux" in /usr/lib/os-release.

Squashfs compression

If $COMPRESSION is unset in profile.yaml, mksquashfs produces a sparse zero file instead of a valid squashfs. The ISO will be tiny and unbootable. Always verify compression is set, or remove stale images before retrying.

Calamares module precedence

/etc/calamares/modules/ overrides /usr/share/calamares/modules/. The calamares-next launcher copies the online settings file to /etc/calamares/settings.conf, and the modules-search: [ local ] directive in that file resolves modules from /etc/calamares/modules/. Both calamares/modules/ and calamares-online/modules/ in the live-overlay are for the online installer — there is no offline Calamares config. Module configs placed in calamares-online/modules/ are not loaded directly during installation — only calamares/modules/ is consulted at runtime; the calamares-online/modules/ tree is the self-contained companion copy.

GRUB config overwrite must be enabled

The Artix grub package ships a default /etc/default/grub file. When Calamares's grubcfg module runs during installation, this file already exists on the target system. With overwrite: false, the module reads the existing file and only modifies GRUB_CMDLINE_LINUX_DEFAULT and GRUB_DISTRIBUTOR — all other keys from the defaults block (including GRUB_THEME and GRUB_TERMINAL_OUTPUT) are silently ignored.

The active configuration at live-overlay/etc/calamares/modules/grubcfg.conf must set overwrite: true to replace Artix's shipped defaults with the distribution's intended values. Without this, the installed system will use the bare Artix GRUB configuration with no theme.

GRUB_TERMINAL_OUTPUT must be "gfxterm" for themed GRUB

Setting GRUB_TERMINAL_OUTPUT: "console" in grubcfg.conf forces GRUB into text mode and disables the graphical theme. The theme requires GRUB_TERMINAL_OUTPUT: "gfxterm" to render.

Live-overlay is not overlay-mounted

Live-overlay files are copied via cp -LR in make_livefs(). Deleting a file from live-overlay exposes the package version underneath. Use NoDisplay=true in .desktop files to hide entries.

plasma-wayland-session does not exist on Artix

Artix bundles the Wayland session into plasma-workspace itself. Do not add it to package lists.

SDDM theme

The installed system uses the pixie theme (pixie-sddm-git). The antergos-layan-theme package vendors its own kde_settings.conf at /etc/sddm.conf.d/kde_settings.conf with Current=pixie plus dinit halt/reboot commands — this overrides KDE's SDDM KCM setting. The live session deliberately uses breeze for autologin.

The antergos-sddm-theme PKGBUILD still exists in antergos-packages but is not built (not in packages.yaml) and not used.

Pipewire launcher on dinit

artix-pipewire-launcher detects the init system and only proceeds on supported ones. For dinit, the upstream script returns SUPPORT='' (unsupported). The forked version in [antergos-pkgs] patches this to dinit|runit|s6) SUPPORT='YES'. The XDG autostart entry (pipewire.desktop at /etc/xdg/autostart/) then starts pipewire on login.

File conflicts

• calamares and calamares-branding-antergos-next both install to /usr/share/calamares/branding/default/ — handled by --overwrite='*'
• filesystem and antergos-release both claim /usr/lib/os-release — handled by including antergos-release in basestrap operations

calamares-next.sh SetConfig()

Must rm -f the existing file before cp, otherwise cp follows any existing symlink to the settings file.

CI does not trigger on push

The build.yml workflow only runs on workflow_dispatch (manual trigger from GitHub Actions tab). This prevents accidental ISO builds on every push.

Internet Archive bucket naming

ISO identifier format: antergos-next-YYYYMMDD-<run_number>. The -<run_number> ensures uniqueness even for multiple builds on the same day.

Testing a build

Boot the resulting ISO in a VM. Verify:

• Wayland is the default display server (SDDM session is plasma.desktop)
• No "Install Artix Linux" entry in the app menu
• Wallpaper is set on first login
• DE selector works
• Slideshow renders correctly
• Audio works after installation (pipewire should auto-start)
• After install, /usr/lib/os-release shows "Antergos NeXT"
• SDDM shows the Antergos theme, not Breeze

Custom packages repo

Custom PKGBUILDs live in the companion antergos-packages repo. The CI there builds them and publishes to GitHub Pages as a pacman repository:

[antergos-pkgs]
SigLevel = Optional TrustAll
Server = https://antergos-next.github.io/antergos-packages