# Stage 2: Core Ports Implementation Plan

**Document Version:** 1.0
**Created:** January 2026
**Status:** Planning
**Prerequisites:** Stage 1 Complete (Coral package manager validated)

---

## Overview

Stage 2 creates the foundational ports collection for Zygaena. These are real, working packages that can be built and installed using Coral on illumos.

**Goal:** Build a self-hosting development environment where Zygaena can compile itself.

---

## Port Categories

| Category | Purpose | Examples |
|----------|---------|----------|
| **core** | Essential system packages | libc, zlib, ncurses, libressl |
| **base** | Standard Unix utilities | bash, vim, curl, git, tree |
| **devel** | Development tools & libraries | gmake, pkgconf, autoconf, reef |

---

## Implementation Phases

### Phase 1: Zero-Dependency Ports

Start with packages that have no external dependencies and are easy to build on illumos.

| Port | Version | Description | Notes |
|------|---------|-------------|-------|
| `core/zlib` | 1.3.1 | Compression library | Foundation for many packages |
| `base/tree` | 2.1.1 | Directory listing | Simple C, good test |
| `base/less` | 643 | Pager | Simple, useful immediately |
| `base/which` | 2.21 | Command locator | Single file |

### Phase 2: Core Libraries

Libraries needed by most other packages.

| Port | Version | Dependencies | Notes |
|------|---------|--------------|-------|
| `core/ncurses` | 6.4 | none | Terminal handling |
| `core/readline` | 8.2 | ncurses | Line editing for bash/shells |
| `core/libressl` | 3.9.2 | none | TLS/SSL (preferred over openssl) |
| `core/libffi` | 3.4.6 | none | Foreign function interface |
| `core/libedit` | 3.1 | ncurses | BSD line editor alternative |

### Phase 3: Base Utilities

Essential command-line tools.

| Port | Version | Dependencies | Notes |
|------|---------|--------------|-------|
| `base/bash` | 5.2.21 | ncurses, readline | Primary shell |
| `base/vim` | 9.1 | ncurses | Editor |
| `base/curl` | 8.6.0 | libressl, zlib | HTTP client |
| `base/git` | 2.43.0 | curl, zlib, libressl | Version control |
| `base/tmux` | 3.4 | ncurses, libevent | Terminal multiplexer |
| `base/htop` | 3.3.0 | ncurses | Process viewer |

### Phase 4: Development Tools

Tools needed to build software.

| Port | Version | Dependencies | Notes |
|------|---------|--------------|-------|
| `devel/gmake` | 4.4.1 | none | GNU Make |
| `devel/pkgconf` | 2.1.0 | none | Package config tool |
| `devel/autoconf` | 2.72 | none | Configure script generator |
| `devel/automake` | 1.16.5 | autoconf | Makefile generator |
| `devel/libtool` | 2.4.7 | none | Library build tool |
| `devel/cmake` | 3.28.1 | curl, zlib | Build system |

### Phase 5: Reef Language

Package Reef itself so Zygaena can build Coral.

| Port | Version | Dependencies | Notes |
|------|---------|--------------|-------|
| `devel/ocaml` | 5.1.1 | none | OCaml compiler (for building Reef) |
| `devel/opam` | 2.1.5 | ocaml | OCaml package manager |
| `devel/reef` | 0.1.4 | ocaml, opam | Reef language compiler |
| `core/coral` | 1.0.0 | reef | Package manager itself |

---

## Port Structure Template

Each port follows this structure:

```
/usr/ports/<category>/<name>/
├── package.toml      # Package metadata
├── build.sh          # Build script (shell for now, reef later)
├── patches/          # illumos compatibility patches (if needed)
│   └── *.patch
└── files/            # Additional files (configs, services)
```

### Example: core/zlib/package.toml

```toml
[package]
name = "zlib"
version = "1.3.1"
release = 1
description = "General-purpose compression library"
url = "https://zlib.net"
license = "Zlib"
maintainer = "Chris Tusa <chris.tusa@leafscale.com>"
arch = "x86_64"

[dependencies]
runtime = []
build = []

[sources]
urls = ["https://zlib.net/zlib-1.3.1.tar.gz"]
checksums = ["9a93b2b7dfdac77ceba5a558a580e74667dd6fede4585b91eefb60f03b72df23"]

[build]
parallel = true
jobs = 0
```

### Example: core/zlib/build.sh

```bash
#!/bin/bash
# Build script for zlib

set -e

# Environment provided by coral:
# $SRCDIR - extracted source directory
# $PKGDIR - installation destination (DESTDIR)
# $JOBS   - parallel job count

cd "$SRCDIR"

./configure --prefix=/usr

gmake -j$JOBS
gmake install DESTDIR="$PKGDIR"
```

---

## illumos Compatibility Notes

### Common Issues & Fixes

| Issue | Solution |
|-------|----------|
| `make` vs `gmake` | Always use `gmake`, set `MAKE=gmake` |
| `tar` vs `gtar` | Always use `gtar`, set `TAR=gtar` |
| Missing `d_type` in dirent | Apply compatibility patch |
| Different socket API | May need `-lsocket -lnsl` |
| No `/proc/self/exe` | Use `getexecname()` instead |
| Terminal ioctl differences | Patch with illumos-specific code |

### Build Environment Variables

```bash
export PATH="/usr/gnu/bin:$PATH"
export CC=gcc
export CXX=g++
export MAKE=gmake
export TAR=gtar
export CFLAGS="-O2 -pipe -march=x86-64"
export LDFLAGS=""
```

---

## Dependency Graph (Simplified)

```
                    zlib
                     |
    +-------+--------+--------+
    |       |                 |
  curl    git              cmake
    |       |
    +---+---+
        |
     libressl

    ncurses
       |
   +---+---+---+
   |   |   |   |
 bash vim tmux htop
   |
readline
```

---

## Success Criteria

### Minimum Viable Ports (MVP)
- [ ] 5 working ports that build and install
- [ ] Dependency chain works (e.g., ncurses -> vim)
- [ ] Ports work on OmniOS test machine

### Full Stage 2
- [ ] 20+ ports covering core, base, devel categories
- [ ] Reef can be built as a port
- [ ] Coral can be built as a port
- [ ] Self-hosting: can rebuild entire ports tree from itself
- [ ] Binary repository with pre-built packages

---

## Implementation Order

1. **Set up ports tree structure** on illumos
2. **Create zlib port** - simplest, no deps, widely needed
3. **Create tree port** - simple C program, validate workflow
4. **Create ncurses port** - core library
5. **Create vim port** - depends on ncurses, user-facing
6. **Create libressl port** - TLS for curl/git
7. **Create curl port** - depends on libressl
8. **Create git port** - depends on curl
9. **Package Reef and Coral** - self-hosting milestone

---

## Verification Plan

After each port:
1. `coral build <port>` - Verify it builds
2. `coral install <package>` - Verify it installs
3. Test the installed program works
4. `coral remove <package>` - Verify clean removal

---

## Notes

- Start with shell build scripts (build.sh) for simplicity
- Convert to Reef build scripts (build.reef) later if desired
- Focus on getting packages working, not perfection
- Document any illumos-specific patches needed
- Keep patch files in the port for reproducibility
