Getting started

This page summarizes the build/test/debug loop for the Swift compiler and toolchain. The canonical, longer reference is docs/HowToGuides/GettingStarted.md.

Prerequisites

• A working C++ toolchain (Clang on macOS/Linux, Visual Studio + clang-cl on Windows).
• Python 3.6+ — utils/build-script is Python.
• CMake 3.x and Ninja.
• ~70 GB of free disk for a full debug build.
• For Linux: see the package list in docs/HowToGuides/GettingStarted.md. Roughly: git, ninja-build, python3, clang, libicu-dev, libpython3-dev, swig, uuid-dev, libxml2-dev, libsqlite3-dev, tzdata, pkg-config.
• For Windows: see docs/WindowsBuild.md.

Source layout

The build expects a workspace directory containing several side-by-side checkouts:

swift-source/
├── swift/             # this repo (apple/swift)
├── llvm-project/      # apple/llvm-project (Swift fork)
├── cmark/
├── swift-corelibs-libdispatch/
├── swift-corelibs-foundation/
├── swift-corelibs-xctest/
├── swift-driver/
├── swift-tools-support-core/
├── swiftpm/
├── ...

Use update-checkout to clone everything at compatible revisions:

git clone https://github.com/apple/swift.git
./swift/utils/update-checkout --clone

First build

The simplest "I want to hack on the compiler" command is a debug build via the Onone preset:

./swift/utils/build-script --preset=buildbot_incremental \
  --release-debuginfo --skip-build-benchmarks

For a faster local incremental compiler-only build that skips standard-library cross-compilation:

./swift/utils/build-script -r --skip-build-benchmarks --skip-test-cmark \
  --skip-test-swift --skip-build-swift-stdlib-static-mirror \
  --swift-stdlib-build-type=Release

The toolchain is produced under ../build/Ninja-RelWithDebInfoAssert/ (or similar, depending on preset). Useful binaries:

• bin/swift — driver
• bin/swift-frontend — frontend
• bin/swift-demangle, bin/swift-ide-test, bin/sourcekit-test, bin/swift-refactor, etc.

Running the test suite

The compiler has multiple test targets; see Testing. The typical fast iteration is:

./swift/utils/run-test --build-dir ../build/Ninja-RelWithDebInfoAssert \
  swift/test/Sema

Or directly via lit:

ninja -C ../build/Ninja-RelWithDebInfoAssert/swift-macosx-arm64 check-swift

Building a toolchain

To produce a toolchain tarball for ~/Library/Developer/Toolchains/ (macOS) or for distribution:

./swift/utils/build-toolchain com.example

See utils/build-toolchain for options (--dry-run, --test, --distcc, --sccache).

Editor integration

• Generate an Xcode project: utils/generate-xcode.
• VS Code: open the workspace, add clangd for C++ IntelliSense; the build script can emit a compile_commands.json next to build.ninja.
• Emacs / Vim: utils/swift-mode.el, utils/sil-mode.el.

Useful environment knobs

• SWIFT_FORCE_TEST_MODE — see utils/run-test.
• SWIFT_DEBUG_* — runtime debug flags; see stdlib/public/runtime/EnvironmentVariables.def.
• SWIFT_BACKTRACE — backtracer configuration; see docs/Backtracing.rst.

Where to start hacking

• A simple bug in stdlib types: stdlib/public/core/. Add a test under test/stdlib/.
• A new SIL pass: SwiftCompilerSources/Sources/Optimizer/Passes/. Test under test/SILOptimizer/.
• A diagnostic improvement: lib/Sema/ plus the .def file under include/swift/AST/DiagnosticsSema.def. Test under test/Sema/.
• A new built-in or runtime entry point: stdlib/public/runtime/ plus include/swift/Runtime/.

For a guided tour, see How to contribute.