docs - zygaena/zports

root / docs
docs Plain Text 437 lines 40.1 KB
# Coral issues found during the XLibre desktop ports effort

Bug reports / improvement notes for the **Coral team** (we do not patch Coral source — per project policy). File these upstream as appropriate.

---

## CORAL-1: `coral build <category>/<name>` (relative path) fails exit 127

- **Found:** 2026-07-22, building `base/util-macros` on hh-alpha9 (Hammerhead), coral **0.4.5**.
- **Severity:** High (blocks every relative-path build; silent-ish — exits 127 with a confusing "can't open input file" error).

### Symptom
```
$ cd /usr/zports && coral build base/util-macros -y
...
cd "$SRCDIR" && export ... && zsh "base/util-macros/build.sh"
zsh: can't open input file: base/util-macros/build.sh    # exit 127
```

### Root cause (from reading Coral source — NOT modified)
`coral build <category>/<name>` stores the CLI path string verbatim as `port.port_dir`
(`src/core/port.reef:397` — `port.port_dir = port_path`). Later, the build step joins it
with `build.sh` (`src/commands/build.reef:974` — `path.join_path(ctx.port.port_dir, "build.sh")`)
and hands that **relative** path to a shell that has **already `cd`'d into `$SRCDIR`** (the
extracted-tarball work dir). Because cwd changed, the relative port path no longer resolves,
so `zsh <relative>/build.sh` can't find the script. Happens for any relative CLI port argument
regardless of the invoking cwd.

### Workaround (in use)
Always pass an **absolute** port path:
```
coral build /usr/zports/base/util-macros -y      # works
```

### Suggested fix (for the Coral team)
Resolve `port_dir` to an absolute path at load time (in `port.reef` when `port_dir` is set),
**or** compute `build.sh`'s absolute path before the `cd "$SRCDIR"` in `build.reef`, so the
build-script path is independent of the shell's working directory.

---

## CORAL-2: source download fails against some HTTPS hosts that system `curl` fetches fine

- **Found:** 2026-07-22, building `devel/nasm` on hh-alpha9 (Hammerhead), coral **0.4.5**.
- **Severity:** Medium (blocks `coral build` for any port sourced from an affected host;
  has a reliable workaround, so not a hard blocker).

### Symptom
```
$ coral build /usr/zports/devel/nasm -y
...
-> Downloading sources...
error: Failed to download: nasm-2.16.03.tar.xz (all sources failed)
error: Failed to download sources
```
No further detail in either the console output or the per-build log
(`.../coral-build-nasm-*.log` — just "Failed to download sources", nothing from
the underlying transport). `-v`/`--verbose` on the `build` subcommand adds nothing.

### What did NOT reproduce it
- `curl -L -f -s -S -o ... https://www.nasm.us/pub/nasm/releasebuilds/2.16.03/nasm-2.16.03.tar.xz`
  (the exact flag set `strings /usr/bin/coral` shows coral invoking) succeeds from the
  same host, as both `root` and the unprivileged `zygaena` build user.
- Same URL over plain `openssl s_client` completes a full TLS handshake and the server
  presents a chain openssl considers valid.
- The same port category/build machinery worked fine minutes earlier and later for
  `base/util-macros` (`xorg.freedesktop.org`), `lang/python` (`www.python.org`),
  `devel/ninja` (`github.com`/`codeload.github.com`) — all HTTPS, all succeeded via
  `coral build`'s normal download path.

### Suspected root cause (not confirmed — read-only investigation, Coral not modified)
The one systematic difference found between the failing host and the working ones is
the TLS certificate chain's intermediate/root naming:
```
$ echo | openssl s_client -connect www.nasm.us:443 -servername www.nasm.us
 0 s:CN=www.nasm.us
   i:C=US, O=Let's Encrypt, CN=YR2      <-- unusual intermediate name
```
vs. e.g. `xorg.freedesktop.org`'s chain terminating in the well-known `ISRG Root X1` /
`R13` naming. `strings /usr/bin/coral` shows the binary statically links its own
OpenSSL (many `OSSL_*`/`SSL_CTX_*` symbols) rather than shelling out to the system's
`curl`/OpenSSL for the actual source-tarball fetch (curl only shows up in strings next
to repository-manifest/signature messages, e.g. `(using curl) ...`, `No signature
found (repo.toml.sig)`). Working theory: coral's statically-linked OpenSSL carries an
older/incomplete embedded CA trust store that doesn't recognize this particular
Let's Encrypt intermediate, while the system `curl`/`openssl` (using the OS trust
store) verifies it fine. Not confirmed with a packet capture — filed as a lead, not
a diagnosis, for the Coral team to verify against their embedded trust store.

### Workaround (in use)
Pre-populate coral's source cache before calling `coral build` — coral trusts a
checksum-matching file already sitting in `[paths].sources` (`/usr/zports/pkgs/sources`
by default) and skips its own download entirely:
```
# download with system curl (or scp from a host that can), verify sha256 first
curl -sL -o nasm-2.16.03.tar.xz https://www.nasm.us/pub/nasm/releasebuilds/2.16.03/nasm-2.16.03.tar.xz
sha256sum nasm-2.16.03.tar.xz   # confirm matches package.toml's checksum
scp nasm-2.16.03.tar.xz root@<build-host>:/usr/zports/pkgs/sources/nasm-2.16.03.tar.xz
coral build /usr/zports/devel/nasm -y   # now logs "Using cached: nasm-2.16.03.tar.xz"
```
Confirmed both `devel/nasm` (nasm.us) and, pre-emptively for `devel/ninja`/`devel/meson`
(github.com), that priming the cache this way lets `coral build` proceed normally
(checksum verify → extract → build) with no other change needed.

### Suggested fix (for the Coral team)
1. Surface the underlying TLS/transport error instead of the generic "Failed to
   download: ... (all sources failed)" — even the per-build log has nothing more
   specific, making this look identical to a dead URL or an actual checksum failure.
