Building from Source

Building from Source

Toolchain

Pinned in rust-toolchain.toml:

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy"]

rustup will install the right components on first build. Minimum Rust version: 1.85 (edition 2024).

System dependencies

You need development headers for:

Library	Arch	Debian / Ubuntu	Fedora
libpam	pam	libpam0g-dev	pam-devel
Wayland client	wayland	libwayland-dev	wayland-devel
xkbcommon	libxkbcommon	libxkbcommon-dev	libxkbcommon-devel
fontconfig	fontconfig	libfontconfig1-dev	fontconfig-devel
freetype	freetype2	libfreetype6-dev	freetype-devel
pkg-config	pkgconf	pkg-config	pkgconf-pkg-config
wayland-protocols	wayland-protocols	wayland-protocols	wayland-protocols-devel

Optional but recommended at runtime:

• vulkan-icd-loader (Arch) / libvulkan1 + mesa-vulkan-drivers (Debian) — wgpu prefers Vulkan, falls back to llvmpipe otherwise.

Cargo workspace

Cargo.toml                       # workspace root
crates/pam-sentinel/             # cdylib → /usr/lib/security/pam_sentinel.so
crates/sentinel-helper/          # bin    → /usr/lib/sentinel-helper

Build

just build
# or, manually:
cargo build --release --workspace

Build-time install paths

Install paths are baked into the binaries via build.rs reading env vars. Defaults shown:

SENTINEL_PREFIX=/usr \
SENTINEL_SYSCONFDIR=/etc \
SENTINEL_LIBEXECDIR=lib \
    cargo build --release --workspace

Used to resolve:

• HELPER_PATH = $PREFIX/$LIBEXECDIR/sentinel-helper
• CONFIG_PATH = $SYSCONFDIR/security/sentinel.conf

The pam_sentinel.so binary contains these strings statically, so relocating after build won't work — rebuild with the prefix you want.

Cargo features

sentinel-helper builds against libcosmic with these feature flags:

features = ["wayland", "winit", "tokio", "multi-window"]

multi-window is required for the layer-shell daemon path. There are no project-specific feature flags exposed today.

Useful just recipes

just build           # cargo build --release --workspace
just check           # cargo fmt --check + cargo clippy -D warnings
just helper-test     # run the helper as a layer-shell overlay
just helper-test-windowed   # render as xdg-toplevel (debug)
just install         # cargo build + pkexec ./install.sh
just uninstall       # pkexec ./uninstall.sh
just dev-test        # PAM-stack integration test via pamtester

CI

The release workflow at .github/workflows/release.yml runs on tag push (v*):

1. Builds the workspace.
2. Builds source + binary tarballs via scripts/build-release.sh.
3. Builds .deb via cargo deb.
4. Builds .rpm via cargo generate-rpm.
5. Creates a GitHub release with notes from .github/release-notes/v$ver.md.

There is no per-commit CI today (no clippy/test workflow on PR). PRs should run just check and just helper-test locally before submission.