X Linux
Documentation menu

Overview/Scripts and CLI

x — packaging

The provisioning payload is packaged as x-scripts with a plain PKGBUILD + makepkg in packaging/. (The Rust tooling xpkg/xpm is currently out of scope for packaging; see the workspace ROADMAP, Phase 4.)

Building x-scripts

packaging/PKGBUILD produces the Arch package (any, depends on bash):

  • Ships bin, install, skel, etc, config, hardware, tools, migrations, themes and hooks to /usr/share/x.
  • Makes every *.sh (and the x dispatcher) executable under /usr/share/x/{bin,install,hardware,tools,hooks}.
  • The /etc overlay is applied by x setup (install/config.sh). The pacman hooks ship in the package (hooks/alpm/*.hook → /usr/share/libalpm/hooks/); hooks/pacman-gen.sh is the wrapper they call (see provisioning.md and generations.md).
  • Installs /usr/bin/x as a symlink to /usr/share/x/bin/x.
  • If packaging/.vendor/x-config exists, its contents are merged into /usr/share/x/config (the offline desktop snapshot used by tools/hyprland-install.sh). There are no remote source=() entries: the snapshot is vendored in-repo and never fetched at build time.

Version metadata: pkgver=0.1.0, pkgrel bumped per iteration (currently 42 in the PKGBUILD). A leftover build artifact (*.pkg.tar.zst) may sit in the directory but is stale and git-ignored; rebuild produces the current pkgrel.

To build (network-free regarding the config sources; the vendored tree must be present first, see below):

cd packaging
makepkg   # requires packaging/.vendor/x-config to be present

packaging/.gitignore ignores src/, pkg/, .vendor/ and built artifacts.

vendor-config.sh — the offline snapshot

packaging/vendor-config.sh regenerates the vendored snapshot at packaging/.vendor/x-config from the external source repos (branch main), which are used read-only and remain the source of truth:

  • equisdots/{dots,hyprland,shell,palettes,theme-sync,davincix,timex,login} → equisdots/<repo> (the Hyprland desktop stack; equisdots/dots is the official installer and ships the standalone install-xwww.sh).
  • xscriptor-colors/terminal → kitty only (kitty.conf + themes/) and starship (prompts/starship: template + themes).
  • xscriptor-colors/nvim → the whole nvim tree.

niri is not vendored: tools/niri-install.sh clones equisdots/niri-meta online and runs dotsniri setup -y. KDE Plasma branding is a separate x-kde-settings package bundled in the live ISO, not part of this payload.

Behavior:

  • Refuses to run as root; requires git and network access (shallow clones).
  • Strips .git/.github from each clone and from the final tree.
  • Verifies the key stack files are present (hyprland Lua config, PAM policy, shell entry point, palettes, engines, login installer, kitty/starship/nvim).
  • Nothing NVIDIA is excluded: the snapshot stays complete so the tool can fall back to the upstream equisdots NVIDIA setup when needed (the X hardware phase remains the owner of the driver installation).
  • Never modifies the external repos.
  • Prints the pinned commits of the sources and a per-directory file count.
packaging/vendor-config.sh        # from the repo root
packaging/vendor-config.sh /path/to/repo

The .vendor output is git-ignored, so it must be (re)generated by a maintainer before building; it is not part of git history. config/hypr/README.md documents the same flow.

Reproducibility (vendor-config.lock)

The resolved commits are recorded in packaging/vendor-config.lock (tracked). On the next run each clone is checked out at its pinned commit (fetched directly with git fetch --depth 1 origin <sha>), so rebuilding the package from the same lock produces the same snapshot. The lock is rewritten when it changes: commit it together with the regenerated snapshot.

  • X_VENDOR_BRANCH=ref — branch to clone (default main).
  • X_VENDOR_NO_LOCK=1 — ignore the lock (resolve the branch tips) and rewrite it.
  • X_VENDOR_LOCK=path — lock file override.

Vendored layout

packaging/.vendor/x-config
├── equisdots/
│   ├── dots/ hyprland/ shell/ palettes/ theme-sync/ davincix/ timex/ login/
├── kitty/     (kitty.conf + themes/)
├── starship/  (starship.toml + themes/)
└── nvim/      (whole config tree)

Shipped by the PKGBUILD as /usr/share/x/config, this mirrors the ~/.local/share/equisdots layout of dots install (equisdots/<repo>), which is exactly how tools/hyprland-install.sh consumes it offline.

Offline ISO usage

The point of vendoring is that a Hyprland/equisdots desktop can be provisioned offline right after install. niri and KDE Plasma are online install paths:

  1. A maintainer runs vendor-config.sh and builds x-scripts (snapshot embedded in the package).
  2. The distro (equislinux/x) installs x-scripts on the target and runs the root phases during install.
  3. At first boot the user phase runs tools/hyprland-install.sh, which finds /usr/share/x/config/equisdots and deploys the whole desktop without any external clone. Package installation (official + AUR + the xwww release) is the only part that needs a repository/network, since the configs themselves travel inside the package.

Notes / current state (from the workspace ROADMAP):

  • x-base.packages (the builder-readable base list) is shipped but does not yet have a consumer wired into the distro builder.
  • The distro-side offline mirror bundling (fully network-less install) remains a pending improvement in equislinux/x.

Edit this page on GitHub