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 (including the pacman generation hooks etc/pacman.d/hooks/) is applied by x setup (install/config.sh); hooks/pacman-gen.sh is the wrapper those hooks 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 19 in the PKGBUILD, so the payload is x-scripts 0.1.0-19). 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.

Payload checks

The test suite guards the packaged payload: test/package-payload.sh (run by test/validate.sh) requires the generation engine inside the built .pkg, compares xgen.sh against the branch and checks that the payload embedded in the distro ISO is unique and identical. Bump pkgrel and rebuild whenever the payload content changes so the check stays reproducible.

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 whole 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.

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:

  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