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