swift / swiftc / swift-frontend

Active contributors: jrose-apple, compnerd, hamishknight

Purpose

The user-facing swift and swiftc binaries are produced by tools/driver/. Both are the same executable -- the binary's name (or the first argument) selects between the driver, the frontend, the REPL, and several lesser-used subcommands. This page covers the binary surface; the internal architecture is in Frontend and driver.

Binary modes

A single binary is shipped under several names. tools/driver/driver.cpp calls swift::mainEntry in lib/DriverTool/DriverTool.cpp, which dispatches by argv[0]:

Invocation	Mode
swift	Driver. Discovers files, runs frontend per primary, links.
swiftc	Same as swift, with default action -c (compile-and-link).
swift -frontend	Frontend body. Per-invocation compile.
swift repl	Interactive REPL (uses LLDB under the hood).
swift -i	Interpret a script (immediate mode).
swift package, swift build, swift test, swift run	Forward to the swift-package-manager subcommand binaries.
swift demangle	Forward to swift-demangle.
swift symbolgraph-extract	Forward to swift-symbolgraph-extract.
swift api-digester	Forward to swift-api-digester.

Driver vs the Swift driver

There are two driver implementations:

1. C++ lib/Driver/ -- in-tree, a fallback. Used by some legacy paths.
2. swift-driver -- a separate Swift-implemented driver in a sibling repo. Default in shipping toolchains.

Most users never have to think about the distinction. lib/DriverTool/DriverTool.cpp decides at runtime which driver to use based on environment / build flags.

Common flags

A non-exhaustive cheat sheet:

Flag	What it does
-c	Compile-only (don't link).
-emit-module	Build a .swiftmodule.
-emit-library	Build a .dylib / .so / .dll.
-emit-executable	Build an executable (default).
-emit-sil / -emit-silgen	Print canonical / raw SIL.
-emit-ir / -emit-bc	Print LLVM IR / bitcode.
-O / -Osize / -Onone	Optimization level.
-whole-module-optimization	One frontend invocation per module.
-language-version 5 / 6	Pick a language mode.
-enable-experimental-feature Foo	Turn on an experimental feature (gated in Features.def).
-Xfrontend <flag>	Pass a flag to swift-frontend.
-Xllvm <flag>	Pass a flag to LLVM (e.g., -sil-print-after=...).
-Xclang-importer <flag>	Pass a flag to the embedded Clang.
-resource-dir <path>	Override the resource (stdlib) location.
-sdk <path>	Pick a target SDK.
-sanitize=address / thread	Enable sanitizers.

Run swift -help for the user-visible list, or swift -frontend -help-hidden for the internal flags.

Where flags are defined

The single source of truth is lib/Option/Options.td -- a TableGen file consumed by both this repo's C++ and by swift-driver. New flags should be added there first.

Integration points

• lib/DriverTool/ -- subcommand dispatch.
• lib/Driver/ -- the C++ driver fallback.
• lib/Frontend/, lib/FrontendTool/ -- the per-invocation compiler.
• lib/Option/Options.td -- the option definitions.

Related pages

• Frontend and driver -- internal architecture.
• Auxiliary tools -- companions invoked from the driver.