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

> Discover how omarchy-pkgs dual-package build system creates synchronized omarchy and omarchy-settings packages from a single source, preventing conflicts and ensuring version consistency.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-28

---

**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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main//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.