SwiftOS Package Guide

This guide explains the package workflows that work in the current checked-in SwiftOS tree. It is the practical companion to the package design documents: use it when you want to build the sample package, inspect artifacts, boot package content, and collect support evidence.

SwiftOS packages follow the system's immutable-image model. A package is built on the host, verified on the host, and exposed to the guest as read-only package content under /usr. The current target-side package manager supports local file install, pkg install FILE, into a writable package-store disk, pkg list, pkg info NAME, pkg files NAME for active package inspection, and pkg remove NAME as a next-boot package deactivation, plus a signed static HTTP repository fixture with pkg repo set, pkg update [URL], and pkg install NAME. Repository installs resolve dependencies by package name. Public production channels, version-constraint solving, live unmount, upgrade, and rollback are staged work, not current behavior. The ports workflow can cross-build static AArch64 Lua, zlib, bzip2, zstd, xz, libarchive, OpenSSL, pcre2, curl, nginx, and sqlite packages on the host, package the pinned CA certificate bundle and IANA time zone data, publish them into signed local repository fixtures, install Lua by package name in QEMU, and boot SwiftOS with a default repository URL to install Lua, zlib, bzip2, zstd, xz, libarchive, ca-certificates, OpenSSL, pcre2, curl, tzdata, nginx, and sqlite from one seed repository. It can also produce a static-hostable web root for that seed repository, verify a hosted URL from the host, and prove that SwiftOS installs from a DNS-resolved HTTP repository URL.

Use this guide with:

• Package Management for the long-term package manager design and roadmap.
• Package Build Automation Guide for package recipe, CI smoke-test, and repository publishing plans.
• SWPKG Format for the .swpkg container format.
• Package Store Format for the package-store image.
• Static Package Repository for the signed HTTP repository layout.
• Server Software Catalog for prioritized server packages and porting prerequisites.
• Operations Guide for QEMU boot profiles.
• Application Cookbook for package authoring context.
• Troubleshooting for package failure diagnosis.

Current Package State

The current real port fixtures are Lua, zlib, bzip2, zstd, xz, libarchive, ca-certificates, OpenSSL, pcre2, curl, tzdata, nginx, and sqlite. They are useful for package maintainers and release owners because they prove source fetch, checksum verification, static cross-build or data-only staging, .swpkg creation, signed local repository publication, target-side Lua install from a signed repository, and target-side seed package install from a default repository URL. They are still local fixtures, not public hosted channels.

Mental Model

SwiftOS does not install packages by unpacking files into a mutable root filesystem. The current model is:

read-only base image
  + active read-only package payloads
  + RAM tmpfs scratch
  = guest VFS namespace

The three package artifact types have different jobs:

Use the direct payload overlay when you want the simplest package-content boot. Use the package-store image when you want to test the current activation-record path. Use the local install path when you want to prove the guest can append a local .swpkg payload to a writable package-store disk and live-mount it. Use the ports seed repository path when you want to prove the first multi-package hosted-style workflow.

Choose A Package Workflow

Pick the narrowest workflow that proves the behavior you care about:

Do not use these fixtures to claim public production channels, live package unmount, upgrade, rollback, target-side HTTPS transport, or version-constraint solving. Those remain package-roadmap items.

Quick Start

Build the kernel, base image, DTB, host package tools, and sample package:

make build base-image build/virt.dtb
make package-fixture

Inspect and verify the .swpkg artifact:

build/swpkg inspect build/pkghello.swpkg
build/swpkg verify build/pkghello.swpkg

Inspect the package-store image:

make package-store-fixture
build/pkgstore inspect build/pkgstore-pkghello.img

Inspect the signed repository fixture:

make package-repo-fixture
build/pkgrepo inspect build/pkgrepo-root/aarch64/current/catalog.signed

Build and inspect the Lua port repository fixture:

make ports-lua-repo-fixture
build/swpkg inspect build/lua.swpkg
build/pkgrepo inspect build/lua-repo-root/aarch64/current/catalog.signed

Build the deployable static-host repository root:

make ports-static-host-publish
shasum -a 256 -c build/ports-static-host-root/SHA256SUMS
build/pkgrepo inspect build/ports-static-host-root/aarch64/current/catalog.signed

Verify a hosted copy and prove DNS-resolved repository install locally:

make ports-hosted-url-verify PKG_HOSTED_REPO_URL=http://repo-host.example
make ports-hosted-url-verify-test
make package-static-host-dns-repo-install-test

Run the acceptance tests:

make package-overlay-test
make package-store-test
make package-local-install-test
make package-repo-install-test
make ports-catalog-test
make ports-recipe-test

