Dmitry Kovba
a339606068
This PR resolves the following error for new users:
```
% make cross-prep
Installing Swiftly...
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 8549k 100 8549k 0 0 14.7M 0 --:--:-- --:--:-- --:--:-- 14.8M
installer: Package name is
installer: Installing at base path /Users/Dmitry
installer: The install was successful.
Welcome to swiftly, the Swift toolchain manager for Linux and macOS!
Please read the following information carefully before proceeding with the installation. If you
wish to customize the steps performed during the installation process, refer to 'swiftly init -h'
for configuration options.
Swiftly installs files into the following locations:
/Users/Dmitry/.swiftly - Directory for configuration files
/Users/Dmitry/.swiftly/bin - Links to the binaries of the active toolchain
/Users/Dmitry/Library/Developer/Toolchains - Directory hosting installed toolchains
These locations can be changed by setting the environment variables
SWIFTLY_HOME_DIR, SWIFTLY_BIN_DIR, and SWIFTLY_TOOLCHAINS_DIR before running 'swiftly init' again.
For your convenience, swiftly will also attempt to modify your shell's profile file to make
installed items available in your environment upon login. This can be suppressed with the
'--no-modify-profile' option.
Proceed? (Y/n):
Installing swiftly in /Users/Dmitry/.swiftly/bin/swiftly...
Error: The file “swiftly” couldn’t be opened because there is no such file.
make[1]: *** [swiftly] Error 1
make: *** [cross-prep] Error 2
```
Containerization
The Containerization package allows applications to use Linux containers. Containerization is written in Swift and uses Virtualization.framework on Apple silicon.
Containerization provides APIs to:
- Manage OCI images.
- Interact with remote registries.
- Create and populate ext4 file systems.
- Interact with the Netlink socket family.
- Create an optimized Linux kernel for fast boot times.
- Spawn lightweight virtual machines and manage the runtime environment.
- Spawn and interact with containerized processes.
- Use Rosetta 2 for running linux/amd64 containers on Apple silicon.
Please view the API documentation for information on the Swift packages that Containerization provides.
Design
Containerization executes each Linux container inside of its own lightweight virtual machine. Clients can create dedicated IP addresses for every container to remove the need for individual port forwarding. Containers achieve sub-second start times using an optimized Linux kernel configuration and a minimal root filesystem with a lightweight init system.
vminitd is a small init system, which is a subproject within Containerization.
vminitd is spawned as the initial process inside of the virtual machine and provides a GRPC API over vsock.
The API allows the runtime environment to be configured and containerized processes to be launched.
vminitd provides I/O, signals, and events to the calling process when a process is run.
Requirements
To build the Containerization package, you need:
- Mac with Apple silicon
- macOS 15 minimum, macOS 26 beta recommended
- Xcode 26 beta
Applications built using the package will run on macOS 15 or later, but the following features are not available on macOS 15:
- Non-isolated container networking - with macOS 15, containers on the same vmnet network cannot communicate with each other
Example Usage
For examples of how to use some of the libraries surface, the cctl executable is a good start. This tools primary job is as a playground to trial out the API. It contains commands that exercise some of the core functionality of the various products, such as:
- Manipulating OCI images
- Logging in to container registries
- Creating root filesystem blocks
- Running simple Linux containers
Linux kernel
A Linux kernel is required for spawning lightweight virtual machines on macOS. Containerization provides an optimized kernel configuration located in the kernel directory.
This directory includes a containerized build environment to easily compile a kernel for use with Containerization.
The kernel configuration is a minimal set of features to support fast start times and a light weight environment.
While this configuration will work for the majority of workloads we understand that some will need extra features. To solve this Containerization provides first class APIs to use different kernel configurations and versions on a per container basis. This enables containers to be developed and validated across different kernel versions.
See the README in the kernel directory for instructions on how to compile the optimized kernel.
Pre-built Kernel
If you wish to consume a pre-built kernel it must have VIRTIO drivers compiled into the kernel, not as modules.
The Kata Containers project provides an optimized kernel for containers with all the required configuration options enabled provided on the releases page.
A kernel image named vmlinux.container can be found in the /opt/kata/share/kata-containers/ directory of the release artifacts.
Prepare to build package
Install the recommended version of Xcode.
Set the active developer directory to the installed Xcode (replace <PATH_TO_XCODE>):
sudo xcode-select -s <PATH_TO_XCODE>
Install Swiftly, Swift, and Static Linux SDK:
make cross-prep
If you use a custom terminal application, you may need to move this command from .zprofile to .zshrc (replace <USERNAME>):
# Added by swiftly
. "/Users/<USERNAME>/.swiftly/env.sh"
Restart the terminal application. Ensure this command returns /Users/<USERNAME>/.swiftly/bin/swift (replace <USERNAME>):
which swift
If you've installed or used a Static Linux SDK previously, you may need to remove older SDK versions from the system (replace <SDK-ID>):
swift sdk list
swift sdk remove <SDK-ID>
Build the package
Build Containerization from sources:
make all
Test the package
After building, run basic and integration tests:
make test integration
A kernel is required to run integration tests.
If you do not have a kernel locally for use a default kernel can be fetched using the make fetch-default-kernel target.
Fetching the default kernel only needs to happen after an initial build or after a make clean.
make fetch-default-kernel
make all test integration
Protobufs
Containerization depends on specific versions of grpc-swift and swift-protobuf. You can install them and re-generate RPC interfaces with:
make protos
Documentation
Generate the API documentation for local viewing with:
make docs
make serve-docs
Preview the documentation by running in another terminal:
open http://localhost:8000/documentation/
Contributing
Contributions to Containerization are welcomed and encouraged. Please see CONTRIBUTING.md for more information.
Project Status
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.
Future minor versions of the package may introduce changes to these rules as needed.