Coral Package Manager

Coral is the package manager for Zygaena, written in Reef.

Building

Prerequisites

• Reef compiler (reefc) version 0.11.0 or newer. Coral waits for child
  processes with 0.11's sys.process ExitStatus API (process_wait_status),
  which does not exist in 0.10.x.
• Before that, 0.9.3 was the floor: 0.9.2 and 0.9.3 were both
  breaking stdlib releases and Coral 0.6.0 is built against the result: lookups
  and parsers return Option/Result instead of in-band sentinels
  (encoding.toml, core.str.index_of*, sys.process.process_spawn_shell,
  crypto.sha256_file, net.http.http_request_new), core.str.split sizes its
  own result instead of filling a caller buffer, and sys.optparse's accessors
  became plain fields. None of these are source-compatible with 0.9.1.
• On illumos: source the development environment first

Why 0.8.3 is a hard floor. Before 0.8.3, a bounds-checked string index and
core.str.length() were both O(length) (Reef BUG-147), which made core.str.split
and encoding.base64 quadratic in the size of their input. Coral reads file lists
and a base64-encoded file index that run to megabytes, so on an older compiler
coral list takes ~30s and coral owner ~227s over a ~120-package database.

Coral 0.4.6 shipped private linear reimplementations to work around this. 0.4.7
removed them, so building against an older reefc will compile cleanly and then
be unusably slow, with no error to explain why. Note also that 0.8.1 and 0.8.2 were
retired without a public release (0.8.2 carried an FFI regression, BUG-151).

Quick Start

# On illumos - source the environment
source /opt/zygaena-env.sh

# Build coral
cd ~/repos/zygaena/coral
reefc build -l socket -l nsl

# The binary is created at build/coral
./build/coral --help

Build Options

# Basic build (Linux/macOS)
reefc build

# illumos/Solaris (requires socket libraries)
reefc build -l socket -l nsl

# Type-check only (no compilation)
reefc build --check

# Verbose output
reefc build -v

# Keep generated C code for debugging
reefc build --keep-c

Installation

After building, install to your PATH:

# Option 1: Copy to /usr/local/bin (requires root)
sudo cp build/coral /usr/local/bin/

# Option 2: Copy to user bin
mkdir -p ~/bin
cp build/coral ~/bin/
export PATH="$HOME/bin:$PATH"

Usage

coral --help              # Show help
coral build <port>        # Build a package from port
coral install <pkg>       # Install package(s)
coral remove <pkg>        # Remove package(s)
coral upgrade [pkg]       # Upgrade package(s)
coral sysupgrade <be>     # Install OS set into a new BE and rebuild its boot archive (no activate)
coral rebuild-boot-archive --root <dir>  # Rebuild boot_archive + kmdb pair only (no install/ESP/activate)
coral info <pkg>          # Show package info
coral list                # List installed packages
coral files <pkg>         # List files owned by package
coral owner <file>        # Find which package owns a file
coral search <term>       # Search for packages
coral depends <pkg>       # Show dependency tree
coral sync                # Update ports tree
coral outdated            # Show outdated packages
coral db status           # Show database status
coral clean status        # Show build artifact status
coral ports new cat/name  # Scaffold a new port
coral ports cache status  # Show ports index status

The OS set is zygaena-kernel, zygaena-userland, zygaena-baselayout, zyginit, coral, zports, and reef. On the live root, install, upgrade, install ./file.pkg, and remove all refuse a protected package and point you at coral sysupgrade, and there is no flag to override that. A package is protected if it is one of zygaena-kernel, zygaena-userland, zygaena-baselayout, zyginit, or coral, or if its .PKGINFO or installed entry sets live_root_protected = true. The live root is the resolved target root. A --root that is the same directory as / counts as the live root, and any other --root is allowed. See hammerhead docs/design/PACKAGE_INSTALLER.md §7.1.

coral sysupgrade rebuilds <root>/boot/boot_archive after the OS set is installed, before the BE is unmounted:

/boot/solaris/bin/create_ramdisk -R <root> -p amd64 -f cpio

It does not call bootadm update-archive. The archive must be a gzip cpio that contains kernel/genunix; a UFS or zero image is removed and the command fails. It then writes <root>/boot/boot_archive.kmdb and boot_archive.kmdb.hash beside that pair. create_ramdisk has no -k and always names the archive boot_archive, and extract_boot_filelist does not expand globs, so the kmdb pair is hh-deploy's build_boot_archive contract: boot/solaris/filelist.ramdisk plus boot/solaris/filelist.ramdisk.kmdb, objcopy dropping .debug* and .rela.debug*, cpio -o -H odc, SHA-1 of the uncompressed cpio, gzip -9. The command fails unless the kmdb archive lists kernel/misc/kmdbmod and a kernel/kmdb/amd64/ dmod. Limine still loads unix and the archives from the ESP, not from the BE. install_boot_loader copies both pairs; sysupgrade does not mount the ESP or guess a disk path.

If the install prompt is answered no (or there is no terminal and no -y), sysupgrade unmounts the new BE, runs beadm destroy -F on it, and removes its mount point, so a cancel leaves nothing behind, like --dry-run. If the destroy fails it warns with the BE name; the exit status is still the cancel (3). A failed install keeps its BE.

coral rebuild-boot-archive --root <dir> exposes the same archive rebuild without package install, BE create, ESP copy, or activate. First-install paths that already ran coral install --root (for example zyginstall tip 1) can call it before ESP handoff. It refuses the live root (/). Media/live images must ship tip 57+ coral and host /boot/solaris/bin/create_ramdisk.

Project Structure

coral/
├── reef.toml             # Project manifest
├── src/
│   ├── main.reef         # Entry point, CLI dispatch
│   ├── types.reef        # Shared type definitions
│   ├── commands/         # Command implementations
│   │   ├── build.reef
│   │   ├── install.reef
│   │   ├── remove.reef
│   │   └── ...
│   ├── core/             # Core functionality
│   │   ├── port.reef     # Port file parsing
│   │   ├── portindex.reef # Ports index (MsgPack cache)
│   │   ├── package.reef  # Package operations
│   │   ├── database.reef # Package database
│   │   ├── resolver.reef # Dependency resolution
│   │   └── ...
│   └── util/             # Utilities
│       ├── http.reef     # HTTP downloads
│       ├── archive.reef  # Archive handling
│       └── ...
├── test/                 # Tests
├── build/                # Build output (generated)
└── docs/                 # Documentation

Configuration

Coral uses TOML for configuration. See docs/ for details on:

• Port file format (package.toml)
• Repository configuration
• Build scripts (build.reef)

License

Apache License 2.0. Copyright 2026 Leafscale, LLC. See LICENSE and NOTICE.