Host Tools

build/swpkg

build/swpkg is the host-side package container tool.

make swpkg

build/swpkg create --manifest fixtures/pkghello/manifest.json --root build/pkghello-root --output build/pkghello.swpkg
build/swpkg inspect build/pkghello.swpkg
build/swpkg verify build/pkghello.swpkg
build/swpkg extract-payload build/pkghello.swpkg build/pkghello-payload.img

The package fixture target runs the correct sequence for the sample package. Most users should start with:

make package-fixture

build/pkgstore

build/pkgstore is the host-side package-store image tool.

make pkgstore

build/pkgstore create --package build/pkghello.swpkg --output build/pkgstore-pkghello.img --generation 1
build/pkgstore inspect build/pkgstore-pkghello.img

The package-store fixture target builds and inspects the sample store:

make package-store-fixture

Build an empty writable store for local guest installs:

make package-local-install-fixture

build/pkgrepo

build/pkgrepo is the host-side signed static repository tool.

make pkgrepo

SEED=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
build/pkgrepo pubkey --seed-hex "$SEED" --output build/pkgrepo-root.pub
build/pkgrepo create \
  --package build/pkghello.swpkg \
  --output build/pkgrepo-root \
  --seed-hex "$SEED" \
  --generation 1
build/pkgrepo verify --catalog-signed build/pkgrepo-root/aarch64/current/catalog.signed --pubkey build/pkgrepo-root.pub
build/pkgrepo inspect build/pkgrepo-root/aarch64/current/catalog.signed

Most users should start with:

make package-repo-fixture

Boot A Direct Package Payload

This is the direct read-only package payload path. Build the fixture:

make build base-image build/virt.dtb
make package-fixture

Boot QEMU with the base image plus the package payload image:

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic -no-reboot \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -drive file=build/pkghello-payload.img,format=raw,if=none,id=swospkg0,readonly=on \
  -device virtio-blk-device,drive=swospkg0 \
  -kernel build/kernel.elf

Log in as root and run:

/usr/bin/pkghello

Expected output:

pkghello: hello from package overlay

Proof:

make package-overlay-test

Boot A Package Store

This is the package-store activation path. Build the fixture:

make build base-image build/virt.dtb
make package-store-fixture

Boot QEMU with the base image plus the package-store image:

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic -no-reboot \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -drive file=build/pkgstore-pkghello.img,format=raw,if=none,id=swpkgstore \
  -device virtio-blk-device,drive=swpkgstore \
  -kernel build/kernel.elf

The serial log should include package-store activation markers:

P3: package store active generation
P3: package store payload mounted

Log in as root and run:

/usr/bin/pkghello

Expected output:

pkghello: hello from package overlay

The program text still says "package overlay" because the final VFS result is the same: a read-only package payload mounted under /usr.

Proof:

make package-store-test

Install A Local Package In The Guest

This is the current local package install path. It does not fetch from a repository and it does not resolve dependencies. It verifies a local .swpkg, appends its payload to a writable package-store disk, activates a new generation, and live-mounts the payload under /usr.

Build the package fixture, base image, and writable package-store image:

make build base-image build/virt.dtb
make package-fixture
make package-local-install-fixture

Boot QEMU with the base image plus the writable store image:

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic -no-reboot \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -drive file=build/pkgstore-install.img,format=raw,if=none,id=swpkgstore \
  -device virtio-blk-device,drive=swpkgstore \
  -kernel build/kernel.elf

Log in as root, then run:

pkg list
pkg install /packages/pkghello.swpkg
pkg list
pkg info pkghello
pkg files pkghello
/usr/bin/pkghello

Expected output includes:

no packages installed
pkg: installed pkghello-1.0.0_1
pkghello-1.0.0_1
source: installed
/usr/bin/pkghello
pkghello: hello from package overlay

The .swpkg file is staged in the read-only base image under /packages for the fixture. Repository install tests use the signed HTTP fixture described in the next section.

Proof:

make package-local-install-test

Install From A Signed HTTP Repository Fixture

This is the current signed repository path. It uses an explicit or configured repository URL, verifies catalog.signed with /etc/pkg/repo-root.pub, rejects expired or incompatible catalogs, resolves dependencies by package name, downloads content-addressed .swpkg files, verifies SHA-256, then reuses the local install path to activate the payloads.

Build the repository fixture and writable package-store image:

make build base-image build/virt.dtb
make package-repo-fixture
make package-local-install-fixture

The acceptance test starts a host HTTP server and drives QEMU automatically:

