Configuration

Selected runtime environment variables, frontend flags, and feature gates. The full lists live in source .def files; this page is a curated jumping-off point.

Runtime environment variables

The runtime reads many environment variables, defined in stdlib/public/runtime/EnvironmentVariables.def. Useful subset:

Variable	Purpose
SWIFT_DEBUG_RUNTIME_ENVIRONMENT_VARIABLES=1	Print the recognized variables on startup.
SWIFT_DEBUG_FAILED_TYPE_LOOKUP=1	Log failures during dynamic type metadata lookup.
SWIFT_DEBUG_VALIDATE_UNCACHED_GENERIC_METADATA=1	Verify generic metadata caches.
SWIFT_DETERMINISTIC_HASHING=1	Use a fixed seed for Hasher (reproducible bug repros).
SWIFT_BACKTRACE	Configure the in-process backtracer (see docs/Backtracing.rst).
SWIFT_DEBUG_ENABLE_MALLOC_SCRIBBLE=1	Poison freed metadata allocations.
SWIFT_BINARY_COMPATIBILITY_VERSION	Override compatibility-shim selection.

Concurrency runtime variables

Variable	Purpose
SWIFT_DEBUG_RUNTIME_TRACK_ACTORS=1	Track actor lifecycles.
SWIFT_PRIORITY_QUEUE_SCHED_FIFO=1	Force FIFO scheduling in the cooperative pool.
SWIFT_DEBUG_TASK_*	Several task-debug toggles -- see EnvironmentVariables.def.

Frontend flags

A non-exhaustive list. The full list is in lib/Option/Options.td.

Flag	Effect
-typecheck	Type-check only; emit no IR or SIL.
-emit-module	Produce a .swiftmodule.
-emit-module-interface	Produce a .swiftinterface.
-emit-symbol-graph	Produce a symbol-graph JSON (used by DocC and similar).
-emit-pcm	Build a precompiled Clang module for use with this Swift module.
-import-objc-header <path>	Bridge a single Objective-C header.
-target <triple>	Cross-compile target.
-enable-experimental-feature Foo	Turn on an experimental feature gated in include/swift/Basic/Features.def.
-Xfrontend <flag>	Forward <flag> to the frontend (when using the driver).
-Xllvm <flag>	Forward <flag> to LLVM (e.g., -sil-print-after=...).
-debug-time-function-bodies	Print per-function type-check times.
-debug-constraints	Verbose constraint solver dump.
-stats-output-dir <dir>	Write frontend-stats.json.

Experimental features

Listed in include/swift/Basic/Features.def. Examples (subject to change):

• Embedded -- Embedded Swift mode.
• TypedThrows -- typed throws clauses.
• RegionBasedIsolation -- the actor-isolation upgrade.
• LifetimeDependence -- non-escapable types and lifetime annotations.

Enable with -enable-experimental-feature <name>. Ship-flagged features become language features after a Swift Evolution proposal.

Feature flags

The Features.def entries split into:

• Experimental -- behind -enable-experimental-feature.
• Upcoming -- behind -enable-upcoming-feature. These will become default in a future language mode.

Diagnostic IDs

Diagnostic identifiers live in include/swift/AST/Diagnostics{Common,Parse,Sema,SIL,IRGen,...}.def. Each entry has an ID, a category, a format string, and parameter types. Diagnostics are emitted via:

ctx.Diags.diagnose(loc, diag::my_diag_id, arg1, arg2);

The diag:: namespace is auto-generated from the .def files.

Build options

The most common build-script switches:

• --release / -R -- release-with-assertions build.
• --debug / -d -- debug build.
• --test -- run tests after build.
• --benchmark -- build benchmarks.
• --skip-build-osx, --skip-build-ios, ... -- limit which targets are built.
• --preset=<name> -- use a preset from utils/build-presets.ini.

Run ./utils/build-script --help for the full list.