2. Refresh/replace the embedded CA trust store (or link against the system trust
   store / system curl for source fetches) so `coral build` isn't a stricter TLS
   client than the OS it runs on.
# XLibre Desktop — Phase 1a Results

**Completed:** 2026-07-22 on hh-alpha9. **Outcome: a working XLibre + Openbox X11 desktop over VNC**, built entirely from zports via Coral. Screenshot: `hammerhead/docs/roadmap/hammerhead-desktop-phase1a.png` (Openbox-decorated `st` terminal, `root@hammerhead` shell, 1280×800).

## What shipped
**57 packages** installed on alpha9. New ports this phase (~50), by layer:
- **Tooling:** util-macros, nasm, meson, gperf, unzip (+ built existing python, ninja, mercurial)
- **Protocol:** xorgproto, xtrans, xcb-proto
- **Client libs (M2):** libpthread-stubs, libXau, libXdmcp, libxcb, libX11, libXext, libXrender, libXfixes, libXdamage, libXrandr, libXi, libXtst, libXcursor, libXinerama, libXcomposite, libICE, libSM, libXt, libXmu, libXpm, pixman, libxkbfile
- **Font/render (M3):** libpng, libjpeg-turbo, freetype, fontconfig, libfontenc, libXfont2, libXft, font-util, dejavu-fonts, pcre2, glib2 (2.88.2), fribidi, harfbuzz, cairo, pango
- **Server + runtime (M4):** xlibre-xserver (25.1.8, Xvfb), xkbcomp, xkeyboard-config, xauth, xinit, libvncserver, x11vnc
- **Desktop (M5):** openbox (3.6.1), st (0.9.3)

## Verified milestone
`Xvfb :99` + a libX11 client → `CLIENT CONNECTED: 1024x768 depth 24, vendor=XLibre`. Full stack (Xvfb+openbox+st+x11vnc) runs on alpha9:5900; screenshot shows the live interactive desktop.

## Systemic illumos-porting gotchas found + standardized (in plan templates + memory)
1. **libtool static-only** — pre-generated `configure` lacks a hammerhead arm → silent `.a`-only builds. Fix: sed the `dynamic_linker` case (nested for freetype: `builds/unix/configure`).
2. **`__EXTENSIONS__` + `_POSIX_PTHREAD_SEMANTICS`** — illumos hides POSIX/BSD prototypes + uses Solaris-draft `_r` signatures without them; meson's `has_function()` false-positives.
3. **Meson rpath** — Meson strips rpath on install + `/usr/local/lib` not on default ld path → bake `-R$PREFIX/lib` (+ added `/usr/local/lib` to alpha9 `crle`).
4. **Hammerhead sysname ≠ `sunos`** — recurred in glib meson checks and the XLibre server os-layer (patched).
5. **autoreconf regenerates config.sub** without the hammerhead patch; **CMake bundled-static needs `-DCMAKE_POSITION_INDEPENDENT_CODE=ON`**; **coral needs `unzip`** for .zip sources.

## Coral bugs filed (see CORAL_ISSUES.md) — for the Coral team
- **CORAL-1:** relative `coral build <cat>/<name>` exit-127-fails (use absolute path).
- **CORAL-2:** bundled TLS trust store rejects some hosts (nasm.us) — pre-stage the tarball.

## XLibre patches (upstream candidates — stored in `base/xlibre-xserver/patches/`)
- **0001** — extend the `os/meson.build` `sunos` guard to accept Hammerhead's sysname (lights up `-lsocket`/`-lnsl`).
- **0002** — fix inverted re-arm check in the illumos event-ports (`PORT_SOURCE_FD`) `ospoll` backend; without it the server accepted only ONE client for its lifetime. Worth contributing back to XLibre.

## Workflow
Mercurial on both machines: author on Linux → `hg commit`/`push` → alpha9 `hg pull -u` → `coral build` (absolute path). Ports build + test on alpha9 (single-VM ports pattern). alpha8 remains the base-OS build VM; alpha7 retired.

## Next
Phase 1b — lightweight X11-native CBPP-look desktop (tint2, conky, picom, feh, dmenu + mpv/mupdf/nnn). Phase 1c — Qt6 + LXQt durable rich-app tier. Phase 2 — native VM console (retarget kdrive/Xfbdev to illumos `visual_io`). See `hammerhead/docs/roadmap/DESKTOP_XLIBRE_OPENBOX.md`.
# Zygaena Desktop — Phase 1b Results

**Completed:** 2026-07-23 on hh-alpha9. **Outcome: a cohesive, Hammerhead-branded, GTK-free X11 desktop** built entirely from zports via Coral, running over VNC. Screenshots: `hammerhead/docs/roadmap/hammerhead-desktop-phase1b.png` (working desktop: Xfe + XNEdit + conky) and `...-showcase.png` (wallpaper wordmark + terminal + conky).

## What shipped (~26 new ports; 83 packages total)
- **Shell:** tint2 16.2 (panel), conky 1.24.2 (**native illumos/kstat stats** — CPU/mem/disk/net/load), picom 13 (xrender compositor), feh 3.12.2 (wallpaper + image viewer), dmenu 5.4.
- **Apps:** Xfe 1.x (FOX file manager), mupdf 1.28.0 (PDF), neovim 0.11.6 (terminal editor), XNEdit 1.6.3 (Motif GUI editor).
- **Toolkit/deps:** imlib2, lua 5.4.8, libconfig, libev, fox-toolkit 1.6.59, motif 2.3.8 (+xbitmaps), + neovim's tree (libuv, msgpack-c, unibilium, libtermkey, libvterm, tree-sitter), + picom's (3 xcb-util libs, uthash).
- **Branding:** `hammerhead-desktop` config port — a cairo-generated marine-dark wallpaper (teal hammerhead-shark motif, sonar arcs, "HAMMERHEAD / ZYGAENA" wordmark), dark Openbox theme with teal accent, matching tint2 + conky configs, branded Openbox menu/keybinds, autostart.