make package-repo-install-test

Inside the guest, the tested flow first rejects negative fixtures:

pkg update http://10.0.2.2:<port>/expired/aarch64/current
pkg update http://10.0.2.2:<port>/wrongarch/aarch64/current

Then it installs from the valid repository:

pkg update http://10.0.2.2:<port>/good/aarch64/current
pkg search pkghello
pkg info pkghello
pkg install pkghello
pkg files pkghello
/usr/bin/pkghello

Expected output includes:

pkg: catalog expired
pkg: catalog incompatible
pkg: catalog updated http://10.0.2.2:<port>/good/aarch64/current
pkghello-1.0.0_1
sha256:
pkg: installed pkghello-1.0.0_1
/usr/bin/pkghello
pkghello: hello from package overlay

The same test later points the guest at a bad-hash repository and expects pkg: package SHA-256 mismatch before the package is allowed to install.

Build The Lua Port Repository Fixture

This is the single-package source-port path. It cross-builds real static AArch64 lua and luac binaries against the local newlib sysroot, packages them into build/lua.swpkg, and publishes a signed local repository fixture under build/lua-repo-root. The QEMU smoke then installs lua from that repository and runs it inside SwiftOS.

If the generated sysroot is missing, build it first:

make newlib

Then build the Lua fixture:

make ports-lua-repo-fixture

Expected host artifacts:

Inspect the result:

build/swpkg verify build/lua.swpkg
build/pkgrepo verify \
  --catalog-signed build/lua-repo-root/aarch64/current/catalog.signed \
  --pubkey build/lua-repo-root.pub
build/pkgrepo inspect build/lua-repo-root/aarch64/current/catalog.signed

Run the target-side Lua repository smoke:

make package-lua-repo-install-test

The guest-side flow exercised by the test is:

pkg repo set http://10.0.2.2:<port>/aarch64/current
pkg update
pkg search lua
pkg info lua
pkg install lua
/usr/bin/lua -v
/usr/bin/lua -e 'print(21 * 2)'

Build The Ports Seed Repository Fixture

The checked Lua, zlib, bzip2, zstd, xz, libarchive, ca-certificates, OpenSSL, pcre2, curl, tzdata, nginx, and sqlite recipes publish into one signed local seed repository. This is the closest current stand-in for the future hosted package channel: the guest boots with a default repository URL, runs pkg update, installs all thirteen packages by name, and exercises the installed payloads.

make ports-lua-repo-fixture
make ports-zlib-repo-fixture
make ports-bzip2-repo-fixture
make ports-zstd-repo-fixture
make ports-xz-repo-fixture
make ports-libarchive-repo-fixture
make ports-ca-certificates-repo-fixture
make ports-openssl-repo-fixture
make ports-pcre2-repo-fixture
make ports-tzdata-repo-fixture
make ports-curl-repo-fixture
make ports-nginx-repo-fixture
make ports-sqlite-repo-fixture
make ports-seed-repo-fixture

Key artifacts:

The seed smoke reuses build/pkgstore-lua-install.img as its 32 MiB writable package-store image.

The guest-side flow exercised by the seed smoke is:

pkg update
pkg install lua
pkg install zlib
pkg install bzip2
pkg install zstd
pkg install xz
pkg install libarchive
pkg install ca-certificates
pkg install openssl
pkg install pcre2
pkg install curl
pkg install tzdata
pkg install nginx
pkg install sqlite
/usr/bin/lua -e 'print(21 * 2)'
echo zlib-ok >/tmp/zlib.txt
/usr/bin/minigzip /tmp/zlib.txt
/usr/bin/minigzip -d /tmp/zlib.txt.gz
cat /tmp/zlib.txt
/usr/bin/bzip2 -V
cat /usr/share/bzip2/swiftos-bzip2.version
echo zstd-ok > /tmp/zstd.in
/usr/bin/zstd -q -f /tmp/zstd.in -o /tmp/zstd.zst
/usr/bin/zstd -q -d -f /tmp/zstd.zst -o /tmp/zstd.out
cat /tmp/zstd.out
cat /usr/share/zstd/swiftos-zstd.version
echo xz-ok | /usr/bin/xz -q -c | /usr/bin/xz -q -d -c
cat /usr/share/xz/swiftos-xz.version
/usr/bin/bsdtar --version
cd /tmp && echo libarchive-ok > libarchive.txt && /usr/bin/bsdtar -cf libarchive.tar libarchive.txt && /usr/bin/bsdtar -tf libarchive.tar
cat /usr/share/libarchive/swiftos-libarchive.version
cat /usr/share/certs/swiftos-ca-bundle.version
/usr/bin/openssl version
echo openssl-ok | /usr/bin/openssl dgst -sha256
cat /usr/share/openssl/swiftos-openssl.version
echo nginx-lighttpd > /tmp/pcre2.txt
/usr/bin/pcre2grep 'nginx|lighttpd' /tmp/pcre2.txt
/usr/bin/curl --version
/usr/bin/curl -fsS http://10.0.2.2:<port>/curl-fixture.txt
cat /usr/share/curl/swiftos-curl.version
cat /usr/share/zoneinfo/swiftos-tzdata.version
cat /usr/share/zoneinfo/zone1970.tab
/usr/sbin/nginx -v
cat /usr/share/nginx/swiftos-nginx.version
/usr/bin/sqlite3 -batch -noheader -cmd '.mode list' :memory: 'select 6*7;'
cat /usr/share/sqlite/swiftos-sqlite.version

