Package traits

SwiftPM に package traits という新しい設定を導入します。パッケージ作者は Package.swift で「どんな trait を提供するか」を宣言し、利用者側は依存を書くときにどの trait を有効化するかを選べます。trait に応じてオプショナルな依存を引き込んだり、#if でコードを出し分けたりできるため、環境変数や別リポジトリ分割といった従来の回避策に頼らずに、条件付きコンパイルとオプショナル依存を素直に表現できます。

trait の宣言

trait は Package の traits: に列挙します。各 trait は名前を持ち、「この trait を有効化したときに一緒に有効になる他の trait」を enabledTraits で指定できます。.default(enabledTraits:) を使うと、デフォルトで有効になる trait の集合を宣言できます。

let package = Package(
    name: "Example",
    traits: [
        "Foo",
        .trait(
            name: "Bar",
            enabledTraits: [
                "Foo",
            ]
        ),
        .trait(
            name: "FooBar",
            enabledTraits: [
                "Foo",
                "Bar",
            ]
        ),
        .default(enabledTraits: ["Foo"]),
    ],
    // ...
)

trait 名は Swift の識別子として有効な文字（加えて - と +）で構成する必要があり、default / defaults は大文字小文字を問わず予約されています。また、パッケージあたりの trait 数は当面 300 個までに制限されます。

依存パッケージの trait を有効化する

依存パッケージを書くときに traits: を指定すると、その依存でどの trait を有効化するかを選べます。デフォルト trait を有効にしたい場合は .defaults を明示的に含めます。下の例は、デフォルト trait に加えて SomeTrait も有効化します。

dependencies: [
    .package(
        url: "https://github.com/Org/SomePackage.git",
        from: "1.0.0",
        traits: [
            .defaults,
            "SomeTrait",
        ]
    ),
]

traits: [] と空集合を渡すと、デフォルト trait も含めてすべて無効化できます。

dependencies: [
    .package(
        url: "https://github.com/Org/SomePackage.git",
        from: "1.0.0",
        traits: []
    ),
]

「自分のパッケージで Foo が有効なときだけ、依存側の SomeOtherTrait も有効にしたい」という条件付き有効化は .when(traits:) で表現します。

dependencies: [
    .package(
        url: "https://github.com/Org/SomePackage.git",
        from: "1.0.0",
        traits: [
            .trait(name: "SomeOtherTrait", condition: .when(traits: ["Foo"])),
        ]
    ),
]

ターゲット単位の条件付き依存

ターゲットが引く依存にも、trait による条件を付けられます。既存のプラットフォーム条件と同じ condition: を拡張する形で、次のように書けます。

targets: [
    .target(
        name: "SomeTarget",
        dependencies: [
            .product(
                name: "SomeProduct",
                package: "SomePackage",
                condition: .when(traits: ["Foo"])
            ),
        ]
    )
]

同じ .when(traits:) は SwiftSettings / CSettings / CXXSettings / LinkerSettings にも指定できるので、ビルド設定も trait で条件分岐できます。

ソース上での trait チェック

有効化されている trait は、コンパイラに define として渡されます。これにより、#if で trait 名を直接チェックできます。オプショナル依存の import を trait で囲ったり、同じ関数の実装を trait によって切り替えたりといった使い方ができます。

#if Foo
import SomeDependency
#endif

func hello() {
    #if Foo
    Foo.hello()
    #else
    print("Hello")
    #endif
}

trait の統合（unification）と additive 原則

依存解決が終わったあと、SwiftPM はグラフ全体を見て「各パッケージについて最終的にどの trait を有効化するか」を計算します。あるパッケージの trait の有効状態は、その依存元ごとにばらばらに指定されるため、SwiftPM はそれらの 和集合 を取ります。結果として、自分のパッケージに対して依存グラフのどこから有効化が飛んでくるかは予測できません。

このため、trait は additive、つまり「有効化したときに機能が増えるだけで、減らない」ように設計する必要があります。trait を有効化することで API を取り除くような変更は SemVer 非互換の破壊的変更になり得ます。どうしても排他的な trait が必要な場合は、ビルド時に #error で検知できるようにしておくのが推奨されます。

#if Trait1 && Trait2
#error("Trait1 and Trait2 are mutually exclusive")
#endif

同様に、デフォルト trait から既存の trait を外す変更も、これまで「デフォルト trait 経由で API を使っていた」側を壊す可能性があるため、SemVer 非互換として扱う必要があります。

trait 名は package ごとの名前空間

trait 名はパッケージごとに独立した名前空間を持ちます。異なるパッケージが同じ trait 名を使っても問題なく、むしろ依存元で同名 trait を条件付きで有効化する使い方はごく自然です。

コマンドライン

ルートパッケージに対して swift test / swift build / swift run を実行するときは、コマンドラインから trait を制御できます。

• --traits Trait1,Trait2: 指定した trait を有効化します。
• --enable-all-traits: すべての trait を有効化します。
• --disable-default-traits: デフォルト trait をすべて無効化します。

また、swift package dump-package の JSON 出力にも、パッケージと依存の trait 設定が含まれるようになります。

ドキュメント生成との関係

trait による条件付きコンパイルは、ドキュメント生成時にも影響します。symbol graph extractor は実際にコンパイルされたコードしか見られないため、すべての公開 API のドキュメントを出したいツールは、既定で「すべての trait を有効化してビルドする」構成を取るのが安全です。

既存パッケージへの影響

この機能は純粋な追加であり、既存パッケージの挙動は変わりません。ただし trait を導入する場合、既存の API を新しい trait の裏に移動してはいけません。利用者が「デフォルト trait をすべて無効化」して使っている可能性があるため、デフォルトで有効な trait に移したとしても破壊的変更になり得ます。trait は新規 API を opt-in で提供する用途で使うのが基本となります。