How the Dual-Package Build System Works in omarchy-pkgs

The omarchy-pkgs repository implements a dual-package build system that produces two separate Arch Linux packages—omarchy for runtime binaries and omarchy-settings for pre-install configuration files—from a single source checkout, ensuring version synchronization while avoiding file conflicts with upstream packages.

The dual-package build system separates the Omarchy desktop environment’s executable components from its system-wide configuration templates. This architecture, maintained in the basecamp/omarchy source tree alongside the companion omarchy-pkgs repository, allows the same Git commit to generate both the runtime package and the settings package. Understanding this split is critical for developers packaging Omarchy or modifying its installation pipeline.

Overview of the Dual-Package Architecture

The build system generates two distinct Arch packages with separate responsibilities:

• omarchy – Contains runtime binaries (bin/), the Quickshell desktop environment, migration scripts, themes, and installation logic. Its build instructions reside in omarchy-pkgs/pkgbuilds/omarchy/PKGBUILD.
• omarchy-settings – Houses files that must exist before the main package installs, including /etc/skel/ templates, system-wide drop-ins, fonts, Plymouth and SDDM themes, and branding assets. Its build instructions are located at omarchy-pkgs/pkgbuilds/omarchy-settings/PKGBUILD.

The PKGBUILDs are not stored in the main repository. Instead, they live in the separate omarchy-pkgs companion repository, which packages the source code found in basecamp/omarchy.

Build-Time Flow

The packaging process follows a strict sequence to maintain integrity between the two artifacts:

1. Checkout both repositories – Developers must clone both the main omarchy source tree and the omarchy-pkgs companion repository.

2. Locate the PKGBUILD directory – The helper script bin/omarchy-version-pkgs discovers the path to the PKGBUILDs, falling back to ~/Work/omacom/omarchy-pkgs/pkgbuilds or a sibling ../omarchy-pkgs/pkgbuilds directory.

3. Execute makepkg – The build runs separately for each PKGBUILD, producing the omarchy and omarchy-settings packages.

4. Install binaries and templates – The omarchy package installs executables to /usr/bin/omarchy-* and a symlink tree under /usr/share/omarchy/bin/. The omarchy-settings package places seed files in /etc/skel/ and override files in /usr/share/omarchy/etc-overrides/.

5. Post-install configuration – The omarchy-settings package runs a post_install script that copies files from the override directory into their final locations under /etc/ (such as /etc/bashrc and /etc/nsswitch.conf). This indirect installation prevents file conflicts with upstream Arch packages that own those paths.

Because both packages originate from the same source commit, a change to a default configuration in config/ automatically appears in the next omarchy-settings release, while a new binary added under bin/ appears in the next omarchy release.

Rationale for the Split

The dual-package approach solves three specific packaging constraints:

• Separation of concerns – omarchy-settings must be installed before the omarchy package so that useradd -m can copy the /etc/skel/ templates when creating the initial user account.

• Avoiding file conflicts – Many files under /etc/ are owned by core Arch packages. By staging files in /usr/share/omarchy/etc-overrides/ and copying them during post-install, omarchy-settings can safely replace or augment system files without triggering pacman conflicts.

• Independent update cadence – The runtime package can be upgraded independently of the settings package, yet both remain version-matched because they are built from the same commit hash.

Key Implementation Files

Several source files define and verify this architecture:

• docs/file-layout.md – Documents the mental model for the two-package split, explaining which directories map to which package.

• bin/omarchy-version-pkgs – Detects the omarchy-pkgs checkout location and reports the version used for the PKGBUILDs, ensuring the build system references the correct companion repository.

• test/shell.d/unowned-system-paths-test.sh – Validates that a checkout of omarchy-pkgs is available, ensuring packaging coverage during continuous integration.

• omarchy-pkgs/pkgbuilds/omarchy/PKGBUILD – Defines the build process for the runtime package, specifying which directories (such as bin/, shell/, themes/) to include.

• omarchy-pkgs/pkgbuilds/omarchy-settings/PKGBUILD – Defines the build process for the settings package, targeting config/, skel/, and override directories.

Build Commands and Workflows

Building packages from side-by-side checkouts

# Assume the following directory structure:

#   ~/Work/omarchy          ← main source repository

#   ~/Work/omarchy-pkgs     ← companion repository with PKGBUILDs

cd ~/Work/omarchy-pkgs/pkgbuilds/omarchy
makepkg -si

cd ../omarchy-settings
makepkg -si

Locating the PKGBUILD directory programmatically

# Returns the path to the PKGBUILDs and the current version

omarchy-version-pkgs

# Example output:

#   OMARCHY_PKGBUILDS_DIR="/home/user/Work/omarchy/omarchy-pkgs/pkgbuilds"

Linking a development checkout

# Symlinks the current source tree as the active development version

omarchy-dev-link

# This writes to /etc/omarchy.conf and updates secure_path so sudo

# sees the local binaries before they are packaged.

Updating both packages simultaneously

# Pull latest changes and rebuild both packages

git -C ~/Work/omarchy pull
git -C ~/Work/omarchy-pkgs pull
omarchy-update-system-pkgs   # Builds both PKGBUILDs and runs pacman -U

Summary

• The dual-package build system generates omarchy and omarchy-settings from a single source commit in basecamp/omarchy.
• Runtime binaries ship in the omarchy package while pre-install configuration files ship in omarchy-settings.
• The helper script bin/omarchy-version-pkgs locates the companion omarchy-pkgs repository containing the PKGBUILDs.
• omarchy-settings uses an override directory and post-install copy mechanism to avoid file conflicts with upstream Arch packages.
• Both packages remain version-synchronized because they are built from identical source checkouts.

Frequently Asked Questions

Why are the PKGBUILDs stored in a separate repository from the main source code?

The PKGBUILDs live in omarchy-pkgs to isolate Arch-specific build logic from the desktop environment’s source code. This separation allows the omarchy repository to remain distribution-agnostic while the companion repository handles packaging rules, dependencies, and Arch-specific installation hooks.

How does the build system handle files in /etc/ owned by other Arch packages?

The omarchy-settings package installs configuration templates to /usr/share/omarchy/etc-overrides/ rather than directly to /etc/. During installation, a post_install script copies these files into their final locations (such as /etc/bashrc or /etc/nsswitch.conf). This strategy prevents pacman from detecting file conflicts with core packages like filesystem or bash while still deploying the required system configurations.

Can I build and test these packages without installing them system-wide?

Yes. Developers can use omarchy-dev-link to symlink a local checkout as the active development source, bypassing the need for packaged installation during testing. Additionally, running makepkg in a side-by-side checkout of omarchy-pkgs builds local packages that can be installed with pacman -U without affecting the system-wide package database until you choose to upgrade.

What happens if the omarchy and omarchy-settings packages become out of sync?

While designed to be updated together from the same commit, the packages can technically be upgraded independently. However, version mismatches may cause configuration drift, as omarchy-settings contains the default user environment templates and system overrides that the omarchy runtime expects to be present. The bin/omarchy-version-pkgs script ensures both PKGBUILDs reference the same source version to prevent this drift during the build process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}