diff --git a/Sources/PackageDescription/PackageDependency.swift b/Sources/PackageDescription/PackageDependency.swift index a71e44dffbc..06cf9912343 100644 --- a/Sources/PackageDescription/PackageDependency.swift +++ b/Sources/PackageDescription/PackageDependency.swift @@ -201,7 +201,9 @@ extension Package { // MARK: - file system extension Package.Dependency { - /// Adds a dependency to a package located at the given path. + /// Adds a local dependency to a package located at the path you provide. + /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. /// /// The Swift Package Manager uses the package dependency as-is /// and does not perform any source control access. Local package dependencies @@ -217,7 +219,7 @@ extension Package.Dependency { return .init(name: nil, path: path, traits: nil) } - /// Adds a dependency to a package located at the given path. + /// Adds a local dependency to a package located at the path and with an optional set of traits you provide. /// /// The Swift Package Manager uses the package dependency as-is /// and does not perform any source control access. Local package dependencies @@ -225,7 +227,7 @@ extension Package.Dependency { /// on multiple tightly coupled packages. /// /// - Parameter path: The file system path to the package. - /// - Parameter traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - Parameter traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A package dependency. @available(_PackageDescription, introduced: 6.1) @@ -236,7 +238,9 @@ extension Package.Dependency { return .init(name: nil, path: path, traits: traits) } - /// Adds a dependency to a package located at the given path on the filesystem. + /// Adds a local dependency to a named package located at the path you provide. + /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. /// /// Swift Package Manager uses the package dependency as-is and doesn't perform any source /// control access. Local package dependencies are especially useful during @@ -256,7 +260,7 @@ extension Package.Dependency { return .init(name: name, path: path, traits: nil) } - /// Adds a dependency to a package located at the given path on the filesystem. + /// Adds a local dependency to a named package located at the path and with an optional set of traits you provide. /// /// Swift Package Manager uses the package dependency as-is and doesn't perform any source /// control access. Local package dependencies are especially useful during @@ -266,7 +270,7 @@ extension Package.Dependency { /// - Parameters: /// - name: The name of the Swift package. /// - path: The file system path to the package. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A package dependency. @available(_PackageDescription, introduced: 6.1) @@ -282,7 +286,7 @@ extension Package.Dependency { // MARK: - source control extension Package.Dependency { - /// Adds a package dependency that uses the version requirement, starting with the given minimum version, + /// Adds a remote package dependency with a version requirement, starting with the given minimum version, /// going up to the next major version. /// /// This is the recommended way to specify a remote package dependency. @@ -299,6 +303,8 @@ extension Package.Dependency { ///.package(url: "https://example.com/example-package.git", from: "1.2.3"), ///``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - version: The minimum version requirement. @@ -311,7 +317,7 @@ extension Package.Dependency { return .package(url: url, .upToNextMajor(from: version)) } - /// Adds a package dependency that uses the version requirement, starting with the given minimum version, + /// Adds a remote package dependency with a version requirement, starting with the given minimum version, /// going up to the next major version. /// /// This is the recommended way to specify a remote package dependency. @@ -331,7 +337,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - version: The minimum version requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -343,7 +349,7 @@ extension Package.Dependency { return .package(url: url, .upToNextMajor(from: version), traits: traits) } - /// Adds a package dependency that uses the version requirement, starting + /// Adds a remote package dependency with a version requirement, starting /// with the given minimum version, going up to the next major version. /// /// This is the recommended way to specify a remote package dependency. It @@ -378,12 +384,14 @@ extension Package.Dependency { return .package(name: name, url: url, .upToNextMajor(from: version)) } - /// Adds a remote package dependency given a branch requirement. + /// Adds a remote package dependency with a branch requirement you provide. /// ///```swift /// .package(url: "https://example.com/example-package.git", branch: "main"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - branch: A dependency requirement. See static methods on ``Requirement-swift.enum`` for available options. @@ -397,7 +405,7 @@ extension Package.Dependency { return .package(url: url, requirement: .branch(branch)) } - /// Adds a remote package dependency given a branch requirement. + /// Adds a remote package dependency with a branch requirement you provide. /// ///```swift /// .package(url: "https://example.com/example-package.git", branch: "main"), @@ -406,7 +414,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - branch: A dependency requirement. See static methods on ``Requirement-swift.enum`` for available options. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -418,7 +426,7 @@ extension Package.Dependency { return .package(url: url, requirement: .branch(branch), traits: traits) } - /// Adds a remote package dependency given a branch requirement. + /// Adds a remote package dependency with a branch requirement you provide. /// /// ```swift /// .package(url: "https://example.com/example-package.git", branch: "main"), @@ -439,12 +447,14 @@ extension Package.Dependency { return .package(name: name, url: url, requirement: .branch(branch)) } - /// Adds a remote package dependency given a revision requirement. + /// Adds a remote package dependency with a specific revision requirement. /// /// ```swift /// .package(url: "https://example.com/example-package.git", revision: "aa681bd6c61e22df0fd808044a886fc4a7ed3a65"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - revision: A dependency requirement. See static methods on ``Requirement-swift.enum`` for available options. @@ -458,7 +468,7 @@ extension Package.Dependency { return .package(url: url, requirement: .revision(revision)) } - /// Adds a remote package dependency given a revision requirement. + /// Adds a remote package dependency with a specific revision requirement. /// /// ```swift /// .package(url: "https://example.com/example-package.git", revision: "aa681bd6c61e22df0fd808044a886fc4a7ed3a65"), @@ -467,7 +477,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - revision: A dependency requirement. See static methods on ``Requirement-swift.enum`` for available options. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -479,7 +489,7 @@ extension Package.Dependency { return .package(url: url, requirement: .revision(revision), traits: traits) } - /// Adds a remote package dependency given a revision requirement. + /// Adds a remote package dependency with a specific revision requirement. /// /// ```swift /// .package(url: "https://example.com/example-package.git", revision: "aa681bd6c61e22df0fd808044a886fc4a7ed3a65"), @@ -500,7 +510,7 @@ extension Package.Dependency { return .package(name: name, url: url, requirement: .revision(revision)) } - /// Adds a package dependency starting with a specific minimum version, up to + /// Adds a remote package dependency starting with a specific minimum version, up to /// but not including a specified maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -510,6 +520,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", "1.2.3"..<"1.2.6"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The custom version range requirement. @@ -522,7 +534,7 @@ extension Package.Dependency { return .package(name: nil, url: url, requirement: .range(range)) } - /// Adds a package dependency starting with a specific minimum version, up to + /// Adds a remote package dependency starting with a specific minimum version, up to /// but not including a specified maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -535,7 +547,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The custom version range requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -547,7 +559,7 @@ extension Package.Dependency { return .package(name: nil, url: url, requirement: .range(range), traits: traits) } - /// Adds a package dependency starting with a specific minimum version, up to + /// Adds a remote package dependency starting with a specific minimum version, up to /// but not including a specified maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -557,6 +569,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", "1.2.3"..<"1.2.6"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - name: The name of the package, or `nil` to deduce it from the URL. /// - url: The valid Git URL of the package. @@ -572,7 +586,7 @@ extension Package.Dependency { return .package(name: name, url: url, requirement: .range(range)) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -582,6 +596,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The closed version range requirement. @@ -594,7 +610,7 @@ extension Package.Dependency { return .package(name: nil, url: url, closedRange: range) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -607,7 +623,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The closed version range requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -619,7 +635,7 @@ extension Package.Dependency { return .package(name: nil, url: url, closedRange: range, traits: traits) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -643,6 +659,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", .upToNextMinor(from: "1.0.0"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - name: The name of the package, or `nil` to deduce it from the URL. /// - url: The valid Git URL of the package. @@ -658,7 +676,7 @@ extension Package.Dependency { return .package(name: name, url: url, closedRange: range) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -668,6 +686,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - name: The name of the package, or `nil` to deduce it from the URL. /// - url: The valid Git URL of the package. @@ -688,7 +708,7 @@ extension Package.Dependency { return .package(name: name, url: url, requirement: .range(closedRange.lowerBound ..< upperBound)) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -702,7 +722,7 @@ extension Package.Dependency { /// - name: The name of the package, or `nil` to deduce it from the URL. /// - url: The valid Git URL of the package. /// - range: The closed version range requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. private static func package( @@ -727,7 +747,7 @@ extension Package.Dependency { ) } - /// Adds a package dependency that uses the exact version requirement. + /// Adds a remote package dependency that uses an exact version requirement. /// /// Specifying exact version requirements are not recommended as /// they can cause conflicts in your dependency graph when other packages depend on this package. @@ -740,6 +760,8 @@ extension Package.Dependency { /// .package(url: "https://example.com/example-package.git", exact: "1.2.3"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - url: The valid Git URL of the package. /// - version: The exact version of the dependency for this requirement. @@ -753,7 +775,7 @@ extension Package.Dependency { return .package(url: url, requirement: .exact(version)) } - /// Adds a package dependency that uses the exact version requirement. + /// Adds a remote package dependency that uses an exact version requirement. /// /// Specifying exact version requirements are not recommended as /// they can cause conflicts in your dependency graph when other packages depend on this package. @@ -769,7 +791,7 @@ extension Package.Dependency { /// - Parameters: /// - url: The valid Git URL of the package. /// - version: The exact version of the dependency for this requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -838,7 +860,7 @@ extension Package.Dependency { // MARK: - registry extension Package.Dependency { - /// Adds a package dependency that uses the version requirement, starting with the given minimum version, + /// Adds a remote package dependency that uses the version requirement, starting with the given minimum version, /// going up to the next major version. /// /// This is the recommended way to specify a remote package dependency. @@ -855,6 +877,8 @@ extension Package.Dependency { /// .package(id: "scope.name", from: "1.2.3"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - id: The identity of the package. /// - version: The minimum version requirement. @@ -868,7 +892,7 @@ extension Package.Dependency { return .package(id: id, .upToNextMajor(from: version)) } - /// Adds a package dependency that uses the version requirement, starting with the given minimum version, + /// Adds a remote package dependency that uses the version requirement, starting with the given minimum version, /// going up to the next major version. /// /// This is the recommended way to specify a remote package dependency. @@ -888,7 +912,7 @@ extension Package.Dependency { /// - Parameters: /// - id: The identity of the package. /// - version: The minimum version requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -900,7 +924,7 @@ extension Package.Dependency { return .package(id: id, .upToNextMajor(from: version), traits: traits) } - /// Adds a package dependency that uses the exact version requirement. + /// Adds a remote package dependency with an exact version requirement. /// /// Specifying exact version requirements are not recommended as /// they can cause conflicts in your dependency graph when multiple other packages depend on a package. @@ -913,6 +937,8 @@ extension Package.Dependency { /// .package(id: "scope.name", exact: "1.2.3"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - id: The identity of the package. /// - version: The exact version of the dependency for this requirement. @@ -926,7 +952,7 @@ extension Package.Dependency { return .package(id: id, requirement: .exact(version), traits: nil) } - /// Adds a package dependency that uses the exact version requirement. + /// Adds a remote package dependency with an exact version requirement. /// /// Specifying exact version requirements are not recommended as /// they can cause conflicts in your dependency graph when multiple other packages depend on a package. @@ -942,7 +968,7 @@ extension Package.Dependency { /// - Parameters: /// - id: The identity of the package. /// - version: The exact version of the dependency for this requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -954,7 +980,7 @@ extension Package.Dependency { return .package(id: id, requirement: .exact(version), traits: traits) } - /// Adds a package dependency starting with a specific minimum version, up to + /// Adds a remote package dependency starting with a specific minimum version, up to /// but not including a specified maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -978,6 +1004,8 @@ extension Package.Dependency { /// .package(id: "scope.name", .upToNextMinor(from: "1.0.0"), /// ``` /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. + /// /// - Parameters: /// - id: The identity of the package. /// - range: The custom version range requirement. @@ -991,7 +1019,7 @@ extension Package.Dependency { return .package(id: id, requirement: .range(range), traits: nil) } - /// Adds a package dependency starting with a specific minimum version, up to + /// Adds a remote package dependency starting with a specific minimum version, up to /// but not including a specified maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -1018,7 +1046,7 @@ extension Package.Dependency { /// - Parameters: /// - id: The identity of the package. /// - range: The custom version range requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) @@ -1030,7 +1058,7 @@ extension Package.Dependency { return .package(id: id, requirement: .range(range), traits: traits) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -1039,6 +1067,8 @@ extension Package.Dependency { /// ```swift /// .package(id: "scope.name", "1.2.3"..."1.2.6"), /// ``` + /// + /// If the package you depend on defines traits, the package manager uses the dependency with its default set of traits. /// /// - Parameters: /// - id: The identity of the package. @@ -1059,7 +1089,7 @@ extension Package.Dependency { return .package(id: id, range.lowerBound ..< upperBound) } - /// Adds a package dependency starting with a specific minimum version, going + /// Adds a remote package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// /// The following example allows the Swift Package Manager to pick @@ -1072,7 +1102,7 @@ extension Package.Dependency { /// - Parameters: /// - id: The identity of the package. /// - range: The closed version range requirement. - /// - traits: The trait configuration of this dependency. Defaults to enabling the default traits. + /// - traits: The trait configuration of this dependency. The default value enables the default traits of the package. /// /// - Returns: A `Package.Dependency` instance. @available(_PackageDescription, introduced: 6.1) diff --git a/Sources/PackageDescription/PackageDependencyTrait.swift b/Sources/PackageDescription/PackageDependencyTrait.swift index a35d3eefd26..188667da441 100644 --- a/Sources/PackageDescription/PackageDependencyTrait.swift +++ b/Sources/PackageDescription/PackageDependencyTrait.swift @@ -11,21 +11,22 @@ //===----------------------------------------------------------------------===// extension Package.Dependency { - /// A struct representing an enabled trait of a dependency. + /// An enabled trait of a dependency. @available(_PackageDescription, introduced: 6.1) public struct Trait: Hashable, Sendable, ExpressibleByStringLiteral { - /// Enables all default traits of a package. + /// Enables all default traits of the dependency. public static let defaults = Self.init(name: "default") - /// A condition that limits the application of a dependencies trait. + /// A condition that limits the application of a trait for a dependency. public struct Condition: Hashable, Sendable { - /// The set of traits of this package that enable the dependencie's trait. + /// The set of traits that enable the dependencies trait. let traits: Set? /// Creates a package dependency trait condition. /// - /// - Parameter traits: The set of traits that enable the dependencies trait. If any of the traits are enabled on this package - /// the dependencies trait will be enabled. + /// If the depending package enables any of the traits you provide, the package manager enables the dependency to which this condition applies. + /// + /// - Parameter traits: The set of traits that enable the dependencies trait. public static func when( traits: Set ) -> Self? { @@ -36,10 +37,10 @@ extension Package.Dependency { /// The name of the enabled trait. public var name: String - /// The condition under which the trait is enabled. + /// The condition under which the package manager enables the dependency. public var condition: Condition? - /// Initializes a new enabled trait. + /// Creates a new enabled trait. /// /// - Parameters: /// - name: The name of the enabled trait. @@ -52,11 +53,14 @@ extension Package.Dependency { self.condition = condition } + /// Creates a new enabled trait. + /// + /// - Parameter value: The name of the enabled trait. public init(stringLiteral value: StringLiteralType) { self.init(name: value) } - /// Initializes a new enabled trait. + /// Creates a new enabled trait. /// /// - Parameters: /// - name: The name of the enabled trait. diff --git a/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency-Trait.md b/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency-Trait.md new file mode 100644 index 00000000000..da40fbcedb0 --- /dev/null +++ b/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency-Trait.md @@ -0,0 +1,19 @@ +# ``PackageDescription/Package/Dependency/Trait`` + +## Topics + +### Declaring a Dependency Trait + +- ``trait(name:condition:)`` +- ``defaults`` + +### Creating a Dependency Trait + +- ``init(name:condition:)`` +- ``init(stringLiteral:)`` +- ``Condition`` + +### Inspecting a Dependency Trait + +- ``name`` +- ``condition`` diff --git a/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency.md b/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency.md index d400176b3e5..bf7eddaab71 100644 --- a/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency.md +++ b/Sources/PackageDescription/PackageDescription.docc/Curation/Dependency.md @@ -41,16 +41,12 @@ - ``Trait`` - ``RegistryRequirement`` - ``SourceControlRequirement`` -- ``requirement-swift.property`` -- ``Requirement-swift.enum`` ### Describing a Package Dependency - ``kind-swift.property`` - ``Kind`` - ``Version`` -- ``name`` -- ``url`` ### Deprecated methods @@ -63,3 +59,5 @@ - ``package(url:_:)-(_,Package.Dependency.Requirement)`` - ``name`` - ``url`` +- ``requirement-swift.property`` +- ``Requirement-swift.enum`` diff --git a/Sources/PackageDescription/PackageDescription.docc/Curation/Package.md b/Sources/PackageDescription/PackageDescription.docc/Curation/Package.md index a4e52b12a81..b92aa0e3e5a 100644 --- a/Sources/PackageDescription/PackageDescription.docc/Curation/Package.md +++ b/Sources/PackageDescription/PackageDescription.docc/Curation/Package.md @@ -6,11 +6,10 @@ - ``Package/init(name:defaultLocalization:platforms:pkgConfig:providers:products:dependencies:targets:swiftLanguageModes:cLanguageStandard:cxxLanguageStandard:)`` - ``Package/init(name:defaultLocalization:platforms:pkgConfig:providers:products:traits:dependencies:targets:swiftLanguageModes:cLanguageStandard:cxxLanguageStandard:)`` -- ``Package/init(name:defaultLocalization:platforms:pkgConfig:providers:products:dependencies:targets:swiftLanguageVersions:cLanguageStandard:cxxLanguageStandard:)`` - ``Package/init(name:platforms:pkgConfig:providers:products:dependencies:targets:swiftLanguageVersions:cLanguageStandard:cxxLanguageStandard:)`` - ``Package/init(name:pkgConfig:providers:products:dependencies:targets:swiftLanguageVersions:cLanguageStandard:cxxLanguageStandard:)-(_,_,_,_,_,_,[Int]?,_,_)`` - ``Package/init(name:pkgConfig:providers:products:dependencies:targets:swiftLanguageVersions:cLanguageStandard:cxxLanguageStandard:)-(_,_,_,_,_,_,[SwiftVersion]?,_,_)`` - +- ``Package/init(name:defaultLocalization:platforms:pkgConfig:providers:products:dependencies:targets:swiftLanguageVersions:cLanguageStandard:cxxLanguageStandard:)`` ### Naming the Package diff --git a/Sources/PackageDescription/PackageDescription.docc/Curation/Trait.md b/Sources/PackageDescription/PackageDescription.docc/Curation/Trait.md new file mode 100644 index 00000000000..b4677af9fc4 --- /dev/null +++ b/Sources/PackageDescription/PackageDescription.docc/Curation/Trait.md @@ -0,0 +1,20 @@ +# ``PackageDescription/Trait`` + +## Topics + +### Declaring Traits + +- ``trait(name:description:enabledTraits:)`` +- ``default(enabledTraits:)`` + +### Creating Traits + +- ``init(name:description:enabledTraits:)`` +- ``init(stringLiteral:)`` + +### Inspecting Traits + +- ``name`` +- ``description`` +- ``enabledTraits`` + diff --git a/Sources/PackageDescription/PackageDescription.swift b/Sources/PackageDescription/PackageDescription.swift index 88234087637..60e2d769583 100644 --- a/Sources/PackageDescription/PackageDescription.swift +++ b/Sources/PackageDescription/PackageDescription.swift @@ -97,7 +97,7 @@ public final class Package { /// The list of products that this package vends and that clients can use. public var products: [Product] - /// The set of traits of this package. + /// The set of traits this package provides. @available(_PackageDescription, introduced: 6.1) public var traits: Set @@ -344,7 +344,7 @@ public final class Package { /// `.pc` file to get the additional flags required for a system target. /// - providers: The package providers for a system target. /// - products: The list of products that this package makes available for clients to use. - /// - traits: The set of traits of this package. + /// - traits: The set of traits this package provides. /// - dependencies: The list of package dependencies. /// - targets: The list of targets that are part of this package. /// - swiftLanguageModes: The list of Swift language modes with which this package is compatible. diff --git a/Sources/PackageDescription/Trait.swift b/Sources/PackageDescription/Trait.swift index 449e0eaeaad..bb1ac1a6948 100644 --- a/Sources/PackageDescription/Trait.swift +++ b/Sources/PackageDescription/Trait.swift @@ -10,11 +10,50 @@ // //===----------------------------------------------------------------------===// -/// A struct representing a package's trait. +/// A package trait. /// -/// Traits can be used for expressing conditional compilation and optional dependencies. +/// A trait is a package feature that expresses conditional compilation and potentially optional dependencies. +/// It is typically used to expose additional or extended API for the package. /// -/// - Important: Traits must be strictly additive and enabling a trait **must not** remove API. +/// When you define a trait on a package, the package manager uses the name of that trait as a conditional block for the package's code. +/// Use the conditional block to enable imports or code paths for that trait. +/// For example, a trait with the canonical name `MyTrait` allows you to use the name as a conditional block: +/// +/// ```swift +/// #if MyTrait +/// // additional imports or APIs that MyTrait enables +/// #endif // MyTrait +/// ``` +/// +/// - Important: Traits must be strictly additive. Enabling a trait **must not** remove API. +/// +/// If your conditional code requires a dependency that you want to enable only when the trait is enabled, +/// add a conditional declaration to the target dependencies, +/// then include the import statement within the conditional block. +/// The following example illustrates enabling the dependency `MyDependency` when the trait `Trait1` is enabled: +/// +/// ```swift +/// targets: [ +/// .target( +/// name: "MyTarget", +/// dependencies: [ +/// .product( +/// name: "MyAPI", +/// package: "MyDependency", +/// condition: .when(traits: ["Trait1"]) +/// ) +/// ] +/// ), +/// ] +/// ``` +/// +/// Coordinate a declaration like the example above with code that imports the dependency in a conditional block: +/// +/// ```swift +/// #if Trait1 +/// import MyAPI +/// #endif // Trait1 +/// ``` @available(_PackageDescription, introduced: 6.1) public struct Trait: Hashable, ExpressibleByStringLiteral { /// Declares the default traits for this package. @@ -28,25 +67,26 @@ public struct Trait: Hashable, ExpressibleByStringLiteral { /// The trait's canonical name. /// - /// This is used when enabling the trait or when referring to it from other modifiers in the manifest. + /// Use the trait's name to enable the trait or when referring to it from other modifiers in the manifest. + /// The trait's name also defines the conditional block that the compiler supports when the trait is active. /// /// The following rules are enforced on trait names: /// - The first character must be a [Unicode XID start character](https://unicode.org/reports/tr31/#Figure_Code_Point_Categories_for_Identifier_Parsing) /// (most letters), a digit, or `_`. /// - Subsequent characters must be a [Unicode XID continue character](https://unicode.org/reports/tr31/#Figure_Code_Point_Categories_for_Identifier_Parsing) /// (a digit, `_`, or most letters), `-`, or `+`. - /// - `default` and `defaults` (in any letter casing combination) are not allowed as trait names to avoid confusion with default traits. + /// - The names `default` and `defaults` (in any letter casing combination) aren't allowed as trait names to avoid confusion with default traits. public var name: String /// The trait's description. /// - /// Use this to explain what functionality this trait enables. + /// Use the description to explain the additional functionality that the trait enables. public var description: String? /// A set of other traits of this package that this trait enables. public var enabledTraits: Set - /// Initializes a new trait. + /// Creates a trait with a name, a description, and set of additional traits it enables. /// /// - Parameters: /// - name: The trait's canonical name. @@ -62,11 +102,13 @@ public struct Trait: Hashable, ExpressibleByStringLiteral { self.enabledTraits = enabledTraits } + /// Creates a trait with the name you provide. + /// - Parameter value: The trait's canonical name. public init(stringLiteral value: StringLiteralType) { self.init(name: value) } - /// Initializes a new trait. + /// Creates a trait with a name, a description, and set of additional traits it enables. /// /// - Parameters: /// - name: The trait's canonical name. diff --git a/Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md b/Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md index 9a8bbc14164..b1a667a3ef8 100644 --- a/Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md +++ b/Sources/PackageManagerDocs/Documentation.docc/AddingDependencies.md @@ -1,6 +1,6 @@ # Adding dependencies to a Swift package -Use other swift packages, system libraries, or binary dependencies in your package. +Use other Swift packages, system libraries, or binary dependencies in your package. ## Overview @@ -8,7 +8,7 @@ To depend on another Swift package, define a dependency and the requirements for A remote dependency requires a location, represented by a URL, and a requirement on the versions the package manager may use. -The following example illustrates a package that depends on [PlayingCard](https://github.com/apple/example-package-playingcard), using `from` to require at least version `3.0.4`, and allow any other version up to the next major version that is available at the time of dependency resolution. +The following example illustrates a package that depends on [PlayingCard](https://github.com/apple/example-package-playingcard), using `from` to require at least version `4.0.0`, and allow any other version up to the next major version that is available at the time of dependency resolution. It then uses the product `PlayingCard` as a dependency for the target `MyPackage`: ```swift @@ -19,7 +19,7 @@ let package = Package( name: "MyPackage", dependencies: [ .package(url: "https://github.com/apple/example-package-playingcard.git", - from: "3.0.4"), + from: "4.0.0"), ], targets: [ .target( @@ -43,15 +43,52 @@ For more information on resolving package versions, see Note: tags for package versions should include all three components of a semantic version: major, minor, and patch. +> Note: tags for package versions should include all three components of a semantic version: major, minor, and patch. > Tags that only include one or two of those components are not interpreted as semantic versions. Use the version requirement when you declare the dependency to limit what the package manager can choose. The version requirement can be a range of possible semantic versions, a specific semantic version, a branch name, or a commit hash. -The API reference documentation for [Package.Dependency](https://developer.apple.com/documentation/packagedescription/package/dependency) defines the methods to use. +The API reference documentation for [Package.Dependency](https://docs.swift.org/swiftpm/documentation/packagedescription/package/dependency) defines the methods to use. + +### Packages with Traits + +Traits, introduced with Swift 6.1, allow packages to offer additional API that may include optional dependencies. +Packages should offer traits to provide API beyond the core of a package. +For example, a package may provide an experimental API, an optional API that requires additional dependencies, or functionality that isn't critical that a developer may want to enable only in specific circumstances. + +If a package offers traits and you depend on it without defining the traits to use, the package uses its default set of traits. +In the following example, the dependency `example-package-playingcard` uses its default traits, if it offers any: +```swift +dependencies: [ + .package(url: "https://github.com/swiftlang/example-package-playingcard", + from: "4.0.0") +] +``` + +To determine what traits a package offers, including its defaults, either inspect its `Package.swift` manifest or use to print out the resolved dependencies and their traits. + +Enabling a trait should only expand the API offered by a package. +If a package offers default traits, you can choose to not use those traits by declaring an empty set of traits when you declare the dependency. +The following example dependency declaration uses the dependency with no traits, even if the package normally provides a set of default traits to enable: + +```swift +dependencies: [ + .package(url: "https://github.com/swiftlang/example-package-playingcard", + from: "4.0.0", + traits: []) +] +``` + +Swift package manager determines the traits to enable using the entire graph of dependencies in a project. +The traits enabled for a dependency is the union of all of the traits that for packages that depend upon it. +For example, if you opt out of all traits, but a dependency you use uses the same package with some trait enabled, the package will use the depdendency with the requested traits enabled. + +> Note: By disabling any default traits, you may be removing available APIs from the dependency you use. + +To learn how to provide packages with traits, see . ### Local Dependencies @@ -77,6 +114,7 @@ For more information on creating a binary target, see [Creating a multiplatform ## Topics - +- - - - diff --git a/Sources/PackageManagerDocs/Documentation.docc/Dependencies/PackageTraits.md b/Sources/PackageManagerDocs/Documentation.docc/Dependencies/PackageTraits.md new file mode 100644 index 00000000000..0450fea8632 --- /dev/null +++ b/Sources/PackageManagerDocs/Documentation.docc/Dependencies/PackageTraits.md @@ -0,0 +1,141 @@ +# Provide configurable packages using traits. + +Define one or more traits to offer default and configurable features for a package. + +Swift packages prior to Swift 6.1 offered a non-configurable API surface for each version. +With Swift 6.1, packages may offer traits, which express a configurable API surface for a package. + +Use traits to enable additional API beyond the core API of the package. +For example, a trait may enable an experimental API, optional extended functionality that requires additional dependencies, or functionality that isn't critical that a developer may want to enable only in specific circumstances. + +> Note: Traits should never "remove" or disable public API when a trait is enabled. + +Within the package, traits express conditional compilation, and may be used to declare additional dependencies that are enabled when that trait is active. + +Traits are identified by their names, which are name-spaced within the package that hosts them. +Trait names must be [valid swift identifiers](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/lexicalstructure#Identifiers) with the addition of the characters of `-` and `+`. +The trait names `default` and `defaults` (regardless of any capitalization) aren't allowed to avoid confusion with the default traits that a package defines. + +Enabled traits are exposed as conditional blocks (for example, `#if YourTrait`) that you can use to conditionally enable imports or different compilation paths in code. + +## Overview + +### Declaring Traits + +Create a trait to define a discrete amount of additional functionality, and define it in the [traits](https://docs.swift.org/swiftpm/documentation/packagedescription/package/traits) property of the package manifest. +Use [`.default(enabledTraits:)`](https://docs.swift.org/swiftpm/documentation/packagedescription/trait/default(enabledtraits:)) to provide the set of traits that the package uses as a default. +If you don't define a default set of traits to enable, no traits are enabled by default. + +The following example illustrates a single trait, `FeatureA`, that is enabled by default: + +```swift +// ... +traits: [ + .trait(name: "FeatureA"), + .default(enabledTraits: ["FeatureA"]), +], +// ... +``` + +Traits may also be used to represent a set of other traits, which allows you to group features together. +The following example illustrates defining three traits, and an additional trait (`B-and-C`) that enables both traits `FeatureB` and `FeatureC`: + +```swift +// ... +traits: [ + .trait(name: "FeatureA"), + .trait(name: "FeatureB"), + .trait(name: "FeatureC"), + .trait(name: "B-and-C", enabledTraits: ["FeatureB", "FeatureC"]). + .default(enabledTraits: ["FeatureA"]), +], +// ... +``` + +The traits enabled by default for the example above is `FeatureA`. + +> Note: Changing the default set of traits for your package is a major semantic version change if it removes API surface. +> Adding additional traits is not a major version change. + +#### Mutually Exclusive Traits + +The package manifest format doesn't support declaring mutually exclusive traits. +In the rare case that you need to offer mutually exclusive traits, protect that scenario in code: + +```swift +#if FeatureA && FeatureC +#error("FeatureA and FeatureC are mutually exclusive") +#endif // FeatureA && FeatureC +``` + +> Note: Providing mutually exclusive traits can result in compilation errors when a developer enables the mutually exclusive traits. + +### Using traits in your code + +Use the name of a trait for conditional compilation. +Wrap the additional API surface for that trait within a conditional compilation block. +For example, if the trait `FeatureA` is defined and enabled, the compiler see and compile the function `additionalAPI()`: + +```swift +#if FeatureA +public func additionalAPI() { + // ... +} +#endif // FeatureA +``` + +### Using a trait to enable conditional dependencies + +You can use a trait to optionally include a dependency, or a dependency with specific traits enabled, to support the functionality you expose with a trait. +To do so, add the dependency you need to the manifest's `dependencies` declaration, +then use a conditional dependency for a trait or traits defined in the package to add that dependency to a target. + +The following example illustrates the relevant portions of a package manifest that defines a trait `FeatureB`, a local dependency that is used only when the trait is enabled: + +```swift +// ... +traits: [ + "FeatureB" + // this trait exists only within *this* package +], +dependencies: [ + .package( + path: "../some/local/path", + traits: ["DependencyFeatureTrait"] + // this enables the trait DependencyFeatureTrait on + // the local dependency at ../some/local/path. + ) +] +// ... +targets: [ + .target( + name: "MyTarget", + dependencies: [ + .product( + name: "MyAPI", + package: "MyDependency", + condition: .when(traits: ["FeatureB"]) + // if the FeatureB trait is enabled in *this* package, then + // the `MyAPI` product is included as a dependency for `MyTarget`. + ) + ] + ), +] +``` + +With the above example, the following code illustrates wrapping the import with the trait's conditional compilation, and later defines more API that uses the dependency: + +```swift +#if FeatureB + import MyAPI +#endif // FeatureB + +// ... + +#if FeatureB + public func additionalAPI() { + MyAPI.provideExtraFunctionality() + // ... + } +#endif // MyTrait +```