Hammerhead

Hammerhead is the modernized base system for the Zygaena operating system — a
64-bit-only illumos derivative built with a modern GNU toolchain, a simplified
filesystem layout, and a lightweight init system in place of SMF.

It began as a fork of illumos-gate and
has since diverged substantially:

• SPARC and 32-bit support removed; ~66 legacy drivers deleted
• the dmake / Sun-cc / illumos-ld build chain replaced with GNU Make + GCC 14 + GNU ld
• IPS replaced by the Coral package manager
• SMF replaced by zyginit as PID 1
• Mozilla NSS/NSPR and the NIS+ name service removed; PAM stack simplified
• the whole system made self-hosting — Hammerhead builds Hammerhead, with no
  OpenIndiana cross-build host required

What Hammerhead is (and isn't)

Hammerhead is the base system of Zygaena: the kernel, core libraries, base
commands, and the toolchain needed to rebuild them — everything produced by
hh-build into a self-contained proto area. The wider software catalog (git,
Python, bash upgrades, and so on) lives above the base system and is delivered
by the Coral package manager under /usr/local.

Goals

• 64-bit only — no 32-bit binary or library builds
• Simplified paths — libraries in /usr/lib (not /usr/lib/amd64)
• Modern toolchain — GCC 14 + GNU ld + GNU Make (replacing dmake + illumos ld)
• Self-host — Hammerhead can build itself; no OpenIndiana cross-build host required
• Reduced scope — legacy drivers and architectures removed (SPARC, obsolete hardware)
• Replaced SMF — zyginit is PID 1; no svc.startd / svccfg / svcadm

Non-Goals

• Compatibility with upstream illumos
• Support for legacy hardware/architectures
• Contribution back to the illumos project

Naming

• Hammerhead — the illumos-gate fork / base system (the common name for Zygaena sharks)
• Zygaena — the parent operating-system project (the genus name for hammerhead sharks)

Repository Structure

hammerhead/
├── README.md                 # This file
├── BUILDING.md               # Build prerequisites and instructions
├── CLAUDE.md                 # AI assistant project memory (rules, workflow, key docs)
├── docs/
│   ├── README.md             # Documentation index
│   ├── ROADMAP.md            # Done / in-flight / slate
│   ├── design/               # Per-initiative design docs (BUILDING.md, MODIFICATIONS.md, …)
│   ├── roadmap/              # Per-initiative roadmap docs (ONBLD_PHASE_OUT.md, …)
│   └── archived/             # Reference / historical (DRIVER_REMOVAL.md, GIT_HISTORY.*, …)
├── base/                     # illumos-gate source tree (renamed from hammerhead/)
│   └── usr/src/
│       ├── Makefile.master   # Master build config
│       ├── lib/              # Libraries
│       ├── cmd/              # Commands
│       ├── uts/              # Kernel
│       ├── tools/            # Build tools (hh-build, build-gcc.sh, build-tools.sh)
│       └── zyginit/services/ # Hammerhead-owned service definitions
├── rootfs/                   # Files overlaid onto every deploy (/etc/pam.conf, etc.)
├── tools/                    # Top-level tooling
│   ├── hh-deploy             # Deploy proto to a disk or running VM
│   ├── bootstrap-hh.sh       # OCaml → reefc → coral + autotools/curl chain
│   ├── bootstrap.sh          # Legacy OI cross-build bootstrap (rarely used now)
│   ├── update-zyginit        # Vendored zyginit version bump
│   └── bootstrap/            # Source tarballs + patches for bootstrap-hh
└── archive/                  # Archived materials

Version Control

Hammerhead is hosted on Isurus, the Zygaena project's Mercurial forge.

hg clone ssh://hg@leafscale.isurus.dev:2222/zygaena/hammerhead

Note: the project migrated from git to Mercurial (fresh-snapshot cutover). The
complete pre-migration git commit history is preserved for reference in
docs/archived/GIT_HISTORY.md (and .csv). The
conversion silently dropped some ignored-but-tracked source; that class has been
swept and a truly-fresh hg clone now builds, boots, and reaches console login
(see the migration-completion entry in docs/ROADMAP.md).

Development Workflow

Self-hosted: the build VM is itself a Hammerhead system (e.g. hh-alpha7). Code is
edited on Linux, pushed via Mercurial, pulled on the build VM, and built there.

Linux dev host             Isurus                  Hammerhead build VM
                       (Mercurial forge)            (hh-alpha7, KVM)
~/repos/.../hammerhead  --> hg push  -->  /usr/src/hammerhead
   [edit]                                            [hg pull -u]
                                                     [hh-build]
                                                     [hh-deploy create/update/deploy]
                                                            |
                                                            v
                                                    Target alpha (hh-alpha8, …)

The OpenIndiana cross-build VM (hammerhead-build) is legacy — kept around only
for emergency bootstrap recovery. Don't power it on or build on it without an explicit
reason; alpha7 is the active build host.

See CLAUDE.md for the full host inventory, IPs, and per-step commands.

Building

Hammerhead must be built on a Hammerhead-based system (or, in extreme recovery
scenarios, OpenIndiana via the legacy bootstrap.sh path).

# On the build VM (alpha7)
cd /usr/src/hammerhead/base
./usr/src/tools/scripts/hh-build usr/src/tools/env/hammerhead.sh

# Build log
tail -f log/build.log

# Tagged log dir after completion
ls -la log/latest    # symlink → log/log.<short-hash>.<date>.<time>/
cat log/latest/build-info

A clean build from a wiped /usr/src/hammerhead plus fresh clone plus repopulated
tools/bootstrap/sources/ takes ~2h14m on alpha7 (validated 2026-06-03, build_ok=y).

Deploying

After hh-build finishes, the proto area at /usr/src/hammerhead-build/root_amd64
is self-contained. Deployment is currently manually done until the installer is ready:

# Fresh install on a wiped disk — creates ZFS pool + UEFI ESP + boots
sudo tools/hh-deploy create --disk /dev/dsk/c2t0d0 --pool hhpool

# Refresh an existing pool on a locally-attached disk
sudo tools/hh-deploy update --pool hhpool

# deploy --target is unsupported (live proto extract)

Hammerhead is UEFI-only: Limine 12 on OVMF + pc-i440fx-8.2 loads
unix from the FAT ESP (protocol: limine). q35 panics at vfs_mountroot.

Documentation

License

This project inherits licensing from illumos-gate. Most code is licensed under the
CDDL.

Related Projects

• illumos — upstream source
• n-hys/illumos-gate — reference for GNU toolchain changes (aarch64/riscv64 ports)
• Tribblix — reference for IPS elimination approach