{"id":11667202,"url":"https://github.com/swiftlang/swift-sdk-generator","last_synced_at":"2025-12-11T23:01:37.217Z","repository":{"id":196117130,"uuid":"596282217","full_name":"swiftlang/swift-sdk-generator","owner":"swiftlang","description":"Generate Swift SDKs for cross-compilation","archived":false,"fork":false,"pushed_at":"2025-06-04T16:21:32.000Z","size":626,"stargazers_count":201,"open_issues_count":27,"forks_count":18,"subscribers_count":89,"default_branch":"main","last_synced_at":"2025-06-04T21:06:33.044Z","etag":null,"topics":["cross-compilation","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swiftlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-01T21:07:11.000Z","updated_at":"2025-06-04T16:21:32.000Z","dependencies_parsed_at":"2024-04-18T12:33:31.985Z","dependency_job_id":"fe22d4f7-c7a7-41ff-8893-33e1a629f64b","html_url":"https://github.com/swiftlang/swift-sdk-generator","commit_stats":null,"previous_names":["apple/swift-sdk-generator","swiftlang/swift-sdk-generator"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/swiftlang/swift-sdk-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-sdk-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-sdk-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-sdk-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-sdk-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swiftlang","download_url":"https://codeload.github.com/swiftlang/swift-sdk-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftlang%2Fswift-sdk-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260546056,"owners_count":23025860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-compilation","swift"],"created_at":"2024-06-25T14:04:48.596Z","updated_at":"2025-12-11T23:01:37.211Z","avatar_url":"https://github.com/swiftlang.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"# Swift SDK Generator\n\n## Overview\n\nWith Swift supporting many different platforms, cross-compilation can boost developer productivity. In certain cases it's\nthe only way to build a Swift package.\n\n[SE-0387](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) proposal\nintroduces Swift SDKs, which bundle together all components required for cross-compilation in a single archive, and\nmake cross builds as easy as running a single command.\n\nSwift SDK authors can assemble such archive manually, but the goal of Swift SDK Generator developed in this repository\nis to automate this task as much as possible. If you're a platform maintainer, or someone who would like to make\ncross-compiling easy to your favorite platform, you can tailor the generator source code to your needs and publish\na newly generated Swift SDK for users to install.\n\n## Requirements\n\nUsage of Swift SDKs requires Swift 5.9, follow [installation instructions on swift.org](https://www.swift.org/install/) to install it first.\n\nAfter that, verify that the `experimental-sdk` command is available:\n\n```\nswift experimental-sdk list\n```\n\nThe 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.\n\n### macOS Requirements\n\nThe generator depends on the following dependencies to be installed on macOS:\n\n- `xz`: used for more efficient downloading of package lists for Ubuntu. If `xz` is not found, the generator will fallback on `gzip`.\n- `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](https://github.com/swiftlang/swift/pull/83060).*_\n- `zstd`: required to decompress certain downloaded artifacts that use [Zstandard](https://github.com/facebook/zstd) compression.\n\nThese dependencies can be installed from the `Brewfile`:\n\n```bash\nbrew bundle install\n```\n\n## Supported platforms and minimum versions\n\nFreeBSD and Linux are supported as both host and target platforms. macOS is only supported as a host platform.\nThe generator also allows cross-compiling between any Linux distributions officially supported by the Swift project.\n\n| Platform       | Supported Version as Host | Supported Version as Target |\n| -:             | :-                        | :-                          |\n| macOS (arm64)  | ✅ macOS 13.0+            | ❌                         |\n| macOS (x86_64) | ✅ macOS 13.0+[^1]        | ❌                         |\n| FreeBSD        | ✅ 14.3+                  | ✅ 14.3+                   |\n| Ubuntu         | ✅ 20.04+                 | ✅ 20.04+                  |\n| Debian         | ✅ 11, 12[^2]             | ✅ 11, 12[^2]              |\n| RHEL           | ✅ Fedora 39, UBI 9       | ✅ Fedora 39, UBI 9[^3]    |\n| Amazon Linux 2 | ✅ Supported              | ✅ Supported[^3]           |\n\n[^1]: Since LLVM project doesn't provide pre-built binaries of `lld` for macOS on x86_64, it will be automatically built\nfrom sources by the generator, which will increase its run by at least 15 minutes on recent hardware. You will also\nneed CMake and Ninja preinstalled (e.g. via `brew install cmake ninja`).\n[^2]: Swift does not officially support Debian 11 or Debian 12 with Swift versions before 5.10.1. However, the Ubuntu 20.04/22.04 toolchains can be used with Debian 11 and 12 (respectively) since they are binary compatible.\n[^3]: These versions are technically supported but require custom commands and a Docker container to build the Swift SDK, as the generator will not download dependencies for these distributions automatically. See [issue #138](https://github.com/swiftlang/swift-sdk-generator/issues/138).\n\n## How to use it\n\nClone this repository into a directory of your choice and make it the current directory. Build and run it with this command:\n\n```\nswift run swift-sdk-generator make-linux-sdk\n```\n\nThis will download required components and produce a Swift SDK for Ubuntu Jammy in the `Bundles` subdirectory. Follow the steps\nprinted at the end of generator's output for installing the newly generated Swift SDK.\n\nAdditional command-line options are available for specifying target platform features, such as Linux distribution name,\nversion, and target CPU architecture. Pass `--help` flag to see all of the available options:\n\n```\nswift run swift-sdk-generator make-linux-sdk --help\n```\n\nAfter installing a Swift SDK, verify that it's available to SwiftPM:\n\n```\nswift experimental-sdk list\n```\n\nThe output of the last command should contain `ubuntu22.04`. Note the full Swift SDK ID in the output, we'll refer to it\nsubsequently as `\u003cgenerated_sdk_id\u003e`.\n\nCreate a new project to verify that the SDK works:\n\n```\nmkdir cross-compilation-test\ncd cross-compilation-test\nswift package init --type executable\n```\n\nBuild this project with the SDK:\n\n```\nswift build --experimental-swift-sdk \u003cgenerated_sdk_id\u003e\n```\n\nVerify that the produced binary is compatible with Linux:\n\n```\nfile .build/debug/cross-compilation-test\n```\n\nThat should produce output similar to this:\n\n```\n.build/debug/cross-compilation-test: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), \ndynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0, with debug_info, not stripped\n```\n\nYou can then copy this binary to a Docker image that has Swift runtime libraries installed. For example,\nfor Ubuntu Jammy and Swift 5.9 this would be `swift:5.9-jammy-slim`. If you'd like to copy the binary to\nan arbitrary Ubuntu Jammy system, make sure you pass `--static-swift-stdlib` flag to `swift build`, in addition\nto the `--experimental-swift-sdk` option.\n\n## Common Generator Options\n\nBy default, on macOS hosts running on Apple Silicon, the Swift SDK Generator will create Swift SDKs\nfor Ubuntu Jammy on aarch64, which matches the CPU architecture of the host. However, it is possible to change\nthe default target architecture by passing the `--target-arch` flag:\n\n```bash\nswift run swift-sdk-generator make-linux-sdk --target-arch x86_64\n```\n\nThis will default to building the Swift SDK for `x86_64-unknown-linux-gnu`. To build for other\nplatforms and environments, supply the `--target` flag with the full target triple instead.\n\nThe Linux distribution name and version can also be passed to change from the default of Ubuntu Jammy:\n\n```bash\nswift run swift-sdk-generator make-linux-sdk --distribution-name ubuntu --distribution-version 24.04\n```\n\n### Host Toolchain\n\nThe host toolchain is not included in the generated Swift SDK by default on Linux to match the behavior\nof the [Static Linux Swift SDKs](https://www.swift.org/documentation/articles/static-linux-getting-started.html)\ndownloadable from [swift.org](https://www.swift.org/install/). However, on macOS, since most users are using Xcode\nand are likely not using the Swift OSS toolchain to build and run Swift projects, the Swift host toolchain\nis included by *default*. This default behavior can be changed by passing  `--no-host-toolchain`:\n\n```bash\nswift run swift-sdk-generator make-linux-sdk --no-host-toolchain --target-arch x86_64\n```\n\nTo generate the Swift SDK on Linux with the host toolchain included, add `--host-toolchain`:\n\n```bash\nswift run swift-sdk-generator make-linux-sdk --host-toolchain --target-arch aarch64\n```\n\n## Building an SDK from a container image\n\nYou can base your SDK on a container image, such as one of the\n[official Swift images](https://hub.docker.com/_/swift).   By\ndefault, the command below will build an SDK based on the Ubuntu\nJammy image:\n```\nswift run swift-sdk-generator make-linux-sdk --with-docker\n```\nTo build a RHEL images, use the `--distribution-name` option.\nThe following command will build a `ubi9`-based image:\n```\nswift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel\n```\n\nYou can also specify the base container image by name:\n\n```\nswift run swift-sdk-generator make-linux-sdk --from-container-image swift:5.9-jammy\n```\n\n```\nswift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel --from-container-image swift:5.9-rhel-ubi9\n```\n\n### Including extra Linux libraries\n\nIf your project depends on Linux libraries which are not part of a\nstandard base image, you can build your SDK from a custom container\nimage which includes them.\n\nPrepare a `Dockerfile` which derives from one of the standard images\nand installs the packages you need.   This example installs SQLite\nand its dependencies on top of the Swift project's Ubuntu Jammy image:\n\n```\nFROM swift:5.9-jammy\nRUN apt update \u0026\u0026 apt -y install libsqlite3-dev \u0026\u0026 apt -y clean\n```\n\nBuild the new container image:\n```\ndocker build -t my-custom-image -f Dockerfile .\n```\n\nFinally, build your custom SDK:\n```\nswift run swift-sdk-generator make-linux-sdk --with-docker --from-container-image my-custom-image:latest --sdk-name 5.9-ubuntu-with-sqlite\n```\n\n## Swift SDK distribution\n\nThe `.artifactbundle` directory produced in the previous section can be packaged as a `.tar.gz` archive and redistributed\nin this form. Users of such Swift SDK bundle archive can easily install it with `swift experimental-sdk install`\ncommand, which supports both local file system paths and public `http://` and `https://` URLs as an argument.\n\n\n## Contributing\n\nThere 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](CONTRIBUTING.md).\n\nIf 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. \n\n## Reporting issues\n\nIf you have any trouble with the Swift SDK Generator, help is available. We recommend:\n\n* Generator's [bug tracker](https://github.com/swiftlang/swift-sdk-generator/issues);\n* The [Swift Forums](https://forums.swift.org/c/development/swiftpm/).\n\nWhen reporting an issue please follow the bug reporting guidelines, they can be found in [contribution guide](./CONTRIBUTING.md#how-to-submit-a-bug-report).\n\nIf you’re not comfortable sharing your question with the list, contact details for the code owners can be found in [CODEOWNERS](.github/CODEOWNERS); however, Swift Forums is usually the best place to go for help.\n\n## License\n\nCopyright 2022 - 2024 Apple Inc. and the Swift project authors. Licensed under Apache License v2.0 with Runtime Library Exception.\n\nSee [https://swift.org/LICENSE.txt](https://swift.org/LICENSE.txt) for license information.\n\nSee [https://swift.org/CONTRIBUTORS.txt](https://swift.org/CONTRIBUTORS.txt) for Swift project authors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-sdk-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswiftlang%2Fswift-sdk-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftlang%2Fswift-sdk-generator/lists"}