SwiftOS Porting Guide

This guide explains how to evaluate and port source-built software to SwiftOS. It is written for application authors, package maintainers, and release owners who need to decide whether a program can run on the current SwiftOS ABI and how to adapt it without importing legacy platform assumptions.

SwiftOS is not Linux, does not provide a Linux ABI, and does not run existing ELF binaries unchanged. Porting means rebuilding from source against the SwiftOS syscall surface, native Embedded Swift bridge, or C/newlib compatibility layer.

Use this guide with:

• Compatibility Guide for platform-level compatibility decisions.
• Developer Guide for native SwiftOS build patterns.
• Application Cookbook for copy-paste app recipes.
• API Reference for syscall numbers, structures, bridge calls, and handle rights.
• Package Guide for package payload and package-store workflows.
• Package Build Automation Guide for the current swport catalog/recipe checks, Lua cross-build fixture, CI, and repository publishing workflow.
• Administration Guide for accounts, capabilities, and image configuration.

Porting Model

SwiftOS ports are static, source-built, and explicit about their dependencies.

The porting goal is not to emulate a legacy Unix distribution. Prefer small source changes, static linking, explicit capability requirements, and tests that prove the exact workflow under QEMU.

First Decision

Do not start with the build system. Start by classifying the program.

If the program is small and core to SwiftOS, rewrite it natively. If the program is an upstream C utility with portable libc assumptions, try newlib. If it depends on Linux kernel surfaces, treat the missing surface as a product decision, not a local hack.

Compatibility Triage

Before editing code, answer these questions.

Record the decision in the package notes or PR description. A good port should make its missing assumptions obvious before code review.

Choose A Build Path

Native Embedded Swift

Use this for new SwiftOS tools and services.

Reference files:

Rules:

• Do not import Foundation.
• Keep binaries static.
• Use swiftos_* bridge calls for OS services.
• Check negative return values explicitly.
• Document required capability bits.
• Add a QEMU test for user-visible behavior.

Raw C Syscalls

Use this for small ABI probes or utilities that do not need libc.

Reference files:

Raw wrappers expose SwiftOS return conventions directly. Most errors are negative errno-like values. Do not assume libc-style -1 plus errno unless you are using a compatibility wrapper that documents it.

C/newlib Compatibility

Use this for C ports that expect printf, malloc, basic POSIX-shaped file APIs, socket declarations, or common libc entry points.

Reference files:

Build the sysroot when needed:

make newlib

Then model the Makefile target on an existing newlib-linked program. Keep the link static and stage the resulting ELF into the base image or a package payload.

Common Code Adaptations

When adding a shim, keep it narrow. A stub that fails clearly is better than a large compatibility layer that silently lies about behavior.

Filesystem Porting

SwiftOS has an immutable base image and RAM-backed /tmp.

Example guest check:

cat /etc/motd
echo ok >/tmp/port-check.txt
cat /tmp/port-check.txt

Writes outside writable tmpfs should fail. Do not work around that by adding mutable root assumptions to the port.

Networking Porting

Networking requires:

1. QEMU launched with a virtio-net device.
2. A principal with capNet.
3. A program built against current socket and poll APIs.

Start with a narrow smoke:

./tests/tcp_echo_test.sh
./tests/udp_echo_test.sh
./tests/dns_test.sh
./tests/socket_test.sh

Use these reference programs:

Current limits:

• No target-side interface configuration command.
• No production certificate trust store policy.
• No Linux netlink, iptables, or routing-tool compatibility.
• /bin/httpd and /bin/llmd both bind guest TCP 8080; test one at a time.

Process And Concurrency Porting

Current process and concurrency tools include:

Guidance:

• Prefer explicit spawn_handles for new designs that pass authority.
• Treat broad fork inheritance as compatibility, not the long-term model.
• Use poll for small servers before adding more process concurrency.
• Respect W^X: PROT_WRITE | PROT_EXEC mappings are rejected.
• Add a stress or QEMU acceptance test when touching concurrency behavior.

Packaging A Port

Use a package payload when the port should not become part of the default base image.

Current package flow:

make package-fixture
make package-overlay-test
make package-store-test
make package-local-install-test
make package-repo-install-test

Package content is read-only at runtime. Put binaries under /usr/bin in the payload namespace unless the package guide says otherwise.

For source ports, use the ports tool and the current seed fixtures:

make ports-catalog-test
make ports-recipe-test
make ports-lua-repo-fixture
build/swpkg inspect build/lua.swpkg
build/pkgrepo inspect build/lua-repo-root/aarch64/current/catalog.signed
make package-lua-repo-install-test
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-pcre2-repo-fixture
make ports-tzdata-repo-fixture
make ports-nginx-repo-fixture
make ports-sqlite-repo-fixture
make ports-seed-repo-fixture
make package-ports-seed-repo-install-test
make ports-static-host-publish
make package-static-host-repo-install-test
make ports-hosted-url-verify-test
make package-static-host-dns-repo-install-test

The checked Lua, zlib, bzip2, zstd, xz, libarchive, ca-certificates, OpenSSL, pcre2, tzdata, nginx, and sqlite recipes are the reference shapes today. Together they prove static AArch64 builds or data-only staging, signed local repository fixtures, guest pkg install by package name, Lua runtime checks, minigzip, bzip2, zstd, and xz compression/decompression smokes, bsdtar tar create/list smoke, CA and zoneinfo marker reads, a pcre2grep regex match, nginx version/marker checks, a SQLite in-memory query, and static-host publication from build/ports-static-host-root. The hosted URL smoke also proves the target package manager can use a DNS-resolved HTTP repository hostname for the same twelve-package seed.

Before publishing a package recipe, record:

• Source origin and license.
• Build flags and static-link choices.
• Installed paths.
• Required capability bits.
• Guest command used for verification.
• Known disabled upstream features.
• Acceptance test name.

See Package Guide and Server Software Catalog.

Testing A Port

Every shipped port needs an executable proof.

Minimum gates for a user-visible port:

make build base-image
./tests/boot_test.sh

Use make test before calling a broad userland or compatibility change release-ready.

Documentation For A Port

When a port becomes a supported SwiftOS workflow, update the relevant docs:

Prefer documenting the exact current behavior. Future goals belong in roadmap documents unless the feature already works.

Port Review Checklist

Before merging a port:

1. The program is rebuilt from source for aarch64-none-none-elf.
2. The binary is static.
3. No Linux ABI, dynamic loader, /proc, /sys, or kernel-module assumption remains in the supported path.
4. Runtime writes are under /tmp or an explicitly documented service.
5. Installed defaults are in the base image or package payload.
6. Required capability bits are documented.
7. Negative SwiftOS syscall returns are handled.
8. Network tests name the QEMU forwarding and guest port.
9. A focused test proves the main user-visible behavior.
10. User-facing docs and troubleshooting notes are updated.

Useful Reference Programs

Use these as working examples before inventing a new pattern.

When To Defer A Port

Deferring is the right choice when the port would require a broad compatibility fiction.

Defer when the program requires:

• Linux kernel modules or device nodes that SwiftOS does not expose.
• Dynamic libraries or plugin loading as a core feature.
• Persistent database or writable-root semantics that cannot be redesigned.
• Full pthreads or process-group behavior not covered by current APIs.
• /proc, /sys, netlink, cgroups, namespaces, seccomp, or containers.
• GPU, CUDA, ROCm, or desktop graphics stacks.
• Production TLS trust policy before the trust-store work lands.

Record the blocker in the package catalog or roadmap so the dependency is visible and can be scheduled deliberately.

Edit this page on GitHub