Guide

Building from source

Everything Alpymist ships is built in an Alpine container, so the binaries link against the same musl they run on. You need Docker for that and a Rust toolchain for the workspace; rust-toolchain.toml pins the version to match Alpine's.

Get the code

❯ git clone https://github.com/bisand/alpymist.git
❯ cd alpymist
❯ make help

The Rust workspace

The same checks CI runs on every pull request. Formatting and clippy warnings are errors.

❯ make check
❯ make test
❯ make lint

CI itself runs clippy and the tests with the alpymist-ui/render feature, lints the installer, splash and login screen once more as they ship, on DRM, and checks that every package's version equals the workspace's. The exact commands are in CLAUDE.md.

On any Linux machine you can ask the probe how Hyprland will do on the hardware in front of you:

❯ cargo run -p alpymist -- probe

The installer opens in a window during development, so you can walk through it without building an image. ALPYMIST_DRY_RUN=1 makes the last step report what it would run instead of touching a disk.

❯ ALPYMIST_DRY_RUN=1 cargo run -p alpymist-install

A bootable image

ARCH defaults to your machine's architecture. x86_64 is the architecture Alpymist actually targets; aarch64 is what it is developed on.

❯ make iso ARCH=x86_64
❯ make smoke ARCH=x86_64

make iso builds the builder container, the packages and the image, and leaves the ISO in out/. make smoke boots it under QEMU, reads the serial console, and checks that the first-boot probe said how Hyprland will do and explained itself.

How the packages, images and channels are built and published is written down in ci/README.md.

Repository layout

Path	Contents
`crates/`	Rust workspace: the alpymist command line and settings library, the hardware probe, the installer, splash, login and lock screens, Settings, the menu, the bar's popups and the screensavers
`aports/`	APKBUILDs for the Alpymist packages
`desktop/`	What the desktop package installs: Hyprland, bar and terminal configuration for /etc/skel, PAM and polkit rules, and the screensaver and AI usage definitions
`profiles/`	mkimage profiles and genapkovl overlays
`builder/`	The Alpine container everything is built in
`ci/`	The scripts CI and make run to build packages and images, and how publishing works
`xtask/`	Version, smoke-test and publish orchestration, in Rust
`docs/manual/`	The manual, one file a chapter
`docs/adr/`	Architecture decision records
`site/`	This web site

This site

The site is SvelteKit, prerendered to static HTML and published to GitHub Pages when site/, docs/ or the signing key in aports/alpymist-keys changes on main. The decision records are read straight from docs/adr, so editing one there updates it here.

❯ cd site
❯ npm ci
❯ npm run dev

Contributions are accepted under MIT or Apache-2.0. Security issues go through SECURITY.md, not the issue tracker.