Skip to content

[Do Not Merge] Update DocC documentation in the PackageDescription library. #4247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

[Do Not Merge] Update DocC documentation in the PackageDescription library. #4247

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e97dfc7
Update DocC documentation.
Mar 22, 2022
2e9fdb9
Merge branch 'main' into zkiraly/documentation-update
zkiraly Mar 22, 2022
e4d56e3
Removed blank line.
Mar 22, 2022
c6343ac
Changes in response to WowbaggersLiquidLunch's and abertelrud's comme…
Mar 29, 2022
60f00c7
Under `PackageDescription`, changed all instances (69 total) of U+201…
Mar 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Documentation/PackageDescription.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ Major versions tend to have more significant changes than minor
versions, and may require you to modify your code when they update.
The version rule requires Swift packages to conform to semantic
versioning. To learn more about the semantic versioning standard,
visit [semver.org](https://semver.org).
visit [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).

Selecting the version requirement is the recommended way to add a package dependency. It allows you to create a balance between restricting changes and obtaining improvements and features.

Expand Down Expand Up @@ -476,7 +476,7 @@ A package version is a three period-separated integer, for example `1.0.0`. It m
that your package behaves in a predictable manner once developers update their
package dependency to a newer version. To achieve predictability, the semantic versioning specification proposes a set of rules and
requirements that dictate how version numbers are assigned and incremented. To learn more about the semantic versioning specification, visit
[semver.org](www.semver.org).
[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).

**The Major Version**

Expand Down
174 changes: 83 additions & 91 deletions Sources/PackageDescription/BuildSettings.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,28 +28,31 @@ public struct BuildConfiguration: Encodable {
/// A condition that limits the application of a build setting.
///
/// By default, build settings are applicable for all platforms and build
/// configurations. Use the ``when(platforms:configuration:)`` modifier to define a build
/// setting for a specific condition. Invalid usage of `.when` emits an error during
/// manifest parsing. For example, it's invalid to specify a `.when` condition with
/// both parameters as `nil`.
/// configurations. Use the `.when` modifier to define a build setting for a
/// specific condition. Invalid usage of `.when` emits an error during manifest
/// parsing. For example, it's invalid to specify a `.when` condition with both
/// parameters as `nil`.
///
/// The following example shows how to use build setting conditions with various APIs:
/// The following example shows how to use build setting conditions with various
/// APIs:
///
/// ...
/// .target(
/// name: "MyTool",
/// dependencies: ["Utility"],
/// cSettings: [
/// .headerSearchPath("path/relative/to/my/target"),
/// .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)),
/// ],
/// swiftSettings: [
/// .define("ENABLE_SOMETHING", .when(configuration: .release)),
/// ],
/// linkerSettings: [
/// .linkedLibrary("openssl", .when(platforms: [.linux])),
/// ]
/// ),
/// ```swift
/// ...
/// .target(
/// name: "MyTool",
/// dependencies: ["Utility"],
/// cSettings: [
/// .headerSearchPath("path/relative/to/my/target"),
/// .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)),
/// ],
/// swiftSettings: [
/// .define("ENABLE_SOMETHING", .when(configuration: .release)),
/// ],
/// linkerSettings: [
/// .linkLibrary("openssl", .when(platforms: [.linux])),
/// ]
/// ),
/// ```
public struct BuildSettingCondition: Encodable {

private let platforms: [Platform]?
Expand Down Expand Up @@ -127,10 +130,8 @@ public struct CSetting: Encodable {
///
/// The path must be a directory inside the package.
///
/// - Since: First available in PackageDescription 5.0
///
/// - Parameters:
/// - path: The path of the directory that contains the headers. The path is relative to the target's directory.
/// - path: The path of the directory that contains the headers. The path is relative to the target's directory.
/// - condition: A condition that restricts the application of the build setting.
public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CSetting {
return CSetting(name: "headerSearchPath", value: [path], condition: condition)
Expand All @@ -140,12 +141,11 @@ public struct CSetting: Encodable {
///
/// If you don't specify a value, the macro's default value is 1.
///
/// - Since: First available in PackageDescription 5.0
///
/// - Parameters:
/// - name: The name of the macro.
/// - value: The value of the macro.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CSetting {
var settingValue = name
if let value = value {
Expand All @@ -154,22 +154,21 @@ public struct CSetting: Encodable {
return CSetting(name: "define", value: [settingValue], condition: condition)
}

/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
/// Sets unsafe flags to pass arbitrary command-line flags to the
/// corresponding build tool.
///
/// As the usage of the word "unsafe" implies, the Swift Package Manager
/// can't safely determine if the build flags have any negative
/// side effect on the build since certain flags can change the behavior of
/// how it performs a build.
/// As the usage of the word “unsafe” implies, Swift Package Manager can't safely determine
/// if the build flags have any negative side effect on the build since
/// certain flags can change the behavior of how it performs a build.
///
/// As some build flags can be exploited for unsupported or malicious
/// behavior, the use of unsafe flags make the products containing this
/// behavior, the use of unsafe flags makes the products containing this
/// target ineligible for use by other packages.
///
/// - Since: First available in PackageDescription 5.0
///
/// - Parameters:
/// - flags: The unsafe flags to set.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CSetting {
return CSetting(name: "unsafeFlags", value: flags, condition: condition)
}
Expand All @@ -182,7 +181,7 @@ public struct CXXSetting: Encodable {
private init(name: String, value: [String], condition: BuildSettingCondition?) {
self.data = BuildSettingData(name: name, value: value, condition: condition)
}

/// Provides a header search path relative to the target's directory.
///
/// Use this setting to add a search path for headers within your target.
Expand All @@ -191,10 +190,8 @@ public struct CXXSetting: Encodable {
///
/// The path must be a directory inside the package.
///
/// - Since: First available in PackageDescription 5.0
///
/// - Parameters:
/// - path: The path of the directory that contains the headers. The path is relative to the target's directory.
/// - path: The path of the directory that contains the headers. The path is
/// - condition: A condition that restricts the application of the build setting.
public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CXXSetting {
return CXXSetting(name: "headerSearchPath", value: [path], condition: condition)
Expand All @@ -204,12 +201,11 @@ public struct CXXSetting: Encodable {
///
/// If you don't specify a value, the macro's default value is 1.
///
/// - Since: First available in PackageDescription 5.0
///
/// - Parameters:
/// - name: The name of the macro.
/// - value: The value of the macro.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CXXSetting {
var settingValue = name
if let value = value {
Expand All @@ -218,21 +214,20 @@ public struct CXXSetting: Encodable {
return CXXSetting(name: "define", value: [settingValue], condition: condition)
}

/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
/// Sets unsafe flags to pass arbitrary command-line flags to the
/// corresponding build tool.
///
/// As the usage of the word "unsafe" implies, the Swift Package Manager
/// can't safely determine if the build flags have any negative
/// side effect on the build since certain flags can change the behavior of
/// how a build is performed.
/// As the usage of the word “unsafe” implies, Swift Package Manager can't safely determine
/// if the build flags have any negative side effect on the build since
/// certain flags can change the behavior of how it performs a build.
///
/// As some build flags can be exploited for unsupported or malicious
/// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
///
/// - Since: First available in PackageDescription 5.0
/// behavior, you can't use products with unsafe build flags as dependencies in another package.
///
/// - Parameters:
/// - flags: The unsafe flags to set.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CXXSetting {
return CXXSetting(name: "unsafeFlags", value: flags, condition: condition)
}
Expand All @@ -248,41 +243,42 @@ public struct SwiftSetting: Encodable {

/// Defines a compilation condition.
///
/// Use compilation conditions to only compile statements if a certain condition is true.
/// For example, the Swift compiler will only compile the
/// Use compilation conditions to only compile statements if a certain
/// condition is true. For example, the Swift compiler will only compile the
/// statements inside the `#if` block when `ENABLE_SOMETHING` is defined:
///
/// #if ENABLE_SOMETHING
/// ...
/// #endif
///
/// Unlike macros in C/C++, compilation conditions don't have an
/// associated value.
/// ```swift
/// #if ENABLE_SOMETHING
/// ...
/// #endif
/// ```
///
/// - Since: First available in PackageDescription 5.0
/// Unlike macros in C/C++, compilation conditions don't have an associated
/// value.
///
/// - Parameters:
/// - name: The name of the macro.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func define(_ name: String, _ condition: BuildSettingCondition? = nil) -> SwiftSetting {
return SwiftSetting(name: "define", value: [name], condition: condition)
}

/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
/// Set unsafe flags to pass arbitrary command-line flags to the
/// corresponding build tool.
///
/// As the usage of the word "unsafe" implies, the Swift Package Manager
/// can't safely determine if the build flags have any negative
/// side effect on the build since certain flags can change the behavior of
/// how a build is performed.
/// As the usage of the word “unsafe” implies, Swift Package Manager can't safely determine
/// if the build flags have any negative side effect on the build since
/// certain flags can change the behavior of how it performs a build.
///
/// As some build flags can be exploited for unsupported or malicious
/// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
///
/// - Since: First available in PackageDescription 5.0
/// behavior, the use of unsafe flags makes the products containing this
/// target ineligible for use by other packages.
///
/// - Parameters:
/// - flags: The unsafe flags to set.
/// - condition: A condition that restricts the application of the build setting..
/// - condition: A condition that restricts the application of the build
/// setting.
public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> SwiftSetting {
return SwiftSetting(name: "unsafeFlags", value: flags, condition: condition)
}
Expand All @@ -299,48 +295,44 @@ public struct LinkerSetting: Encodable {
/// Declares linkage to a system library.
///
/// This setting is most useful when the library can't be linked
/// automatically, such as C++ based libraries and non-modular
/// libraries.
///
/// - Since: First available in PackageDescription 5.0
/// automatically, such as C++ based libraries and non-modular libraries.
///
/// - Parameters:
/// - library: The library name.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func linkedLibrary(_ library: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
return LinkerSetting(name: "linkedLibrary", value: [library], condition: condition)
}

/// Declares linkage to a system framework.
///
/// This setting is most useful when the framework can't be linked
/// automatically, such as C++ based frameworks and non-modular
/// frameworks.
///
/// - Since: First available in PackageDescription 5.0
/// automatically, such as C++ based frameworks and non-modular frameworks.
///
/// - Parameters:
/// - framework: The framework name.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func linkedFramework(_ framework: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
return LinkerSetting(name: "linkedFramework", value: [framework], condition: condition)
}

/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.

/// Sets unsafe flags to pass arbitrary command-line flags to the
/// corresponding build tool.
///
/// As the usage of the word "unsafe" implies, the Swift Package Manager
/// can't safely determine if the build flags have any negative
/// side effect on the build since certain flags can change the behavior of
/// how a build is performed.
/// As the usage of the word “unsafe” implies, Swift Package Manager can't safely determine
/// if the build flags have any negative side effect on the build since
/// certain flags can change the behavior of how it performs a build.
///
/// As some build flags can be exploited for unsupported or malicious
/// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
///
/// - Since: First available in PackageDescription 5.0
/// behavior, the use of unsafe flags makes the products containing this
/// target ineligible for use by other packages.
///
/// - Parameters:
/// - flags: The unsafe flags to set.
/// - condition: A condition that restricts the application of the build setting.
/// - condition: A condition that restricts the application of the build
/// setting.
public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
return LinkerSetting(name: "unsafeFlags", value: flags, condition: condition)
}
Expand Down
8 changes: 5 additions & 3 deletions Sources/PackageDescription/Context.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,15 @@
//
//===----------------------------------------------------------------------===//

/// The context a Swift package is running in. This encapsulates states that are known at build-time.
/// For example where in the file system the current package resides.
/// The context information for a Swift package.
///
/// The context encapsulates states that are known when Swift Package Manager interprets the package manifest,
/// such as where in the file system the current package resides.
@available(_PackageDescription, introduced: 5.6)
public struct Context {
private static let model = try! ContextModel.decode()

/// The directory containing Package.swift.
/// The directory containing `Package.swift`.
public static var packageDirectory : String {
model.packageDirectory
}
Expand Down
Loading