With Swift supporting many different platforms, cross-compilation can boost developer productivity. In certain cases it's the only way to build a Swift package.

SE-0387 proposal introduces Swift SDKs, which bundle together all components required for cross-compilation in a single archive, and make cross builds as easy as running a single command.

Swift SDK authors can assemble such archive manually, but the goal of Swift SDK Generator developed in this repository is to automate this task as much as possible. If you're a platform maintainer, or someone who would like to make cross-compiling easy to your favorite platform, you can tailor the generator source code to your needs and publish a newly generated Swift SDK for users to install.

Usage of Swift SDKs requires Swift 5.9, follow installation instructions on swift.org to install it first.

After that, verify that the experimental-sdk command is available:

swift experimental-sdk list 

The output will either state that no Swift SDKs are available, or produce a list of those you previously had installed, in case you've used the swift experimental-sdk install command before.

The generator depends on the following dependencies to be installed on macOS:

• xz: used for more efficient downloading of package lists for Ubuntu. If xz is not found, the generator will fallback on gzip.
• cmake and ninja: required for building LLVM native for versions of Swift before 6.0. NOTE: if you're building the Swift toolchain outside of Swift SDK Generator, you'll have to uninstall Homebrew CMake or remove it from your PATH before invoking toolchain's build-script due to swiftlang/swift#83060.
• zstd: required to decompress certain downloaded artifacts that use Zstandard compression.

These dependencies can be installed from the Brewfile:

brew bundle install

FreeBSD and Linux are supported as both host and target platforms. macOS is only supported as a host platform. The generator also allows cross-compiling between any Linux distributions officially supported by the Swift project.

Clone this repository into a directory of your choice and make it the current directory. Build and run it with this command:

swift run swift-sdk-generator make-linux-sdk 

This will download required components and produce a Swift SDK for Ubuntu Jammy in the Bundles subdirectory. Follow the steps printed at the end of generator's output for installing the newly generated Swift SDK.

Additional command-line options are available for specifying target platform features, such as Linux distribution name, version, and target CPU architecture. Pass --help flag to see all of the available options:

swift run swift-sdk-generator make-linux-sdk --help 

After installing a Swift SDK, verify that it's available to SwiftPM:

swift experimental-sdk list 

The output of the last command should contain ubuntu22.04. Note the full Swift SDK ID in the output, we'll refer to it subsequently as <generated_sdk_id>.

Create a new project to verify that the SDK works:

mkdir cross-compilation-test cd cross-compilation-test swift package init --type executable 

Build this project with the SDK:

swift build --experimental-swift-sdk <generated_sdk_id> 

Verify that the produced binary is compatible with Linux:

file .build/debug/cross-compilation-test 

That should produce output similar to this:

.build/debug/cross-compilation-test: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0, with debug_info, not stripped 

You can then copy this binary to a Docker image that has Swift runtime libraries installed. For example, for Ubuntu Jammy and Swift 5.9 this would be swift:5.9-jammy-slim. If you'd like to copy the binary to an arbitrary Ubuntu Jammy system, make sure you pass --static-swift-stdlib flag to swift build, in addition to the --experimental-swift-sdk option.

By default, on macOS hosts running on Apple Silicon, the Swift SDK Generator will create Swift SDKs for Ubuntu Jammy on aarch64, which matches the CPU architecture of the host. However, it is possible to change the default target architecture by passing the --target-arch flag:

swift run swift-sdk-generator make-linux-sdk --target-arch x86_64

This will default to building the Swift SDK for x86_64-unknown-linux-gnu. To build for other platforms and environments, supply the --target flag with the full target triple instead.

The Linux distribution name and version can also be passed to change from the default of Ubuntu Jammy:

swift run swift-sdk-generator make-linux-sdk --distribution-name ubuntu --distribution-version 24.04

The host toolchain is not included in the generated Swift SDK by default on Linux to match the behavior of the Static Linux Swift SDKs downloadable from swift.org. However, on macOS, since most users are using Xcode and are likely not using the Swift OSS toolchain to build and run Swift projects, the Swift host toolchain is included by default. This default behavior can be changed by passing --no-host-toolchain:

swift run swift-sdk-generator make-linux-sdk --no-host-toolchain --target-arch x86_64

To generate the Swift SDK on Linux with the host toolchain included, add --host-toolchain:

swift run swift-sdk-generator make-linux-sdk --host-toolchain --target-arch aarch64

You can base your SDK on a container image, such as one of the official Swift images. By default, the command below will build an SDK based on the Ubuntu Jammy image:

swift run swift-sdk-generator make-linux-sdk --with-docker 

To build a RHEL images, use the --distribution-name option. The following command will build a ubi9-based image:

swift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel 

You can also specify the base container image by name:

swift run swift-sdk-generator make-linux-sdk --from-container-image swift:5.9-jammy 

swift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel --from-container-image swift:5.9-rhel-ubi9 

If your project depends on Linux libraries which are not part of a standard base image, you can build your SDK from a custom container image which includes them.

Prepare a Dockerfile which derives from one of the standard images and installs the packages you need. This example installs SQLite and its dependencies on top of the Swift project's Ubuntu Jammy image:

FROM swift:5.9-jammy RUN apt update && apt -y install libsqlite3-dev && apt -y clean 

Build the new container image:

docker build -t my-custom-image -f Dockerfile . 

Finally, build your custom SDK:

swift run swift-sdk-generator make-linux-sdk --with-docker --from-container-image my-custom-image:latest --sdk-name 5.9-ubuntu-with-sqlite 

The .artifactbundle directory produced in the previous section can be packaged as a .tar.gz archive and redistributed in this form. Users of such Swift SDK bundle archive can easily install it with swift experimental-sdk install command, which supports both local file system paths and public http:// and https:// URLs as an argument.

There are several ways to contribute to Swift SDK Generator. To learn about the policies, best practices that govern contributions to the Swift project, and instructions for setting up the development environment please read the Contributor Guide.

If you're interested in adding support for a new platform, please open an issue on this repository first so that the best implementation strategy can be discussed before proceeding with an implementation.

If you have any trouble with the Swift SDK Generator, help is available. We recommend:

• Generator's bug tracker;
• The Swift Forums.

When reporting an issue please follow the bug reporting guidelines, they can be found in contribution guide.

If you’re not comfortable sharing your question with the list, contact details for the code owners can be found in CODEOWNERS; however, Swift Forums is usually the best place to go for help.

Copyright 2022 - 2024 Apple Inc. and the Swift project authors. Licensed under Apache License v2.0 with Runtime Library Exception.

See https://swift.org/LICENSE.txt for license information.

See https://swift.org/CONTRIBUTORS.txt for Swift project authors.