Build system

The repo uses CMake + Ninja, driven by Python wrappers (utils/build-script, utils/build-toolchain, utils/run-test). This page summarizes the structure.

Top-level layout

swift/
├── CMakeLists.txt                    # the top-level CMake file
├── cmake/modules/                    # custom CMake helpers (most of the magic)
│   ├── AddSwift.cmake
│   ├── SwiftSource.cmake
│   ├── SwiftHandleGybSources.cmake
│   ├── SwiftSetIfArchBitness.cmake
│   ├── DarwinSDKs.cmake
│   └── ...
├── lib/CMakeLists.txt                # compiler libraries
├── tools/CMakeLists.txt              # binaries
├── stdlib/CMakeLists.txt             # standard library + overlays
├── Runtimes/CMakeLists.txt           # alternative stdlib build
├── unittests/CMakeLists.txt          # GoogleTest-based unit tests
├── benchmark/CMakeLists.txt          # benchmark suite
├── docs/CMakeLists.txt
└── utils/build-script[-impl] | build-toolchain | run-test

build-script and build-script-impl

utils/build-script (Python) is the canonical entry point. It parses high-level options (presets, target lists, optimization levels), then calls utils/build-script-impl (a Bash-style script written in Python that essentially shells out to CMake/Ninja).

Common invocations:

# Default debug build of compiler + stdlib for the host
./utils/build-script

# Release-with-assertions, run tests
./utils/build-script -R --test

# Use a named preset
./utils/build-script --preset=buildbot_incremental

# Build a redistributable toolchain
./utils/build-toolchain com.example

Presets live in utils/build-presets.ini.

CMake helpers

cmake/modules/AddSwift.cmake defines the project's custom CMake functions:

• add_swift_target_library(...) -- define a Swift library compiled per target.
• add_swift_host_library(...) -- a library compiled for the host build.
• add_swift_host_tool(...) -- an executable for the host (a tool).
• add_swift_unittest(...) -- a GoogleTest unit test binary.

cmake/modules/SwiftSource.cmake handles .swift sources for the standard library: per-arch invocations of the just-built compiler, with the correct module name and import paths.

cmake/modules/SwiftHandleGybSources.cmake runs gyb over .gyb files at configure time.

Runtimes/

The new alternative build at Runtimes/CMakeLists.txt is a separate CMake project (no transitive dependencies on the main top-level CMakeLists.txt). It pulls source files from stdlib/ via Runtimes/Resync.cmake. See Runtimes.

Build outputs

A typical build produces (under ../build/Ninja-RelWithDebInfoAssert/):

• swift-macosx-arm64/bin/ -- compiler binaries (swift, swift-frontend, swift-demangle, swift-ide-test, ...).
• swift-macosx-arm64/lib/swift/ -- the standard library and overlays per target.
• swift-macosx-arm64/lib/sourcekitd.framework -- on Apple, the SourceKit framework.
• swift-macosx-arm64/test-{macosx-arm64,...}/ -- per-target test outputs.
• swift-macosx-arm64/compile_commands.json -- for clangd / IDE integration.

Cross-compilation

The standard library is cross-compiled for many targets in a single build invocation (Apple SDKs, Linux, Android, Wasm, Windows). The list is controlled by build-script flags (--ios, --watchos, --tvos, --android, --wasi, --windows).

For a non-Apple target, cross-compile with the matching --<target> flag and an --<target>-sysroot pointing at the sysroot.

Testing infrastructure

• LLVM lit drives the test suite (test/lit.cfg).
• utils/run-test is a thin wrapper around lit that handles building dependencies first.
• unittests/ uses GoogleTest, exposed as check-swift-unittest in the Ninja graph.

See Testing for the day-to-day flow.

Bootstrapping

Some compiler libraries (those in SwiftCompilerSources/) are built with the just-built swift-frontend. The build orchestrates:

1. Build the C++ compiler.
2. Use it to compile the standard library.
3. Use the just-built compiler + stdlib to compile SwiftCompilerSources/.
4. Re-link the C++ compiler with the bootstrapped Swift libraries.

cmake/modules/SwiftHandleSwiftSources.cmake and the multi-stage targets (bootstrapping0, bootstrapping1) handle this dance.