## New systemic gotchas found + recorded (plan checklist + memory)
- **GCC 14 promotes old-C warnings to errors** (`-Wincompatible-pointer-types`, implicit-function-declaration, int-conversion) → per-port `-fpermissive -fcommon` (motif, mupdf, XNEdit, unzip).
- **illumos `<sys/types.h>` short typedefs** (`index_t`, `level_t`, …) collide with app identifiers → per-file `#define index_t mu_index_t` (mupdf).
- illumos `<sys/stream.h>` `struct queue` tag collision (neovim); `__illumos__` vs `__sun` compiler-define gap (tree-sitter, neovim); Motif Xft-detection + strings.h-ordering + iconv/_XPG6 patches; FOX `HAVE_SYS_FILIO_H`.

## Toolkit-durability held
100% GTK-free: FOX (Xfe), Motif (XNEdit), cairo/imlib2/lua, X11-native shell. Qt deferred to Phase 1c. (See [[x11-toolkit-durability-gtk-vs-qt]].)

## Notes
- neovim uses its bundled LuaJIT (needs Lua 5.1; our lua is 5.4) — the 6 M0b system libs are installed and available but not consumed by neovim-as-built.
- mupdf built with bundled thirdparty (freetype/harfbuzz/jbig2dec/openjpeg/mujs).
- Live desktop left running on alpha9:5900.

## Next
Phase 1c — Qt6 + LXQt durable rich-app tier. Phase 2 — native VM console (retarget kdrive/Xfbdev to illumos `visual_io`; switch VM off VGA-text to a linear framebuffer). See `hammerhead/docs/roadmap/DESKTOP_XLIBRE_PHASE1B.md`.
# XLibre upstream bug reports (illumos / Solaris os-support)

Draft reports for filing at https://github.com/X11Libre/xserver/issues.
Found building XLibre xserver **25.1.8** for Hammerhead (an illumos fork).
Root cause for each: XLibre CI has no illumos/Solaris target, so the
`hw/xfree86/os-support/solaris/` backend and the Solaris event-ports code paths
are unexercised. Local patches live in `zports/base/xlibre-xserver-xorg/patches/`.

---

## Bug 1 — Threaded input busy-loops on Solaris/illumos (event-ports ospoll), pegging ~2 CPUs

**Severity:** high (100% CPU on two cores at idle). **Component:** `os/inputthread.c`, `os/ospoll.c` (Solaris `PORT_SOURCE_FD` backend).

**Symptom:** On illumos with a real input device, Xorg pegs ~2 full cores while idle. `prstat -mL` shows two server threads at 100% (`[MainThread]` + `[InputThread]`); `mpstat` shows ~1,000,000 syscalls/sec; DTrace shows the InputThread doing `portfs`+`write` 1:1 (~340k/s) and the MainThread `portfs`+`read` 1:1 (~225k/s). `pfiles` shows the two hot fds are the **input-thread → main-thread wakeup self-pipe**, not the input devices (which read fine, errno 0).

**Cause:** the threaded-input wakeup pipe fd, registered in the InputThread's ospoll (Solaris event-ports / `port_associate` backend), is re-armed reporting `POLLIN` "ready" every cycle with nothing to deliver, so InputThread and MainThread ping-pong on the self-pipe as fast as the CPU allows. Event ports are one-shot (must re-`port_associate` after `port_get`); the re-arm appears to fire on an already-drained/edge condition.

**Repro:** run Xorg on illumos with `xf86-input-keyboard`/`-mouse` and a real `/dev/kbd`+`/dev/mouse`. XLibre also **removed** the historic `-noThreadedInput` command-line flag (only `-dumbSched` still disables the input thread, as a side effect of disabling the smart scheduler).

**Workaround in use:** patch `os/inputthread.c` default `InputThreadEnable = TRUE` → `FALSE` (input serviced in the main dispatch loop; pre-2016 default). Proper fix: correct the event-ports ospoll re-arm so a drained fd is not re-reported ready.

---

## Bug 2 — `sun_apm.c` fails to build: PM hook declarations moved to `xf86_priv.h`, Solaris backend not updated

**Severity:** medium (build break on the only platform that compiles it). **Component:** `hw/xfree86/os-support/solaris/sun_apm.c`.

**Symptom:** `xf86OSPMOpen()` fails to compile on illumos under GCC 14 with `xf86PMGetEventFromOs`/`xf86PMConfirmEventToOs`/`xf86HandlePMEvents` undeclared (hard error).

**Cause:** XLibre moved the power-management hook declarations into `hw/xfree86/common/xf86_priv.h` (lowercase-underscore) and updated the Linux backend (`lnx_apm.c`/`lnx_acpi.c` now include `"xf86_priv.h"`) but **not** the Solaris backend — `sun_apm.c` still includes only `"xf86Priv.h"` (capital-P, a different header).

**Fix:** add `#include "xf86_priv.h"` to `sun_apm.c` (matching `lnx_apm.c`). One line.

---

## Bug 3 — `os/meson.build` / os-support `sunos` guards don't match a downstream illumos sysname

