diff options
| -rw-r--r-- | WORKFLOW.org | 149 | ||||
| -rw-r--r-- | dotfiles.org | 56 |
2 files changed, 203 insertions, 2 deletions
diff --git a/WORKFLOW.org b/WORKFLOW.org new file mode 100644 index 0000000..95fdb25 --- /dev/null +++ b/WORKFLOW.org @@ -0,0 +1,149 @@ +#+title: Workflow +#+author: cashmere + +* Overview + +This repository contains custom FreeBSD ports. The goal is to build and test them in an isolated jail using the standard FreeBSD tooling rather than ad-hoc =make DISTFILES=...= invocations. + +* Tool choice: poudriere + +After comparing the common FreeBSD port building tools: + +- *poudriere* :: The standard tool for building and testing ports in isolated jails. Supports ZFS, overlays, reproducible bulk builds, and =testport= for individual ports. Best fit for this workflow. +- *synth* :: A lighter alternative, but less commonly used for custom port trees and lacks the overlay/jail flexibility of poudriere. +- *portmaster* / plain =make= :: Good for installing packages on a live system, but do not provide isolated build environments, so they do not solve the "rebuild everything from source" problem. + +* Layout + +#+begin_example +~/ports +├── devel/ +│ ├── bash-language-server/ +│ ├── just-lsp/ +│ ├── nixd/ +│ ├── py-rassumfrassum/ +│ ├── pyrefly/ +│ └── yaml-language-server/ +├── distfiles/ # shared distfiles cache +├── misc/ +│ └── kimi-code/ +├── security/ +│ └── pinentry-emacs/ +├── WORKFLOW.org # this file +└── .agent-shell/ + └── poudriere.conf # reference config +#+end_example + +Each category directory (=devel/=, =security/=, etc.) mirrors the top-level layout of the official Ports Collection. + +* Setup instructions + +** 1. Install poudriere + +#+begin_src sh +doas pkg install -y poudriere +#+end_src + +** 2. Configure poudriere + +#+begin_src sh +doas cp ~/ports/.agent-shell/poudriere.conf /usr/local/etc/poudriere.conf +#+end_src + +Key settings: +- =ZPOOL=zroot= :: reuse the existing ZFS pool. +- =DISTFILES_CACHE=/home/cashmere/ports/distfiles= :: share the distfiles + already collected in this repo. +- =PACKAGE_FETCH_BRANCH=quarterly= and =PACKAGE_FETCH_URL=pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64= :: + tell poudriere to fetch official binary packages for dependencies instead of + compiling everything from source. + +Important: the official ports tree (=/usr/ports=) must be kept on the same +quarterly branch as the binary repository. See step 4 below. + +** 3. Create a build jail + +Use a jail matching the host version (15.1-RELEASE at the time of writing): + +#+begin_src sh +doas poudriere jail -c -j 151amd64 -v 15.1-RELEASE -a amd64 +#+end_src + +** 4. Create a ports tree overlay + +The base tree must track the same quarterly branch as the binary package +repository configured in step 2. For FreeBSD 15.1 amd64 the current quarterly +branch is =2026Q3=. + +#+begin_src sh + # Base tree from the official ports collection +doas poudriere ports -c -p base -m null -M /usr/ports + # Overlay pointing at this repository +doas poudriere ports -c -p custom -m null -M /home/cashmere/ports +#+end_src + +Then tell poudriere to use the overlay: + +#+begin_src sh +doas poudriere ports -u -p base +doas poudriere ports -u -p custom +#+end_src + +To switch an existing =/usr/ports= checkout to quarterly: + +#+begin_src sh +cd /usr/ports +git config --global --add safe.directory /usr/ports +git fetch origin 2026Q3 +git checkout -B 2026Q3 FETCH_HEAD +#+end_src + +After that, update with: + +#+begin_src sh +cd /usr/ports && git pull origin 2026Q3 +#+end_src + +* Building a port + +The easiest port to validate the workflow is =devel/py-rassumfrassum= (pure Python, small dependency tree). To build and test it in the isolated jail: + +#+begin_src sh +doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum +#+end_src + +For a bulk build of a list: + +#+begin_src sh +cat > /tmp/pkglist <<'EOF' +devel/py-rassumfrassum +EOF +doas poudriere bulk -j 151amd64 -p base -O custom -f /tmp/pkglist +#+end_src + +Once =py-rassumfrassum= builds cleanly, heavier ports like =devel/pyrefly= can be added to the list. Avoid using =security/pinentry-emacs= as a smoke test — it depends on =editors/emacs=, which pulls in a very large dependency tree (X11, GCC, etc.). + +* Validated workflow + +The following commands have been executed successfully: + +1. First run (populated the empty jail with Python dependencies): +#+begin_src sh +doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum +#+end_src +Result: success, build time ~6 seconds. + +2. Second run (reproducibility check): +#+begin_src sh +doas poudriere testport -j 151amd64 -p base -O custom -o devel/py-rassumfrassum +#+end_src +#+RESULT: success, build time ~3 seconds. + +3. Node-based port with binary package prefetching: +#+begin_src sh +doas poudriere testport -j 151amd64 -p base -O custom -o devel/bash-language-server +#+end_src +#+RESULT: success. All official-tree dependencies (=www/node24=, =devel/cmake-core=, +=devel/icu=, =dns/c-ares=, etc.) were fetched as binary packages; only +=devel/bash-language-server= from the custom overlay was built from source. + diff --git a/dotfiles.org b/dotfiles.org index 4d936cc..50c5c7f 100644 --- a/dotfiles.org +++ b/dotfiles.org @@ -295,8 +295,60 @@ $5⣅⣛⠶⠽⣧⣋⠳⡓⢿⣿⣿⣿⣿⣿⢿⣿⣿⣿⣿⣿⣿⣫⣸⠏⡋⠷ *** TODO Navidrome -*** NEXT yggdrasil +*** DONE yggdrasil +CLOSED: [2026-07-12 Sun 17:08] +:LOGBOOK: +- State "DONE" from "NEXT" [2026-07-12 Sun 17:08] +:END: ** Ports -*** [#A] Ports Management +*** DONE [#A] poudriere +CLOSED: [2026-07-12 Sun 17:07] +:LOGBOOK: +- State "DONE" from [2026-07-12 Sun 17:07] +:END: + +*** poudriere.conf + +#+begin_src conf +# /usr/local/etc/poudriere.conf + +PACKAGE_FETCH_BRANCH=quarterly +PACKAGE_FETCH_URL=pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64 + +# Use the existing ZFS pool +ZPOOL=zroot + +# Poudriere root filesystem on ZFS +ZROOTFS=/poudriere + +# FreeBSD mirror for jail creation +FREEBSD_HOST=https://download.FreeBSD.org + +# Copy host resolv.conf into the jail for network access +RESOLV_CONF=/etc/resolv.conf + +# Where poudriere keeps jails and ports trees +BASEFS=/usr/local/poudriere + +# Share distfiles with the custom ports tree to avoid re-fetching +DISTFILES_CACHE=/home/cashmere/ports/distfiles + +# Speed up builds with tmpfs +USE_TMPFS=yes + +# Optional: ccache to speed up repeated Rust/C builds +# Install devel/ccache first, then uncomment: +# CCACHE_DIR=/var/cache/ccache + +# Sanity checks +USE_PORTLINT=no +#+end_src + +* nix package manager + +#+begin_src conf :tangle ~/.config/nix/nix.conf +experimental-features = nix-command flakes +#+end_src + |