Swift Settings in Package.swift: Compilation Flags Guide

The swiftSettings parameter in Package.swift lets you configure compilation behavior per target—platform-specific code, upcoming Swift features, and compiler flags.

Basic Structure

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyPackage",
    targets: [
        .target(
            name: "MyLibrary",
            swiftSettings: [
                .define("DEBUG_MODE", .when(configuration: .debug)),
                .enableUpcomingFeature("StrictConcurrency")
            ]
        )
    ]
)

Platform Conditionals

Use .define() with .when(platforms:) to create compile-time flags:

.target(
    name: "CrossPlatformLib",
    swiftSettings: [
        .define("IOS", .when(platforms: [.iOS])),
        .define("MACOS", .when(platforms: [.macOS])),
        .define("LINUX", .when(platforms: [.linux])),
        .define("WINDOWS", .when(platforms: [.windows]))
    ]
)

Then use in Swift code:

func platformName() -> String {
    #if IOS
    return "iOS"
    #elseif MACOS
    return "macOS"
    #elseif LINUX
    return "Linux"
    #else
    return "Unknown"
    #endif
}

Configuration-Based Flags

Define flags that only apply in debug or release builds:

swiftSettings: [
    .define("ENABLE_LOGGING", .when(configuration: .debug)),
    .define("ENABLE_ANALYTICS", .when(configuration: .release))
]

Usage:

func log(_ message: String) {
    #if ENABLE_LOGGING
    print("[DEBUG] \(message)")
    #endif
}

Upcoming Features

Enable Swift evolution features before they become default:

swiftSettings: [
    .enableUpcomingFeature("StrictConcurrency"),
    .enableUpcomingFeature("ExistentialAny"),
    .enableUpcomingFeature("BareSlashRegexLiterals"),
    .enableUpcomingFeature("InferSendableFromCaptures")
]

Check available features with:

swift build --help | grep -i upcoming

Memory Safety

Enforce strict memory safety checking:

swiftSettings: [
    .strictMemorySafety()
]

This enables additional compile-time checks for memory safety violations.

Unsafe Flags

Pass raw compiler flags (use sparingly):

swiftSettings: [
    .unsafeFlags(["-Xfrontend", "-warn-long-expression-type-checking=100"])
]

Warning: Targets using .unsafeFlags() cannot be used as dependencies by other packages.

Complete Example

// swift-tools-version: 6.0
import PackageDescription

let applePlatforms: [Platform] = [.iOS, .macOS, .tvOS, .watchOS, .visionOS]

let package = Package(
    name: "CrossPlatformKit",
    platforms: [.iOS(.v18), .macOS(.v15)],
    products: [
        .library(name: "CrossPlatformKit", targets: ["CrossPlatformKit"])
    ],
    targets: [
        .target(
            name: "CrossPlatformKit",
            swiftSettings: [
                // Platform detection
                .define("DARWIN", .when(platforms: applePlatforms)),
                .define("IOS", .when(platforms: [.iOS])),
                .define("LINUX", .when(platforms: [.linux])),

                // Configuration flags
                .define("DEBUG_MODE", .when(configuration: .debug)),

                // Swift 6 preparation
                .enableUpcomingFeature("StrictConcurrency")
            ]
        )
    ]
)

When to Use Each Setting

Setting	Use Case
.define()	Platform-specific code paths, debug toggles
.enableUpcomingFeature()	Adopt Swift evolution features early
.strictMemorySafety()	Enforce memory safety in Swift 6+
.unsafeFlags()	Debugging, diagnostics (not for distributed packages)

Important Notes

• Platform conditionals compile out unused code paths
• Upcoming features help migrate to new Swift versions incrementally
• .unsafeFlags() breaks package distribution—use only for local development
• Combine .when(platforms:) and .when(configuration:) for granular control