**Severity:** low (portability; only bites forks whose `uname` isn't `SunOS`). **Component:** `os/meson.build`, `hw/xfree86/os-support/meson.build`.

**Symptom/Cause:** the Meson os-support selection keys the Solaris backend on `sunos`; a Solaris-derived OS reporting a different `system()` name (here `hammerhead`) silently gets no Solaris os-support and fails to link the console/VT layer. (Reported for awareness — an illumos-derived downstream, not stock illumos, so may be WONTFIX; the pattern of extending the `sunos` case is the same one the Linux backends already use for kFreeBSD etc.)

**Workaround:** extend the `sunos` arm to also accept the downstream sysname.
# XLibre Phase 1a Dependency Manifest

Authoritative version/dependency manifest for the Phase-1a XLibre X11 desktop
port set (XLibre Xvfb server + Openbox) on Hammerhead, built via Coral from
the zports tree. This is Task 0 output — every later per-port task consumes
this file as its source of truth.

Generated 2026-07-22. Sources mined (priority order): X11Libre's own
packaging (`X11Libre/ports-gentoo`, `X11Libre/pkgbuilds-arch-based`),
XLibre `xserver` repo `meson_options.txt`/`meson.build`, and
freedesktop.org / GNU / GitHub upstream release pages for the client
libs and render/font stack.

**Checksum policy**: sha256 recorded where an upstream/publisher hash was
found; otherwise `compute-on-fetch` — the per-port task must `sha256sum`
the actual downloaded distfile and fill it in. No hash in this table was
fabricated.

## XLibre Xvfb-only meson configuration (Task 7 blocker — READ THIS)

Confirmed by reading `X11Libre/xserver` `meson_options.txt` directly
(fetched from `https://raw.githubusercontent.com/X11Libre/xserver/master/meson_options.txt`)
and cross-checked against the Gentoo ebuild's `src_configure()` in
`X11Libre/ports-gentoo` (`x11-base/xlibre-server/xlibre-server-25.1.8.ebuild`,
which maps Gentoo USE flags to these exact meson option names 1:1 via
`meson_use`).

Relevant option definitions (verbatim names/types/defaults from
`meson_options.txt`):

- `xvfb` — boolean, **default `true`** — "Enable Xvfb X server"
- `xorg` — combo(true/false/auto), default `auto` — "Enable Xorg X Server"
- `xephyr` — boolean, default `false`
- `xnest` — combo, default `auto`
- `xfbdev` — boolean, default `false`
- `xwin` — combo, default `auto`
- `xquartz` — combo, default `auto`
- `glamor` — combo, default `auto`
- `glx` — boolean, default `true`
- `glx_dri` — combo, default `auto`
- `dri1` / `dri2` / `dri3` — combo, default `auto` each
- `gbm` — combo, default `auto`
- `drm` — boolean, default `true`
- `udev` / `udev_kms` — combo, default `auto`
- `hal` — combo, default `false`
- `systemd_logind` / `systemd_notify` — combo, default `false`
- `seatd_libseat` — combo, default `auto`
- `suid_wrapper` — boolean, default `false`
- `xcsecurity` — boolean, default `false`
- `xselinux` — combo, default `auto`
- `pciaccess` — boolean, default `true`
- `agp` — combo, default `auto`
- `int10` — combo(stub/x86emu/vm86/auto/false), default `auto`
- `vgahw` — combo, default `auto`
- `xf86bigfont` — boolean, default `false`
- `tests` — boolean, default `true`
- `xf86-input-inputtest` / `xf86-input-null` — boolean, default `true` each
- `docs` / `devel-docs` / `docs-pdf` — combo, default `auto`
- `dtrace` — boolean, default `false`
- `linux_acpi` / `linux_apm` — boolean, default `true` each (Linux-only code paths anyway)
- `sha1` — combo, choices `libc|CommonCrypto|CryptoAPI|libmd|libsha1|libnettle|libgcrypt|libcrypto|auto`, default `auto`
- `xkb_output_dir` — string

### Recommended Xvfb-only meson invocation for Hammerhead

```
meson setup build \
  -Dxvfb=true \
  -Dxorg=false \
  -Dxephyr=false \
  -Dxnest=false \
  -Dxfbdev=false \
  -Dxwin=false \
  -Dxquartz=false \
  -Dglamor=false \
  -Dglx=false \
  -Dglx_dri=false \
  -Ddri1=false \
  -Ddri2=false \
  -Ddri3=false \
  -Dgbm=false \
  -Ddrm=false \
  -Dudev=false \
  -Dudev_kms=false \
  -Dhal=false \
  -Dsystemd_logind=false \
  -Dsystemd_notify=false \
  -Dseatd_libseat=false \
  -Dsuid_wrapper=false \
  -Dxcsecurity=false \
  -Dxselinux=false \
  -Dpciaccess=false \
  -Dagp=false \
  -Dint10=false \
  -Dvgahw=false \
  -Dxf86bigfont=false \
  -Dtests=false \
  -Ddocs=false \
  -Ddevel-docs=false \
  -Ddocs-pdf=false \
  -Dxf86-input-inputtest=false \
  -Dxf86-input-null=false \
  -Ddtrace=false \
  -Dlinux_acpi=false \
  -Dlinux_apm=false \
  -Dsha1=libcrypto \
  -Dxkb_output_dir=/var/lib/xkb
```

Notes:
- `-Dsha1=libcrypto` matches the Gentoo ebuild's choice and Hammerhead
  already ships OpenSSL 3.5 in base — reuse it rather than pulling in
  libgcrypt/libnettle/libmd as a new dep.
- `linux_acpi`/`linux_apm` gate Linux-specific code paths; harmless to
  leave `false` on illumos regardless of the option's stated default.
- `ipv6` and `input_thread` left at their `auto` defaults; no Xvfb-specific
  reason to force them.
- The ebuild's `REQUIRED_USE` shows `glx-dri? ( glx )` — since we disable
  both here that constraint is moot.
- Gentoo's CDEPEND still lists `libdrm`, `libpciaccess`, `libglvnd` etc.
  unconditionally because Gentoo's meson.build has hard `dependency()`
  calls gated by those same options — Task 7 must verify at meson-configure
  time on Hammerhead whether the build **still probes for** libdrm/mesa
  even with `-Ddrm=false` (illumos has no libdrm/mesa in this port set).
  If meson.build hard-requires them regardless of the option, that is a
  patch Task 7 will need, not a manifest problem.

## Port table

| category | name | version | source_url | sha256 | build_system | runtime_deps | build_deps | special_flags/notes |
|---|---|---|---|---|---|---|---|---|
| devel | meson | 1.11.2 | https://github.com/mesonbuild/meson/releases/download/1.11.2/meson-1.11.2.tar.gz | compute-on-fetch | python | python3 | ninja | Python package; verify ninja already in zports/base. |
| devel | nasm | 2.16.03 | https://www.nasm.us/pub/nasm/releasebuilds/2.16.03/nasm-2.16.03.tar.xz | compute-on-fetch | autotools | — | — | Only needed if any dep (libjpeg-turbo SIMD) wants it; libjpeg-turbo build can also use `-DWITH_SIMD=0` to avoid nasm entirely if bootstrap is easier. |
| devel | gettext | 0.26 | https://ftp.gnu.org/gnu/gettext/gettext-0.26.tar.gz | compute-on-fetch | autotools | — | — | Extra build tool per brief's ask; needed by fontconfig/glib/pango i18n build steps if not already in zports. |
| devel | gperf | 3.3 | https://ftp.gnu.org/gnu/gperf/gperf-3.3.tar.gz | compute-on-fetch | autotools | — | — | Extra build tool per brief's ask; used by some xkbcomp/libX11 codegen paths. Verify actual need at Task 2/3 (may already be satisfied by base gcc toolchain's bundled gperf, if any). |
| protocol/glue | util-macros | 1.20.2 | https://xorg.freedesktop.org/releases/individual/util/util-macros-1.20.2.tar.xz | compute-on-fetch | autotools | — | — | Autoconf macros only, no library; required by nearly every other autotools xorg port. |
| protocol/glue | xorgproto | 2025.1 | https://xorg.freedesktop.org/releases/individual/proto/xorgproto-2025.1.tar.xz | compute-on-fetch | meson (also has autotools) | — | util-macros | Header-only. XLibre ebuild pins `>=x11-base/xorg-proto-2024.1`; 2025.1 satisfies that. |
| protocol/glue | xtrans | 1.6.0 | https://xorg.freedesktop.org/releases/individual/lib/xtrans-1.6.0.tar.xz | compute-on-fetch | autotools | — | util-macros | Header-only transport library. |
| protocol/glue | xcb-proto | 1.17.0 | https://xorg.freedesktop.org/releases/individual/xcb/xcb-proto-1.17.0.tar.xz | compute-on-fetch | autotools/meson | python3 (xcbgen) | — | Needs Python3 at build time for the XML->C codegen. |
| client libs | libpthread-stubs | 0.5 | https://xorg.freedesktop.org/releases/individual/lib/libpthread-stubs-0.5.tar.xz | compute-on-fetch | meson | — | — | Trivial stub lib for platforms without native pthread symbols; verify if actually needed on illumos (native libpthread present) — may be a no-op/skip candidate. |
| client libs | libXau | 1.0.12 | https://xorg.freedesktop.org/releases/individual/lib/libXau-1.0.12.tar.xz | compute-on-fetch | autotools/meson | — | xorgproto, util-macros | |
| client libs | libXdmcp | 1.1.5 | https://xorg.freedesktop.org/releases/individual/lib/libXdmcp-1.1.5.tar.xz | compute-on-fetch | autotools/meson | — | xorgproto, util-macros | |
| client libs | libxcb | 1.17.0 | https://xorg.freedesktop.org/releases/individual/xcb/libxcb-1.17.0.tar.xz | compute-on-fetch | autotools | libXau, libXdmcp | xcb-proto, python3 | |
| client libs | libX11 | 1.8.13 | https://xorg.freedesktop.org/releases/individual/lib/libX11-1.8.13.tar.xz | compute-on-fetch | autotools/meson | libxcb, libXau, libXdmcp | xtrans, xorgproto, xcb-proto, util-macros | |
| client libs | libXext | 1.3.7 | https://xorg.freedesktop.org/releases/individual/lib/libXext-1.3.7.tar.xz | compute-on-fetch | autotools/meson | libX11 | xorgproto, xtrans, util-macros | |
| client libs | libXrender | 0.9.12 | https://xorg.freedesktop.org/releases/individual/lib/libXrender-0.9.12.tar.xz | compute-on-fetch | autotools/meson | libX11 | xorgproto, util-macros | |
| client libs | libXfixes | 6.0.2 | https://xorg.freedesktop.org/releases/individual/lib/libXfixes-6.0.2.tar.xz | compute-on-fetch | autotools/meson | libX11 | xorgproto, util-macros | |
| client libs | libXdamage | 1.1.7 | https://xorg.freedesktop.org/releases/individual/lib/libXdamage-1.1.7.tar.xz | compute-on-fetch | autotools/meson | libX11, libXfixes | xorgproto, util-macros | |
| client libs | libXrandr | 1.5.5 | https://xorg.freedesktop.org/releases/individual/lib/libXrandr-1.5.5.tar.xz | compute-on-fetch | autotools/meson | libX11, libXext, libXrender | xorgproto, util-macros | Not needed by Xvfb itself (no real RandR outputs) but Openbox/toolkits probe it; keep for desktop layer. |
| client libs | libXi | 1.8.3 | https://xorg.freedesktop.org/releases/individual/lib/libXi-1.8.3.tar.xz | compute-on-fetch | autotools/meson | libX11, libXext, libXfixes | xorgproto, util-macros | |
| client libs | libXtst | 1.2.5 | https://xorg.freedesktop.org/releases/individual/lib/libXtst-1.2.5.tar.xz | compute-on-fetch | autotools/meson | libX11, libXext, libXi | xorgproto, util-macros | x11vnc uses XTest to inject input. |
| client libs | libXcursor | 1.2.3 | https://xorg.freedesktop.org/releases/individual/lib/libXcursor-1.2.3.tar.xz | compute-on-fetch | autotools/meson | libX11, libXrender, libXfixes | xorgproto, util-macros | Openbox dep. |
| client libs | libXinerama | 1.1.6 | https://xorg.freedesktop.org/releases/individual/lib/libXinerama-1.1.6.tar.xz | compute-on-fetch | autotools/meson | libX11, libXext | xorgproto, util-macros | |
| client libs | libXcomposite | 0.4.7 | https://xorg.freedesktop.org/releases/individual/lib/libXcomposite-0.4.7.tar.xz | compute-on-fetch | autotools/meson | libX11, libXfixes | xorgproto, util-macros | |
| client libs | libICE | 1.1.2 | https://xorg.freedesktop.org/releases/individual/lib/libICE-1.1.2.tar.xz | compute-on-fetch | autotools/meson | — | xorgproto, util-macros | |
| client libs | libSM | 1.2.6 | https://xorg.freedesktop.org/releases/individual/lib/libSM-1.2.6.tar.xz | compute-on-fetch | autotools/meson | libICE | xorgproto, util-macros | |
| client libs | libXt | 1.3.1 | https://xorg.freedesktop.org/releases/individual/lib/libXt-1.3.1.tar.xz | compute-on-fetch | autotools/meson | libX11, libSM, libICE | xorgproto, util-macros | |
| client libs | libXmu | 1.3.1 | https://xorg.freedesktop.org/releases/individual/lib/libXmu-1.3.1.tar.xz | compute-on-fetch | autotools/meson | libXt, libX11, libXext | xorgproto, util-macros | Needed by st (suckless terminal) and some Openbox tools. |
| client libs | libXpm | 3.5.19 | https://xorg.freedesktop.org/releases/individual/lib/libXpm-3.5.19.tar.xz | compute-on-fetch | autotools/meson | libX11, libXt, libXext | xorgproto, util-macros | Openbox theme/icon support. |
| client libs | pixman | 0.46.4 | https://www.cairographics.org/releases/pixman-0.46.4.tar.gz | compute-on-fetch | meson | — | — | Also mirrored at xorg.freedesktop.org/archive/individual/lib; cairo and the Xvfb software rasterizer both need it. |
| client libs | libxkbfile | 1.2.0 | https://xorg.freedesktop.org/releases/individual/lib/libxkbfile-1.2.0.tar.xz | compute-on-fetch | autotools/meson | libX11 | xorgproto, util-macros | Direct xlibre-server CDEPEND (`>=x11-libs/libxkbfile-1.0.4`). |
| client libs | libxcvt | 0.1.3 | https://xorg.freedesktop.org/releases/individual/lib/libxcvt-0.1.3.tar.xz | compute-on-fetch | meson | — | — | Only pulled in by xlibre-server ebuild when `xorg` USE is enabled (CVT mode-line gen for real Xorg). **Not required for Xvfb-only build** — include only if Task 7 later adds Xorg/DDX support. |
| render/font | libpng | 1.6.58 | https://downloads.sourceforge.net/project/libpng/libpng16/1.6.58/libpng-1.6.58.tar.xz | compute-on-fetch | autotools/cmake | zlib | — | zlib is PRESENT (base) — do not port. |
| render/font | libjpeg-turbo | 3.2.0 | https://github.com/libjpeg-turbo/libjpeg-turbo/archive/refs/tags/3.2.0.tar.gz | compute-on-fetch | cmake | — | nasm (SIMD, optional) | Cairo image-surface/PNG loaders and some toolkits want it; verify actually needed for Xvfb+Openbox minimal set before porting (may be pulled in only transitively via cairo/gdk-pixbuf, which are out of scope here). |
| render/font | brotli | 1.2.0 | https://github.com/google/brotli/archive/refs/tags/v1.2.0.tar.gz | compute-on-fetch | cmake | — | — | freetype2/HarfBuzz woff2 support dependency (brotli-dec/brotli-enc). |
| render/font | freetype | 2.14.3 | https://download.savannah.gnu.org/releases/freetype/freetype-2.14.3.tar.xz | compute-on-fetch | autotools/meson | libpng, brotli | — | Also needs harfbuzz for full autohint-improve mode, but freetype/harfbuzz have a circular dep — build freetype WITHOUT harfbuzz first, then harfbuzz, then optionally rebuild freetype WITH harfbuzz (standard bootstrap sequence upstream documents). |
| render/font | fontconfig | 2.16.0 | https://www.freedesktop.org/software/fontconfig/release/fontconfig-2.16.0.tar.xz | 6a33dc555cc9ba8b10caf7695878ef134eeb36d0af366041f639b1da9b6ed220 | meson/autotools | freetype, libxml2, gperf(build) | pkgconf, gperf | libxml2: PRESENT (base) — **verify on alpha9; port only if absent** per brief. |
| render/font | libfontenc | 1.1.9 | https://xorg.freedesktop.org/releases/individual/lib/libfontenc-1.1.9.tar.xz | compute-on-fetch | autotools/meson | zlib | xorgproto, util-macros | zlib PRESENT (base). |
| render/font | libXfont2 | 2.0.8 | https://xorg.freedesktop.org/releases/individual/lib/libXfont2-2.0.8.tar.xz | compute-on-fetch | autotools/meson | freetype, libfontenc, xtrans, fontconfig | xorgproto, util-macros | Direct xlibre-server CDEPEND (`>=x11-libs/libXfont2-2.0.1`). |
| render/font | libXft | 2.3.9 | https://xorg.freedesktop.org/releases/individual/lib/libXft-2.3.9.tar.xz | compute-on-fetch | autotools/meson | libX11, libXrender, freetype, fontconfig | xorgproto, util-macros | Openbox/toolkit font rendering. |
| render/font | font-util | 1.4.2 | https://xorg.freedesktop.org/releases/individual/font/font-util-1.4.2.tar.xz | compute-on-fetch | autotools/meson | — | util-macros | Direct xlibre-server DEPEND (`media-fonts/font-util`). |
| render/font | dejavu-fonts | 2.37 | https://downloads.sourceforge.net/project/dejavu/dejavu/2.37/dejavu-fonts-ttf-2.37.zip | compute-on-fetch | make (fontforge-based build; or use pre-built ttf archive directly, no compile needed) | fontconfig (runtime) | — | Brief offers dejavu-fonts OR liberation-fonts; recommend dejavu — no compile step needed if using the pre-built `-ttf-` distribution (just install + fc-cache), simplest for a first desktop bring-up. |
| render/font | pcre2 | 10.47 | https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.47/pcre2-10.47.tar.bz2 | compute-on-fetch | autotools/cmake | — | — | glib2 build dependency. |
| render/font | glib2 | 2.89.2 | https://download.gnome.org/sources/glib/2.89/glib-2.89.2.tar.xz | 894fd527e305041f7723071297d79a78af4719dbd0d8fb77f6b1a85c9f5475b9 | meson | pcre2, libffi | python3 (meson), gettext | 2.89.x is GNOME's current stable-numbering release per `gitlab.gnome.org` tags (post-even/odd-minor convention change); libffi is PRESENT (base) — do not re-port. Verify glib2 not already in zports (Python/Mercurial zports work may have pulled it transitively). |
| render/font | fribidi | 1.0.16 | https://github.com/fribidi/fribidi/releases/download/v1.0.16/fribidi-1.0.16.tar.xz | compute-on-fetch | meson | — | — | pango dependency (bidi text). |
| render/font | harfbuzz | 14.2.1 | https://github.com/harfbuzz/harfbuzz/releases/download/14.2.1/harfbuzz-14.2.1.tar.xz | compute-on-fetch | meson | freetype, glib2 | gettext | Circular with freetype — see freetype note above for build order. Version confirmed via GitHub Releases API `tag_name`; note the harfbuzz repo's own git tag list is polluted with unrelated `pango-*`/`hb-*` marker tags so trust the Releases API, not `git tag -l`. |
| render/font | cairo | 1.18.4 | https://www.cairographics.org/releases/cairo-1.18.4.tar.xz | compute-on-fetch | meson/autotools | pixman, libpng, freetype, fontconfig, libX11, libXext, libXrender | — | |
| render/font | pango | 1.58.0 | https://download.gnome.org/sources/pango/1.58/pango-1.58.0.tar.xz | bc5bad6213ad4886a47d1e80292fd850b64159b50db67917a43d9ea80ee2298a | meson | glib2, cairo, harfbuzz, fribidi, fontconfig, freetype | gettext | glib.gnome.org `cache.json` briefly listed a `1.90.0` entry that does NOT correspond to any real git tag (checked GNOME GitLab tag list directly — highest real tag is 1.58.0); treat the cache.json max-version heuristic as unreliable for pango and always cross-check against GitLab tags. |
| server+runtime | xlibre-xserver | 25.1.8 | https://github.com/X11Libre/xserver/archive/refs/tags/25.1.8.tar.gz | compute-on-fetch | meson | libxcb, libX11, libXau, libXdmcp, libXfont2, libxkbfile, pixman, xkeyboard-config, openssl(sha1=libcrypto) | xorgproto (>=2024.1), font-util, xtrans, flex/lex (BDEPEND `app-alternatives/lex`) | **Xvfb-only build**: see meson flags section above. openssl, ncurses PRESENT (base). Gentoo ebuild pins `SLOT=0/${PV}`, latest stable tag `25.1.8` (also `25.1.7`, and legacy `25.0.0.23`/`.24`); `9999` is the live/git ebuild — do not use. |
| server+runtime | xkbcomp | 1.5.0 | https://xorg.freedesktop.org/releases/individual/app/xkbcomp-1.5.0.tar.xz | compute-on-fetch | autotools/meson | libX11, libxkbfile | xorgproto, util-macros | Direct xlibre-server CDEPEND (`x11-apps/xkbcomp`, unconditional). |
| server+runtime | xkeyboard-config | 2.48 | https://xorg.freedesktop.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.48.tar.xz | compute-on-fetch | meson/autotools | — | util-macros, gettext, python3 (some intltool-style steps) | Direct xlibre-server CDEPEND (`>=x11-misc/xkeyboard-config-2.4.1-r3`). Not under xorg.freedesktop.org/releases/individual/{lib,app}; lives under `/data/xkeyboard-config/`. |
| server+runtime | xauth | 1.1.5 | https://xorg.freedesktop.org/releases/individual/app/xauth-1.1.5.tar.xz | compute-on-fetch | autotools/meson | libX11, libXau, libXext, libXmu | xorgproto, util-macros | Direct xlibre-server CDEPEND (`>=x11-apps/xauth-1.0.3`). |
| server+runtime | xinit | 1.4.4 | https://xorg.freedesktop.org/releases/individual/app/xinit-1.4.4.tar.xz | compute-on-fetch | autotools/meson | libX11 | xorgproto, util-macros | Only an xlibre-server RDEPEND when USE=xorg; for Xvfb-only we still want it as the standard "start X + run client" launcher wrapper for Task 7/8 smoke tests. |
| server+runtime | x11vnc | 0.9.17 | https://github.com/LibVNC/x11vnc/releases/download/0.9.17/x11vnc-0.9.17.tar.gz | compute-on-fetch | autotools | libX11, libXext, libXtst, libXrandr, libXdamage, libXfixes, libXinerama, zlib, libjpeg-turbo | pkgconf | zlib PRESENT (base). This is the actual remote-display path for an Xvfb-based headless desktop (brief's "Xvfb->VNC first" plan per graphics-baseline memory). |
| desktop | openbox | 3.6.1 | http://openbox.org/dist/openbox/openbox-3.6.1.tar.gz | compute-on-fetch | autotools | libX11, libXext, libSM, libICE, libXrandr, libXcursor, libXinerama, libxml2, pango, glib2 | pkgconf, util-macros | Upstream project is effectively unmaintained since ~2016; 3.6.1 is the last real release — confirmed the tarball is live at `openbox.org/dist` (HTTP 200, GitHub-Pages-fronted). libxml2: verify on alpha9 per brief; port only if absent from base. |
| desktop | st | 0.9.3 | https://dl.suckless.org/st/st-0.9.3.tar.gz | compute-on-fetch | make | libX11, libXft, fontconfig, freetype | — | suckless has no configure step; Makefile hardcodes `/usr/local` prefix and X11 include/lib paths — expect a Makefile-config patch for Hammerhead's simplified `/usr/lib` paths (per project's Goal #2). |

## PRESENT — do not re-port (per brief)

| name | status | notes |
|---|---|---|
| zlib | PRESENT (base) | consumed by libpng, libfontenc, x11vnc |
| libffi | PRESENT (base) | consumed by glib2 |
| expat | PRESENT (base) | not directly required by this port set, but commonly linked by fontconfig-adjacent tooling; no action needed |
| openssl | PRESENT (base) | OpenSSL 3.5 per memory; xlibre-server's `-Dsha1=libcrypto` uses it directly |
| ncurses | PRESENT (base) | not a direct dep of this port set but listed per brief; no action needed |
| libxml2 | verify on alpha9; port only if absent | consumed by fontconfig and openbox in this table — if it turns out absent, add it as a port (last known upstream 2.13.x, gitlab.gnome.org/GNOME/libxml2) before Task on fontconfig/openbox proceeds |

## Ports whose version/deps could NOT be fully pinned from primary sources

- **libpthread-stubs** — version 0.5 confirmed present on xorg.freedesktop.org, but whether illumos/Hammerhead (which has a native, non-stub pthread implementation) needs this at all is unresolved from packaging alone; flag for the per-port task to check whether libxcb's meson build even requests it on a non-Linux, non-BSD host.
- **libjpeg-turbo** — included because cairo/gdk-pixbuf-style stacks commonly want it, but nothing in the strict Xvfb+Openbox+st dependency chain in this table hard-requires it (cairo's PNG backend uses libpng directly, not libjpeg). Kept in the table per the brief's explicit port list; the per-port task should confirm it's actually linked by something before spending build effort on it.
- **xorgproto exact API-numbered subset** — recorded only the tarball version (2025.1); did not enumerate which of the ~20 sub-protocol headers (`bigreqsproto`, `xproto`, `randrproto`, etc.) are consumed by which client lib — that level of granularity is a Task 2/3 build-time concern, not a manifest concern.
- **dejavu-fonts build system** — the upstream distribution is a pre-built TTF zip (no compile), which doesn't map cleanly onto the `build_system` column enum (`autotools|meson|cmake|make|python`); recorded as `make (fontforge-based build; or use pre-built ttf archive directly, no compile needed)` — flag for whoever writes the Coral `package.toml` since it may just be a copy-files package with no real build step.

## Notable surprises

1. **XLibre's ebuild dependency chain is more informative than freedesktop.org alone** — the Gentoo ebuild's `CDEPEND`/`DEPEND` block is the only place that states the *exact* minimum-version constraints XLibre's own server actually enforces (e.g. `>=x11-libs/libxkbfile-1.0.4`, `>=x11-base/xorg-proto-2024.1`, `>=x11-apps/xauth-1.0.3`) — freedesktop.org release pages don't carry that information at all.
2. **`meson_use` 1:1-maps Gentoo USE flags to meson option names** — this made verifying the exact Xvfb-only flag set far more reliable than guessing from `meson_options.txt` alone: the ebuild's `src_configure()` is effectively a working, tested reference invocation, just with `xorg`/`xephyr`/etc. flipped the other way for Xvfb-only.
3. **GNOME's `cache.json` release-index endpoints are not reliable for "latest stable"** — pango's `cache.json` listed a `1.90.0` version with no matching git tag anywhere in GNOME's GitLab; always cross-check via the GitLab tags API (`gitlab.gnome.org/api/v4/projects/GNOME%2F<pkg>/repository/tags`) before trusting a cache.json max.
4. **harfbuzz's own git tag list is polluted with non-release marker tags** (`pango-start`, `hb-rename`, etc. — likely leftover from a historical monorepo merge) — the GitHub Releases API `tag_name` field is the trustworthy source, not a raw `git tag` scrape.
5. **`libxcvt` is NOT required for an Xvfb-only build** — it's gated behind XLibre's `xorg` USE flag (real Xorg mode-line generation) and never touched when `xvfb`-only is enabled. Listed in the brief's client-libs set, but Task 2/3 can deprioritize it unless/until Phase 1b adds real Xorg/DDX support.
6. **`xkeyboard-config` and `dejavu-fonts` are NOT under the same freedesktop.org path prefix** as the other xorg libs/apps — xkeyboard-config lives at `.../releases/individual/data/xkeyboard-config/`, and dejavu-fonts is SourceForge-hosted, not freedesktop.org at all. Both 404'd on first-guess URLs before the correct path was found by search, consistent with the brief's warning not to guess.

## Added mid-implementation (not in the original mining)
| category | name | version | build_system | why | task |
|---|---|---|---|---|---|
| devel | gettext-not-needed | — | — | glib `-Dnls=disabled`; no gettext dep hit | Task 5/6 |
| devel | gperf | 3.3 | autotools | fontconfig build tool | Task 5 |
| devel | unzip | 6.0 | make | coral shells out to unzip for .zip sources | Task 5 |
| base | libvncserver | 0.9.15 | autotools | x11vnc hard dep since its 2016 codebase split (not in upstream x11vnc tarball) | Task 7a |