SWPKG Package Format

.swpkg is the SwiftOS binary package artifact. It is the unit produced by the host package tools, published in signed package repositories, staged into package-store images, and installed by the current target-side pkg install paths.

The current container format is SWPKG001 version 1. It is deterministic, uncompressed, statically linked by convention, and intentionally small enough for the target-side parser. A .swpkg proves container integrity through SHA-256 hashes; publisher identity is supplied by the signed repository catalog when the package is distributed through pkgrepo.

Use this document with:

• Package Guide for build, inspect, boot, and install workflows.
• Package Store Format for writable package-store images.
• Static Package Repository for signed HTTP repositories.
• Package Build Automation Guide and Ports Seed Catalog for recipe-driven packages.
• Host Tool Reference for command syntax.

Current Capabilities

Quick Start

Build the host tool and sample package:

make swpkg package-fixture

Inspect and verify the sample package:

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

Expected verification output:

OK: pkghello-1.0.0_1

Extract the payload image for direct overlay tests:

build/swpkg extract-payload build/pkghello.swpkg build/pkghello-payload.img

Install the sample package inside SwiftOS through the checked local install path:

make package-local-install-test

Inside the guest, the equivalent command is:

pkg install /packages/pkghello.swpkg
/usr/bin/pkghello

Container Layout

All integer fields are little-endian. Offsets are absolute byte offsets from the start of the .swpkg file.

*.swpkg
  header              fixed 128-byte SWPKG001 header
  manifest.json       canonical UTF-8 JSON package manifest
  payload.swosbase    uncompressed packed read-only payload image
  signature           reserved; absent in v1

Header v1:

0    u8[8]   magic: "SWPKG001"
8    u32     version: 1
12   u32     header_size: 128
16   u64     manifest_offset
24   u64     manifest_size
32   u64     payload_offset
40   u64     payload_size
48   u8[32]  manifest_sha256
80   u8[32]  payload_sha256
112  u64     signature_offset
120  u64     signature_size

The current writer emits:

• manifest_offset == 128;
• payload_offset == manifest_offset + manifest_size;
• signature_offset == 0;
• signature_size == 0;
• no padding between the header, manifest, and payload.

The verifier rejects bad magic, bad version, bad header size, non-empty reserved signature fields, bad section order, out-of-bounds manifest or payload ranges, and SHA-256 mismatches for the manifest or payload byte ranges.

Manifest JSON

The manifest is a canonical JSON object written with sorted keys. The input file may be hand-written, but swpkg create normalizes it before writing the package. In particular, the generated package file list replaces the input files array with records derived from the staged payload tree.

Required or defaulted top-level fields:

Minimal input manifest:

{
  "format": 1,
  "name": "helloapp",
  "version": "1.0.0",
  "summary": "Small SwiftOS package",
  "arch": "aarch64",
  "target": "swift-os",
  "abi": {
    "os": "swos-0",
    "syscall": 1,
    "libc": "newlib-4.6-swos",
    "linkage": "static"
  },
  "depends": [],
  "provides": ["helloapp"],
  "conflicts": []
}

Generated file records look like this:

{
  "path": "/usr/bin/helloapp",
  "mode": "0755",
  "sha256": "8f7d...",
  "size": 12345
}

mode is a four-digit octal string. The hash is the SHA-256 digest of the file payload bytes, not the digest of a tar entry or host filesystem metadata.

Payload Image

The payload is an uncompressed packed read-only filesystem image in the SWOSBASE family. The current swpkg writer emits payload images with:

• magic SWOSBASE;
• version 2;
• 64-byte header;
• 40-byte entries;
• UTF-8 relative paths;
• NUL-terminated path strings;
• concatenated file payload bytes.

Package payload paths must live under /usr. The staged root therefore contains paths such as:

usr/bin/pkghello
usr/share/nginx/swiftos-nginx.version
usr/etc/ssl/cert.pem

Those paths become guest-visible absolute paths such as /usr/bin/pkghello. Files outside /usr are rejected by swpkg create.

Executable mode is inferred from path prefixes:

extract-payload verifies the package first, then writes the payload padded to a 512-byte sector boundary so it can be attached directly as a QEMU block device. The .swpkg container itself is not the image mounted by the VFS; the verified payload image is.

Create A Package Manually

Create a small staged root:

rm -rf build/helloapp-root
mkdir -p build/helloapp-root/usr/bin
printf '#!/bin/sh\necho hello from package\n' > build/helloapp-root/usr/bin/helloapp
chmod 755 build/helloapp-root/usr/bin/helloapp

Create build/helloapp-manifest.json:

{
  "format": 1,
  "name": "helloapp",
  "version": "1.0.0",
  "revision": 1,
  "summary": "Small package-format example",
  "license": ["swift-os-example"],
  "arch": "aarch64",
  "target": "swift-os",
  "abi": {
    "os": "swos-0",
    "syscall": 1,
    "libc": "newlib-4.6-swos",
    "linkage": "static"
  },
  "depends": [],
  "provides": ["helloapp"],
  "conflicts": []
}

Create and verify the package:

make swpkg
build/swpkg create \
  --manifest build/helloapp-manifest.json \
  --root build/helloapp-root \
  --output build/helloapp.swpkg
build/swpkg inspect build/helloapp.swpkg
build/swpkg verify build/helloapp.swpkg

This example demonstrates the container mechanics. Real guest execution requires a SwiftOS-compatible static AArch64 ELF, so use Application Cookbook or Porting Guide for production packages.

Distribution And Install Paths

The same .swpkg artifact can flow through several checked paths:

Repository signatures authenticate the catalog and package hash metadata. The v1 .swpkg signature fields remain reserved and empty.

Verification Matrix

For a narrow format-only edit, run:

make swpkg package-fixture
/usr/bin/swiftc tests/swpkg_tool_test.swift -o build/swpkg_tool_test
build/swpkg_tool_test
make docs-test

Troubleshooting

Security Notes

• .swpkg v1 hashes protect against accidental or malicious byte changes within the package file, but they do not identify a publisher.
• Signed repository catalogs provide publisher authenticity for network distribution. Keep catalog signing keys separate from local package build scratch files.
• Package payloads are read-only when mounted. Current package install paths activate package content through the package store rather than mutating the immutable base image.
• There are no maintainer scripts in v1. Package installation should not run arbitrary post-install code.
• Current package paths are constrained to /usr; base-system files under /bin, /etc, /models, and /www remain base-image owned.

Source Of Truth

The implementation and tests that define this document are:

• tools/swpkg.swift for the container writer, reader, verifier, and extractor.
• tools/packfs.swift for the packed payload image format.
• fixtures/pkghello/manifest.json for the sample manifest.
• Makefile targets swpkg, package-fixture, and package test targets.
• tests/swpkg_tool_test.swift for deterministic output, inspection, payload extraction, and corrupt package rejection.
• userland/pkg.swift and package install tests for target-side local and repository install behavior.

Edit this page on GitHub