From 5687d86e8d2762c4406d51a117e35654f177bd0d Mon Sep 17 00:00:00 2001 From: Andrew Moore Date: Mon, 10 Aug 2026 02:00:05 -0700 Subject: [PATCH] Merge nucleic/upbeat-meadow-lemur-mcim into dev --- README.md | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e81eb1..5d8aa19 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,46 @@  Containerization +> [!IMPORTANT] +> **This is a fork of [apple/containerization](https://github.com/apple/containerization), modified +> for Nucleic.** It is not Apple's distribution, it is not maintained by Apple, and it is not a +> drop-in replacement for upstream. Apple's original README follows below; anything specific to this +> fork is described under [Nucleic fork](#nucleic-fork). If you want the unmodified package, use +> [apple/containerization](https://github.com/apple/containerization). + The Containerization package allows applications to use Linux containers. Containerization is written in [Swift](https://www.swift.org) and uses [Virtualization.framework](https://developer.apple.com/documentation/virtualization) on Apple silicon. > **Looking for command line binaries for running containers?**\ > They are available in the dedicated [apple/container](https://github.com/apple/container) repository. +## Nucleic fork + +Nucleic embeds this package to run Linux workloads on macOS. Upstream targets the general case of +short-lived, one-process-per-container usage; Nucleic drives it much harder than that, and the +divergence exists to make those conditions survivable. Broadly, the changes fall into a few areas: + +- **Host and guest I/O robustness.** Hardening of the stdio and socket relay paths so that one slow, + stalled, or dying stream cannot block, starve, or tear down the others that share a transport. +- **Lifecycle bounds.** Deadlines, cancellation, and teardown guarantees on operations that upstream + allows to block indefinitely, plus independent escape hatches for stopping a virtual machine that + is no longer answering. +- **Per-workload resource isolation.** Finer-grained cgroup placement and limits inside the guest, so + resource exhaustion is contained to the workload that caused it. +- **Host integration.** Additional configuration surface the embedding application needs, and + non-interactive behavior in places where upstream may prompt the user. + +The details are deliberately kept out of this file. Every divergence is enumerated in +[`PATCHES.md`](./PATCHES.md), and every edit site in the sources is marked with a +`[Nucleic vendored patch]` comment, so upstream code and fork code stay easy to tell apart. + +Two consequences worth knowing before you use this fork: + +- It tracks a **pinned upstream commit** rather than upstream `main`, and `Tests/`, `docs/`, + `examples/`, and `images/` are trimmed from the tree. +- Some changes live in the guest agent (`vminitd/`) and are **inert until the init filesystem image is + rebuilt** from this source and the consuming application is pointed at it. + Containerization provides APIs to: - [Manage OCI images](./Sources/ContainerizationOCI/). @@ -169,10 +203,18 @@ open http://localhost:8000/containerization/documentation/ ## Contributing -Contributions to Containerization are welcomed and encouraged. Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information. +Contributions that are not specific to Nucleic belong upstream, at +[apple/containerization](https://github.com/apple/containerization) — see +[CONTRIBUTING.md](/CONTRIBUTING.md); anything landed upstream reaches this fork on the next +re-vendor. Changes to the fork's own divergence should come with a corresponding entry in +[`PATCHES.md`](./PATCHES.md) and a `[Nucleic vendored patch]` marker at each edit site, so the next +re-vendor can re-apply them. ## Project Status +This fork carries no stability guarantees of its own: it exists to serve Nucleic, and its API may +change with Nucleic's needs. Upstream's own status statement follows. + Version 0.1.0 is the first official release of Containerization. Earlier versions have no source stability guarantees. Because the Containerization library is under active development, source stability is only guaranteed within minor versions (for example, between 0.1.1 and 0.1.2). If you don't want potentially source-breaking package updates, you can specify your package dependency using .upToNextMinorVersion(from: "0.1.0") instead.