Package Fixture Anatomy

The sample fixture is intentionally small so it can run in every acceptance gate.

Package files install under /usr. The current package verifier rejects package payload paths outside /usr.

Creating Your Own Local Package Fixture

For a local experiment, follow the fixture shape:

1. Build a static SwiftOS executable.
2. Stage it under a package root, usually build/<name>-root/usr/bin/<name>.
3. Write a manifest with target: "swift-os" and static linkage metadata.
4. Run build/swpkg create.
5. Run build/swpkg verify.
6. Extract a payload image or create a package-store image.
7. Boot QEMU with the resulting image and run the program from /usr/bin.
8. For repository testing, publish it into a local build/pkgrepo-root fixture and prove pkg repo set URL && pkg update && pkg install NAME in QEMU.

Keep current package experiments simple:

• Install real executable paths such as /usr/bin/tool.
• Do not rely on symlinks, maintainer scripts, or dynamic libraries.
• Keep dependency metadata simple: the current repository resolver handles package names, but does not interpret version constraints yet.
• Do not expect files to persist in /tmp after reboot.
• Treat repository signatures as catalog signatures. .swpkg reserved signature fields are still not package-level publisher signatures.

For reusable application recipes, see APPLICATION_COOKBOOK.md.

Verification Matrix

Run the narrowest proof for the path you changed:

The underlying host tests are:

• tests/swpkg_tool_test.swift
• tests/pkgstore_tool_test.swift
• tests/pkgrepo_tool_test.swift
• tests/swport_catalog_test.swift
• tests/swport_recipe_test.swift

The QEMU tests are:

• tests/package_overlay_test.sh
• tests/pkg_store_boot_test.sh
• tests/pkg_local_install_test.sh
• tests/pkg_repo_install_test.sh
• tests/pkg_lua_repo_install_test.sh
• tests/pkg_ports_seed_repo_install_test.sh
• tests/pkg_static_host_repo_install_test.sh
• tests/pkg_hosted_url_verify_test.sh
• tests/pkg_static_host_dns_repo_install_test.sh

Troubleshooting

For general package diagnosis, see TROUBLESHOOTING.md.

Security And Product Limits

Current limits that matter for package use:

• Package content is read-only in the guest.
• The current target-side write paths are local .swpkg install and signed repository install into a writable package-store disk.
• pkg remove NAME records a next-boot deactivation generation. It does not live-unmount package files from the current VFS namespace yet.
• The Lua/zlib/bzip2/zstd/ca-certificates/pcre2/tzdata/nginx/sqlite port fixtures and static-host publish path prove source/data packaging, signed repository publication, target-side repository install, and guest execution through make package-lua-repo-install-test, make package-ports-seed-repo-install-test, and make package-static-host-repo-install-test.
• .swpkg hashes prove container integrity. Catalog signatures prove the repository metadata used to find and hash package blobs; package SHA-256 checks prove the downloaded blob matches the catalog.
• Public hosted channels, package-level publisher signatures, version-constraint solving, live unmount, upgrade, and rollback commands are future milestones.
• Target-side repository transport is HTTP-only for now. Host-side publishing checks can verify HTTP or HTTPS URLs, but /bin/pkg currently relies on signed catalogs and package hashes for authenticity rather than TLS.
• Packages cannot grant themselves process capabilities. Authority remains a property of the process identity and launch path.
• The base image remains immutable and wins over package content unless future conflict rules explicitly allow replacement.

Do not use current package images as a production software update mechanism. They are the verified bring-up path for the package format, VFS overlay model, package-store activation substrate, and local install plumbing.

Edit this page on GitHub