// docs

About

Overview

krypt/sh is a source-based Linux distribution built on a pure LLVM/musl toolchain. The entire system is compiled with clang/clang++ against musl libc — there is no GCC and no glibc anywhere in the base system.

Requirements

Architecture: x86_64 only.
Firmware: UEFI only — legacy BIOS is not supported.
RAM: 16 GB recommended for building packages from source.
Disk: 20 GB minimum for a base system. More for a full ports tree with sources.

Toolchain

The core toolchain consists of LLVM (clang, lld, llvm-tools), musl (libc), compiler-rt (builtins and sanitizers), libc++ (C++ standard library), and libunwind (stack unwinding). GCC compatibility shims are provided where needed — libgcc_s.so symlinks to libunwind and libstdc++.so symlinks to libc++ — so software expecting GNU toolchain components works without modification.

LLVM GPU targets

The llvm-toolchain port is built with AMDGPU as the default GPU backend target. This is required by Mesa for AMD Radeon shader compilation (radeonsi, radv) and by the LLVM-based software rasterizer (llvmpipe). If your system uses different hardware, you can change the targets and rebuild:

# Edit the llvm-toolchain MAKEPKG
# cd /ports/core/llvm-toolchain
# vi MAKEPKG
# Find the -DLLVM_TARGETS_TO_BUILD line and adjust:
#   AMDGPU    — AMD Radeon (required for radeonsi/radv)
#   NVPTX     — NVIDIA (compute/CUDA)
#   X86       — always required
# Rebuild and upgrade
# mkpkg -c && mkpkg -d
# addpkg -u llvm-toolchain#*.pkg.tar.gz
# Then rebuild Mesa to pick up the new backend
# cd /usr/ports/xorg/mesa
# mkpkg -c && mkpkg -d
# addpkg -u mesa#*.pkg.tar.gz

Intel GPUs do not need an LLVM backend target — Intel's Mesa drivers (iris, anv) use their own compiler stack. If you run Intel-only graphics, you can remove AMDGPU entirely to reduce the LLVM build time and binary size.

Installation model

krypt/sh uses a hybrid installation model. During initial installation, pre-built binary packages are fetched over the network and installed with addpkg. Once the system is running, you transition to source-based updates and customization through the ports system — syncing port trees, building packages with mkpkg, and managing dependencies with pkg.

Getting help

Join #krypt/sh on Libera.Chat for support, questions, and discussion.

Filesystem Layout

krypt/sh uses a flat library layout — there is no lib32, lib64, or multilib. Libraries live in /lib and /usr/lib, period. This reflects the single-arch, single-libc nature of the system.

The filesystem splits into two install prefixes. The ports tree mirrors this split directly:

# Root prefix — core system (packages from /ports/core) / ├── bin/ # essential binaries ├── boot/ │ └── efi/ # EFI system partition mount ├── etc/ │ ├── boot.d/ # boot-time setup scripts │ ├── ports/ # ports sync configuration │ ├── profile.d/ # shell environment scripts │ ├── ssl/ # certificates │ └── sv/ # runit service definitions ├── home/ ├── include/ # core headers ├── lib/ # core libraries (no lib32, no lib64) │ └── firmware/ ├── media/ ├── mnt/ ├── ports/ │ └── core/ # core ports → install to / ├── root/ # root home directory ├── sbin/ # essential system binaries ├── service/ # supervised services (symlinks → /etc/sv) ├── src/ ├── usr/ │ ├── bin/ # user binaries │ ├── include/ # user headers │ ├── lib/ # user libraries + pkgconfig │ ├── ports/ # non-core ports → install to /usr │ │ ├── devel/ # development tools │ │ ├── libs/ # shared libraries │ │ ├── opt/ # optional apps │ │ ├── perl/ # perl modules │ │ ├── python/ # python modules │ │ └── xorg/ # graphical stack │ └── share/ # man pages, data, etc. └── var/ └── lib/ └── pkg/ # package database & dependency db

The rule is simple: packages in /ports/core install into the root prefix (/bin, /sbin, /lib). Packages in /usr/ports/* install into the /usr prefix (/usr/bin, /usr/lib). This is set by --prefix=/ vs --prefix=/usr in each port's build function.

The setup-filesystem script creates this entire skeleton, including /var/lib/pkg/db (the empty package database), default /etc/passwd, /etc/group, /etc/profile, and other base configuration files. It must be run before any packages are installed.

XDG runtime directories

krypt/sh sets up XDG base directories through two scripts rather than relying on elogind, dumb_runtime_dir, or session managers. This means Wayland compositors work out of the box with no extra session infrastructure.

/etc/profile.d/xdg.sh exports the environment variables on login:

#!/bin/sh
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_CACHE_HOME="$HOME/.cache"
export XDG_RUNTIME_DIR=/run/user/$(id -u)

/etc/boot.d/xdg-runtime creates the runtime directories at boot for each user:

#!/bin/sh
# Create XDG_RUNTIME_DIR for root and regular users
for user in root $(awk -F: '$3 >= 1000 && $3 < 65534 {print $1}' /etc/passwd); do
    uid=$(id -u "$user")
    dir=/run/user/$uid
    mkdir -p "$dir"
    chmod 0700 "$dir"
    chown "$user":"$user" "$dir"
done

No PAM, no elogind

krypt/sh does not use Linux-PAM or elogind. Authentication is handled by traditional shadow utilities. Session setup — XDG runtime directories, seat management via seatd — is done with minimal, purpose-built scripts that interface directly with the system rather than through abstraction layers.