README.md (7227B)
1 # packages/ 2 3 Source package definitions for UNOS, one directory per package. 4 5 Layout follows the Void Linux convention: 6 7 ``` 8 packages/<pkgname>/ 9 |-- template # shell-sourced build definition (required) 10 |-- patches/ # optional, applied in sorted order 11 `-- files/ # optional, static files referenced by the template 12 ``` 13 14 A `template` is a shell fragment, not a script: it declares variables and 15 optionally overrides `do_*` phases: 16 17 ```sh 18 pkgname=example 19 version=1.0.0 20 revision=1 21 build_style=gnu-configure 22 hostmakedepends="pkg-config" 23 makedepends="libfoo-devel" 24 short_desc="One-line description" 25 maintainer="..." 26 license="BSD-3-Clause" 27 homepage="https://example.org" 28 distfiles="https://example.org/example-${version}.tar.gz" 29 checksum=<sha256> 30 ``` 31 32 Templates are built by our own driver (local now, CI later) into a signed 33 apk repository (v2 artifacts, apk-tools v3 manager). Nothing in this 34 directory is ever built by hand on a target switch. 35 36 ## Rules 37 38 - **Declare build dependencies.** `makedepends` lists other UNOS packages whose 39 headers/libs must be in `build/sysroot` before this one compiles; 40 `hostmakedepends` lists commands that must exist on the build host. Both are 41 enforced by `mk/build.sh` before anything is fetched, and `makedepends` is 42 what `mk/deps.sh` uses to compute build order. Keep them accurate in both 43 directions: a missing entry breaks a clean-checkout build, and a spurious one 44 fails a build that would otherwise work. `depends` is runtime only and does 45 **not** affect build order, so a package needed at both times appears twice 46 (see `gptfdisk`). 47 - **Pin everything.** Explicit versions and recorded checksums. No moving 48 targets, no floating branches. 49 - **Third-party source uses `distfiles=` and must carry `checksum=`.** The 50 driver refuses to build a template that sets `distfiles` without a matching 51 sha256, because there we are trusting a server nobody here controls. 52 - **Our own source uses `srcfiles=` and carries no checksum.** It is fetched by 53 tag from `git.finwo.net`; the tag is the pin and TLS is the transport. A 54 forge regenerates tag archives on demand, so they are not byte-stable and a 55 recorded sha256 would eventually fail for reasons indistinguishable from 56 tampering. Setting `checksum=` alongside `srcfiles=` is an error, as is 57 setting both `srcfiles=` and `distfiles=` -- whichever is present supplies 58 the tarball `WRKSRC` is derived from, and two sources would make that choice 59 silent and arbitrary. Only `linkd` uses this today. 60 - **Never vendor upstream source into this repository.** Sources are fetched at 61 build time from a pinned revision. This keeps history small and keeps our 62 licensing story unambiguous. 63 - **Preserve vendor notices.** Templates that patch third-party code must not 64 strip copyright headers. This is a binding condition of the Broadcom SDK 65 licence, and stripping headers is the single easiest way to breach it. 66 - **Kernel-coupled packages must rebuild with the kernel.** Anything producing 67 a `.ko` has to be rebuilt whenever the `linux` package changes; a stale module 68 fails at `insmod` time on the switch, which is the worst possible place to 69 find out. 70 - **Shared-only C libraries.** Nothing in UNOS links statically, so library 71 templates pass `--disable-static` (or equivalent) and must not ship `.a` 72 files. Keep the rootfs lean; revisit only if a static-link need appears. 73 - **Build-time sysroot (`build/sysroot`, generated, never committed).** 74 Libraries that other packages build against install twice: once into 75 `DESTDIR` (the shipped `.apk`) and once into `SYSROOT` (headers + `.so` + 76 `.pc` files). The driver exports `SYSROOT` and `UNOS_MKDIR` (the mk/ 77 directory - never `MKDIR`, which collides with libtool's internal 78 `$MKDIR`), prepends `build/host/bin` (host tools like muon) to `PATH`, 79 and points `PKG_CONFIG_PATH` at the sysroot. The driver centrally 80 rewrites every sysroot `.pc` after `do_install` (all of `prefix=`, 81 `libdir=`, `includedir` to `${SYSROOT}/usr` paths) - hand-rolled 82 per-template `sed` of only `prefix=` is insufficient (efivar's 83 `libdir=/includedir=` are literal, not `${prefix}`-relative, so a 84 prefix-only rewrite left consumers on host `/usr/include`). Templates 85 only double-install and assert presence; the driver fixes the paths. 86 efivar additionally patches its `.pc.in` before generation to expose 87 both `-I${includedir}` and `-I${includedir}/efivar` (upstream only 88 ships the subdir, which relies on host `/usr/include` as an implicit 89 search path - absent in a sysroot). 90 - **Loader cache is generated, never shipped.** The loader's baked-in 91 search covers `/lib64` + `/usr/lib64` only, so every library package 92 carries a `files/post-install` running `exec /sbin/ldconfig` (absolute: 93 glibc installs it to `/sbin`, and the busybox applet is compiled out). 94 Script-bearing packages order themselves with `depends="glibc busybox"` 95 (`/bin/sh` must exist before apk runs their scripts). `mk/rootfs.sh` 96 additionally runs `ldconfig` explicitly after assembly so the chroot 97 cache never depends on script-execution order. 98 - **Subpackages: one template, several .apks.** A template may declare 99 `subpackages="name ..."` with per-sub `short_desc_<underscored>` / 100 `depends_<underscored>` (provides/replaces optional) and a 101 `sub_<underscored>()` function partitioning `DESTDIR` into `SUBDEST` 102 via `spick` (move semantics - never duplicated). Per-subpackage control 103 scripts live at `files/<script>.<subname>` (e.g. 104 `post-install.linux`). After all splits `DESTDIR` must be empty: the 105 primary packs the remainder, so meta primaries are empty by 106 construction. Version pins between outputs must carry the full pkgver 107 incl. `-r` (`depends="linux=${version}-r${revision}"`) - apk's `=` 108 never matches a bare version. Single-output templates are unaffected. 109 - **Control scripts run chrooted via memfd.** apk v3 executes scripts 110 through `/proc/self/fd`, so any `apk add` that runs scripts needs 111 `/proc` mounted in the target (live systems always have it; 112 `mk/rootfs.sh` binds it for assembly; the installer must too). 113 - **Kernel image symlink.** `mk/kernel.inc` installs both 114 `/boot/vmlinuz-${KREL}` and `/boot/vmlinuz -> vmlinuz-${KREL}`; the 115 static `grub.cfg` references the generic path. Older images had only 116 the versioned name - the installer creates the symlink idempotently 117 after unpacking rootfs, so both old and new images boot. 118 - **GRUB is UEFI-only in this tree.** `packages/grub` builds 119 `x86_64-efi` only; `i386-pc` fails under binutils 2.44 (mislinked 120 `kernel.img` `.text` at 0x9074 vs 0x9000, `grub-mkimage` fail-louds). 121 The installer dies on BIOS firmware with a clear message; revisit 122 when binutils is fixed or upstream works around it. The grub package 123 prunes `grub-mkconfig` - the static `grub.cfg` is rendered by the 124 installer and checked with shipped `grub-script-check`. 125 - **Host-independence.** `iproute2` scrubs autotools-appended optionals 126 (`HAVE_ELF` etc.) and asserts `NEEDED` is subset of {libmnl,libcap,libc}; `grub` 127 trims freetype/tasn1/fuse/zfs/dm; all `CPPFLAGS/LDFLAGS` are 128 sysroot-first. A build must not silently pick up host libraries.