Swift Compiler Deployment Guide

Prerequisites

System Requirements

Operating System: macOS 10.15+ or Ubuntu 20.04/22.04 LTS
Disk Space: 60GB+ free space (full build with debug info)
Memory: 8GB RAM minimum, 16GB+ recommended
CPU: Multi-core processor (4+ cores recommended for reasonable build times)

macOS Requirements

Xcode: Latest stable version (see Getting Started guide for specific version requirements)
Command Line Tools: xcode-select --install

Linux Requirements

Clang: Version compatible with current Swift requirements
Development libraries: libicu-dev, libcurl4-openssl-dev, libxml2-dev, libssl-dev
Python: 3.6 or newer

Build Tools

CMake: 3.19.6 or newer
Ninja: Latest stable
Git: 2.17 or newer

Installation

1. Clone the Repository

git clone https://github.com/apple/swift.git swift
cd swift

2. Clone Dependencies

Swift requires multiple related repositories (LLVM, Clang, etc.). Use the provided script to clone all dependencies:

utils/update-checkout --clone

To update all repositories to the latest compatible versions later:

utils/update-checkout

3. Verify Xcode (macOS)

Ensure Xcode is selected:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Configuration

Build Presets

Swift uses build-script with preset configurations. Common presets include:

buildbot_osx_package (macOS toolchain)
buildbot_linux (Linux toolchain)
buildbot_incremental (Development builds)

Environment Variables

Optional variables for build customization:

export SWIFT_BUILD_ROOT=/path/to/build/dir    # Build output directory
export SWIFT_SOURCE_ROOT=/path/to/swift/src   # Source root (default: current dir)

Compiler Caching (Optional)

Speed up rebuilds with sccache or distcc:

# Install sccache
brew install sccache  # macOS
# or
apt-get install sccache  # Ubuntu

# Set environment variable
export SCCACHE_CACHE_SIZE="50G"

Build & Run

Development Build

For local development and testing:

utils/build-script --release-debuginfo --swift-darwin-supported-archs "$(uname -m)"

Key flags:

--release-debuginfo: Optimized build with debug symbols
--debug: Debug build (slower, larger binaries)
--clean: Clean build (use when switching Xcode versions)
--reconfigure: Reconfigure build system without full rebuild

Building a Toolchain

To create a distributable toolchain package:

./swift/utils/build-toolchain $BUNDLE_PREFIX

Where $BUNDLE_PREFIX is your identifier (e.g., com.example). This produces:

swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz (or linux equivalent)
swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz (debug symbols)

Build Options

./swift/utils/build-toolchain $BUNDLE_PREFIX \
  --dry-run \      # Preview build steps without executing
  --test \         # Run tests after compilation
  --sccache \      # Enable compiler caching
  --distcc         # Enable distributed compilation

Running Tests

After building:

utils/build-script --test

Or for specific test suites:

utils/build-script --test --swiftpm --llbuild

Deployment

Local Installation (macOS)

Install to Xcode Toolchains

Extract the toolchain:

# System-wide (requires sudo)
sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C /

# Or user-local
tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz -C ~/

Install debug symbols (optional):

sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-osx-symbols.tar.gz -C /

Select in Xcode:
- Open Xcode → Preferences → Components → Toolchains
- Or use Xcode > Toolchains menu

Verify Installation

swift --version
which swift

Linux Deployment

Extract to /opt or /usr/local:

sudo tar -xzf swift-LOCAL-YYYY-MM-DD-a-ubuntu22.04.tar.gz -C /opt/
export PATH="/opt/swift-LOCAL-YYYY-MM-DD-a/usr/bin:$PATH"

CI/CD Integration

For automated builds, use the --dry-run flag to validate configurations before execution:

./swift/utils/build-toolchain ci.build --dry-run

Troubleshooting

Build Failures

Xcode Version Mismatches

If you encounter errors related to Xcode versions after updating:

utils/build-script --clean

Incremental Build Issues

When updating to a new Xcode version without full rebuild:

utils/build-script --reconfigure

Out of Disk Space

The build requires significant space. If build fails mid-way:

Clean build products: rm -rf build/
Enable sccache to reduce space usage: ./swift/utils/build-toolchain --sccache
Build only release without debug info: --release instead of --release-debuginfo

Common Issues

Error: "Cannot find source directory"

Ensure you ran utils/update-checkout --clone from the swift directory

Error: "CMake not found"

Install CMake: brew install cmake (macOS) or apt-get install cmake (Linux)

Linking errors on macOS

Ensure Xcode license is accepted: sudo xcodebuild -license accept
Check xcode-select -p points to correct Xcode.app

Slow builds

Use --sccache for C++ caching
Use --distcc for distributed builds across multiple machines
Limit architectures: --swift-darwin-supported-archs "$(uname -m)"

Getting Help

Consult the Getting Started guide
Check the FAQ
Review Continuous Integration docs for testing procedures

How to Deploy & Use apple/swift