diff --git a/Documentation/PackageDescriptionV3.md b/Documentation/PackageDescriptionV3.md deleted file mode 100644 index ee4a86fe3f6..00000000000 --- a/Documentation/PackageDescriptionV3.md +++ /dev/null @@ -1,383 +0,0 @@ -# PackageDescription API Version 3 - -⚠️ This version is no longer supported ⚠️ - ---- - -## Target Format Reference - -### Source Layouts - -The targets that `swift build` creates are determined from the filesystem -layout of your source files. - -For example, if you create a directory with the following layout: - - example/ - example/Sources/bar.swift - example/Sources/baz.swift - -This defines a single target, named after the package name from -`Package.swift`. - -To create multiple targets, create multiple subdirectories: - - example/Sources/Foo/Widget.swift - example/Sources/Bar/Bazzer.swift - -This defines two targets: `Foo` and `Bar`. - -To generate an executable target (instead of a library target), add a -`main.swift` file to that target’s directory: - - example/Sources/Foo/main.swift - -Running `swift build` will now produce an executable output file: `example/.build/debug/Foo`. - -The C language targets are laid out in a similar format. For e.g. a library -`Baz` can be created with following layout: - - example/Sources/Baz/Baz.c - example/Sources/Baz/include/Baz.h - -The public headers for this library go in the directory `include`. - -Similarly, an executable C language target `Baz` looks like this: - - example/Sources/Baz/main.c - -Note: It is possible to have C, C++, Objective-C and Objective-C++ sources as -part of a C language target. Swift targets can import C language targets but -not vice versa. - -Read more on C language targets [here](Usage.md#c-language-targets). - -### Test Target Layouts - -The package manager supports laying out test sources following a similar -convention as primary sources: - - example/Tests/FooTests/WidgetTests.swift - -This defines a `FooTests` test target. By convention, when there is a target -`Foo` and a matching test target `FooTests`, the package manager will establish -an implicit dependency between the test target and the target it assumes it is -trying to test. - -On Linux, the `XCTest` testing framework does not support dynamic discovery of -tests. Instead, packages which are intended for use on Linux should include an: - - example/Tests/LinuxMain.swift - -file which imports all of the individual test targets in the package, and then -invokes `XCTest.XCTMain` passing it the list of all tests. - -### Other Rules - -* `Tests` or any other subdirectory can be [excluded](#exclude) via Manifest - file. -* Subdirectories of a directory named `Sources`, `Source`, `srcs` or `src` in - the root directory become target. -* It is acceptable to have no `Sources` directory, in which case the root - directory is treated as a single target (place your sources there) or sub - directories of the root are considered targets. Use this layout convention - for simple projects. - ---- - -## Package Manifest File Format Reference - -Instructions for how to build a package are provided by the `Package.swift` -manifest file. `Package.swift` is a Swift file defining a single `Package` -object. This object is configured via the APIs defined in the -`PackageDescription` Swift target supplied with the Swift Package Manager. - -### Package Declaration - -Every `Package.swift` file should follow the following format: - -```swift -import PackageDescription - -/// The package description. -let package = Package(/* ... */) - -// ... subsequent package configuration APIs can be used here to further -// configure the package ... -``` - -Conceptually, the description defined by the `Package.swift` file is _combined_ -with the information on the package derived from the filesystem conventions -described previously. - -### Package - -```swift -Package( - name: String, - pkgConfig: String? = nil, - providers: [SystemPackageProvider]? = nil, - targets: [Target] = [], - dependencies: [Package.Dependency] = [], - swiftLanguageVersions: [Int]? = nil, - exclude: [String] = [] -) -``` - -\- [name](#name): The name of the package. -\- [pkgConfig](#pkgconfig): Name of the pkg-config (.pc) file to get the -additional flags for system modules. -\- [providers](#providers): Defines hints to display for installing system -modules. -\- [targets](#targets): Additional information on each target. -\- [dependencies](#dependencies): Declare dependencies on external packages. -\- [swiftLanguageVersions](#swiftlanguageversions): Specifies the set of -supported Swift language versions. -\- [exclude](#exclude): Exclude files and directories from package sources. - -Creates a new package instance. There should only be one package declared per -manifest. The parameters here supply the package description and are documented -in further detail below. - -#### name - -```swift -import PackageDescription - -let package = Package( - name: "FooBar" -) -``` - -This is the minimal requirement for a manifest to be valid. When the sources -are located directly under `Sources/` directory, there is only one target and -the target name will be the same as the package name. - -#### pkgConfig - -This property should only be used for System Module Packages. It defines the -name of the pkg-config (.pc) file that should be searched and read to get the -additional flags like include search path, linker search path, system libraries -to link etc. - -```swift -import PackageDescription - -let package = Package( - name: "CGtk3", - pkgConfig: "gtk+-3.0" -) -``` - -Here `gtk+-3.0.pc` will be searched in standard locations for the current -system. Users can provide their own paths for location of pc files using the -environment variable, `PKG_CONFIG_PATH`, which will be searched before the -standard locations. - -_NOTE: This feature does not require pkg-config to be installed. However, if -installed it will used to find additional platform specific pc file locations -which might be unknown to SwiftPM._ - -#### providers - -This property should only be used for system module packages. It can be used to -provide _hints_ for other users to install a System Module using -a system package manager like homebrew, apt-get etc. - -_NOTE: SwiftPM will *never* execute the command and only suggest the users to -run it._ - -```swift -import PackageDescription - -let package = Package( - name: "CGtk3", - pkgConfig: "gtk+-3.0", - providers: [ - .Brew("gtk+3"), - .Apt("gtk3") - ] -) -``` - -In this case if SwiftPM determines that GTK 3 package is not installed, it will -output an appropriate hint depending on which platform the user is on i.e. -macOS, Ubuntu, etc. - -#### targets - -The targets property is required when you have more than one target in your -package and need to declare a dependency between them. - -```swift -import PackageDescription - -let package = Package( - name: "Hello", - targets: [ - Target(name: "Bar", dependencies: ["Foo"]), - ] -) -``` - -The name identifies which target, the information is being associated with, and -the list of dependencies specifies the names of other targets in the same -package which must be built before that target. In the example here, `Foo` and -`Bar` are targets present under `Sources/` directory, and a dependency is being -establish on `Foo` from `Bar`. This will cause the `Foo` target to be built -before `Bar` target so that it can be imported: - -_NOTE: It is also possible to declare target dependencies between a test and -regular target._ - -#### dependencies - -This is the list of packages that the current package depends on and -information about the required versions. You can specify a URL (or local path) -to any valid Swift package. - -```swift -import PackageDescription - -let package = Package( - name: "Example", - dependencies: [ - .Package(url: "ssh://git@example.com/Greeter.git", versions: Version(1,0,0)..) -``` -\- *url*: URL or local path to a Package. -\- *versions*: The range of [versions](#version) which are required. - -```swift -.Package(url: String, versions: ClosedRange) -``` -\- *url*: URL or local path to a Package. -\- *versions*: The closed range of [versions](#version) which are required. - -```swift -.Package(url: String, majorVersion: Int) -``` -\- *url*: URL or local path to a Package. -\- *majorVersion*: The major version which is required. - -This is a short-hand form for specifying a range including all versions of a -major version, and is the recommended way for specifying a dependency following -the [semantic versioning](http://semver.org) standard. - -```swift -.Package(url: String, majorVersion: Int, minor: Int) -``` -\- *url*: URL or local path to a Package. -\- *majorVersion*: Major version to consider. -\- *minor*: Minor version to consider. - -As for the prior API, this is a short-hand form for specifying a range that -inclues all versions of a major and minor version. - -```swift -.Package(url: String, _ version: Version) -``` -\- *url*: URL or local path to a Package. -\- *version*: The exact [Version](#version) which is required. - -## Version - -A struct representing a [semantic version](http://semver.org). - -```swift -Version( - _ major: Int, - _ minor: Int, - _ patch: Int, - prereleaseIdentifiers: [String] = [], - buildMetadataIdentifier: String? = nil -) -``` - -\- *major*: The major version, incremented when you make incompatible API -changes. -\- *minor*: The minor version, incremented when you add functionality in a -backwards-compatible manner. -\- *patch*: The patch version, incremented when you make backwards-compatible -bug fixes. -\- *prereleaseIdentifiers*: Used to denote a pre-released version for eg: -alpha, beta, etc. -\- *buildMetadataIdentifier*: Optional build meta data for eg: timestamp, hash, -etc. - -A `Version` struct can be initialized using a string literal in following -format: - -``` "major.minor.patch[-prereleaseIdentifiers][+buildMetadata]" ``` - -where `prereleaseIdentifiers` and `buildMetadata` are optional. -_NOTE: prereleaseIdentifiers are separated by dot (.)._ - -### Customizing Builds - -Using Swift as the format for the manifest allows for powerful customization, -for example: - -```swift -import PackageDescription - -var package = Package(name: "Example") - -#if os(Linux) -let target = Target(name: "LinuxSources/foo") -package.targets.append(target) -#endif -``` diff --git a/Documentation/PackageDescriptionV4.md b/Documentation/PackageDescriptionV4.md deleted file mode 100644 index 20387c2299c..00000000000 --- a/Documentation/PackageDescriptionV4.md +++ /dev/null @@ -1,317 +0,0 @@ -# PackageDescription API Version 4 - -⚠️ This document is no longer maintained ⚠️ - -See [this](PackageDescription.md) document instead. - ---- - -## Target Format Reference - -All targets should be declared in the `Package.swift` manifest file. Unless the -relative path of the target is declared, the Package Manager will look for -a directory matching the name of the target in these places: - -Regular targets: Sources, Source, src, srcs. -Test targets: Tests, Sources, Source, src, srcs. - -## Package Manifest File Format Reference - -### Package - -```swift -Package( - name: String, - pkgConfig: String? = nil, - providers: [SystemPackageProvider]? = nil, - products: [Product] = [], - dependencies: [Dependency] = [], - targets: [Target] = [], - swiftLanguageVersions: [Int]? = nil -) -``` - -\- [name](#name): The name of the package. -\- [pkgConfig](#pkgconfig): Name of the pkg-config (.pc) file to get the -additional flags for system modules. -\- [providers](#providers): Defines hints to display for installing system -modules. -\- [products](#products): The products vended by the package. -\- [dependencies](#dependencies): The external package dependencies. -\- [targets](#targets): The list of targets in the package. -\- [swiftLanguageVersions](#swiftlanguageversions): Specifies the set of -supported Swift language versions. - -#### name - -```swift -import PackageDescription - -let package = Package( - name: "FooBar" -) -``` - -This is the minimal requirement for a manifest to be valid. However, at least -one target is required to build the package. - -#### pkgConfig - -This property should only be used for System Module Packages. It defines the -name of the pkg-config (.pc) file that should be searched and read to get the -additional flags like include search path, linker search path, system libraries -to link etc. - -```swift -import PackageDescription - -let package = Package( - name: "CGtk3", - pkgConfig: "gtk+-3.0" -) -``` - -Here `gtk+-3.0.pc` will be searched in standard locations for the current -system. Users can provide their own paths for location of pc files using the -environment variable, `PKG_CONFIG_PATH`, which will be searched before the -standard locations. - -_NOTE: This feature does not require pkg-config to be installed. However, if -installed it will be used to find additional platform specific pc file locations -which might be unknown to SwiftPM._ - -#### providers - -This property should only be used for system module packages. It can be used to -provide _hints_ for users to install a System Module using a system package -manager like homebrew, apt-get etc. - -_NOTE: SwiftPM will **never** execute the command, and only provide suggestions._ - -```swift -import PackageDescription - -let package = Package( - name: "CGtk3", - pkgConfig: "gtk+-3.0", - providers: [ - .brew(["gtk+3"]), - .apt(["gtk3"]) - ] -) -``` - -In this case if SwiftPM determines that GTK 3 package is not installed, it will -output an appropriate hint depending on which platform the user is on i.e. -macOS, Ubuntu, etc. - -#### products - -This is the list of all the products that are vended by the package. A target is -available to other packages only if it is a part of some product. - -Two types of products are supported: - -* library: A library product contains library targets. It should contain the - targets which are supposed to be used by other packages, i.e. the public API - of a library package. The library product can be declared static, dynamic - or automatic. It is recommended to use automatic so the Package Manager can - decide appropriate linkage. - -* executable: An executable product is used to vend an executable target. This - should only be used if the executable needs to be made available to - other packages. - -Example: - -```swift -let package = Package( - name: "Paper", - products: [ - .executable(name: "tool", targets: ["tool"]), - .library(name: "Paper", targets: ["Paper"]), - .library(name: "PaperStatic", type: .static, targets: ["Paper"]), - .library(name: "PaperDynamic", type: .dynamic, targets: ["Paper"]), - ], - dependencies: [ - .package(url: "http://github.com/SwiftyJSON/SwiftyJSON", from: "1.2.3"), - .package(url: "../CHTTPParser", .upToNextMinor(from: "2.2.0")), - .package(url: "http://some/other/lib", .exact("1.2.3")), - ], - targets: [ - .target( - name: "tool", - dependencies: [ - "Paper", - "SwiftyJSON" - ]), - .target( - name: "Paper", - dependencies: [ - "Basic", - .target(name: "Utility"), - .product(name: "CHTTPParser"), - ]) - ] -) -``` - -#### dependencies - -This is the list of packages that the package depends on. You can specify -a URL (or local path) to any valid Swift package. - -```swift -import PackageDescription - -let package = Package( - name: "Example", - dependencies: [ - .package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", from: "1.0.0"), - ], - targets: [ - .target(name: "Foo", dependencies: ["SwiftyJSON"]), - ] -) -``` - -A package dependency represents the location and the required version -information of an external dependency. The version range controls what versions -of a package dependency are expected to work with the current package. When the -package manager is fetching the complete set of packages required to build -a package, it considers all of the version range specifications from all of the -packages in order to select appropriate versions. - -The following options are available for declaring a package dependency: - -```swift - -// 1.0.0 ..< 2.0.0 -.package(url: "/SwiftyJSON", from: "1.0.0"), - -// 1.2.0 ..< 2.0.0 -.package(url: "/SwiftyJSON", from: "1.2.0"), - -// 1.5.8 ..< 2.0.0 -.package(url: "/SwiftyJSON", from: "1.5.8"), - -// 1.5.8 ..< 2.0.0 -.package(url: "/SwiftyJSON", .upToNextMajor(from: "1.5.8")), - -// 1.5.8 ..< 1.6.0 -.package(url: "/SwiftyJSON", .upToNextMinor(from: "1.5.8")), - -// 1.5.8 -.package(url: "/SwiftyJSON", .exact("1.5.8")), - -// Constraint to an arbitrary open range. -.package(url: "/SwiftyJSON", "1.2.3"..<"1.2.6"), - -// Constraint to an arbitrary closed range. -.package(url: "/SwiftyJSON", "1.2.3"..."1.2.8"), - -// Branch and revision. -.package(url: "/SwiftyJSON", .branch("develop")), -.package(url: "/SwiftyJSON", .revision("e74b07278b926c9ec6f9643455ea00d1ce04a021")) -``` - -#### targets - -The targets property is used to declare the targets in the package. - -```swift -import PackageDescription - -let package = Package( - name: "FooBar", - targets: [ - .target(name: "Foo", dependencies: []), - .testTarget(name: "Bar", dependencies: ["Foo"]), - ] -) -``` - -The above manifest declares two targets, `Foo` and `Bar`. `Bar` is a test target -which depends on `Foo`. The Package Manager will automatically search for the -targets inside package in the [predefined search paths](#target-format-reference). - -A target dependency can either be another target in the same package or a product -in one of its package dependencies. All target dependencies, internal or -external, must be explicitly declared. - -A target can be further customized with these properties: - -* path: This property defines the path to the top-level directory containing the -target's sources, relative to the package root. It is not legal for this path to -escape the package root, i.e., values like "../Foo", "/Foo" are invalid. The -default value of this property will be nil, which means the target will be -searched for in the pre-defined paths. The empty string ("") or dot (".") -implies that the target's sources are directly inside the package root. - -* exclude: This property can be used to exclude certain files and directories from -being picked up as sources. Exclude paths are relative to the target path. This -property has more precedence than sources property. - -* sources: This property defines the source files to be included in the target. -The default value of this property will be nil, which means all valid source -files found in the target's path will be included. This can contain directories -and individual source files. Directories will be searched recursively for valid -source files. Paths specified are relative to the target path. - -* publicHeadersPath: This property defines the path to the directory containing -public headers of a C target. This path is relative to the target path and -default value of this property is include. *Only valid for C family library -targets*. - -Note: It is an error if the paths of two targets overlap (unless resolved with -exclude). - -#### swiftLanguageVersions - -This property is used to specify the set of supported Swift language versions. - -The package manager will select the Swift language version that is most close to -(but not exceeding) the major version of the Swift compiler in use. It is an -error if a package does not support any version compatible with the current -compiler. For e.g. if Swift language version is set to `[3]`, both Swift 3 and -4 compilers will select '3', and if Swift language version is set to `[3, 4]`, -Swift 3 compiler will select '3' and Swift 4 compiler will select '4'. - -If a package does not specify any Swift language versions, the language version -to be used will match the major version of the package's [Swift tools -version](Usage.md#swift-tools-version). For e.g.: A Swift tools version with -a major version of '3' will imply a default Swift language version of '3', and -a Swift tools version with a major version of '4' will imply a default Swift -language version of '4'. - -## Version - -A struct representing a [semantic version](http://semver.org). - -```swift -Version( - _ major: Int, - _ minor: Int, - _ patch: Int, - prereleaseIdentifiers: [String] = [], - buildMetadataIdentifiers: [String] = [] -) -``` - -\- *major*: The major version, incremented when you make incompatible API -changes. -\- *minor*: The minor version, incremented when you add functionality in a -backwards-compatible manner. -\- *patch*: The patch version, incremented when you make backwards-compatible -bug fixes. -\- *prereleaseIdentifiers*: Used to denote a pre-release version; for example, -alpha, beta. -\- *buildMetadataIdentifiers*: Optional build metadata; for example, timestamp, hash. - -A `Version` struct can be initialized using a string literal in following -format: - -``` "major.minor.patch[-prereleaseIdentifiers][+buildMetadataIdentifiers]" ``` - -where `prereleaseIdentifiers` and `buildMetadataIdentifiers` are optional. -_NOTE: prereleaseIdentifiers and buildMetadataIdentifiers elements are separated by dot (.)._ diff --git a/Documentation/PackageDescriptionV4_2.md b/Documentation/PackageDescriptionV4_2.md deleted file mode 100644 index aa912d27aef..00000000000 --- a/Documentation/PackageDescriptionV4_2.md +++ /dev/null @@ -1,84 +0,0 @@ -# PackageDescription API Version 4.2 - -⚠️ This document is no longer maintained ⚠️ - -See [this](PackageDescription.md) document instead. - ---- - -The PackageDescription 4.2 contains one breaking and two additive changes to [PackageDescription API Version 4](PackageDescriptionV4.md). - -## Swift Language Version - -The `swiftLanguageVersions` takes an array of `SwiftVersion` enum: - -```swift -public enum SwiftVersion { - case v3 - case v4 - case v4_2 - case version(String) -} -``` - -Example usage: - -```swift -// swift-tools-version:4.2 - -import PackageDescription - -let package = Package( - name: "HTTPClient", - ... - swiftLanguageVersions: [.v4, .v4_2] -) -``` - -## Local Dependencies - -Local dependences are packages on disk that can be referred directly using their -paths. Local dependencies are only allowed in the root package and they override -all dependencies with same name in the package graph. Example declaration: - -```swift -import PackageDescription - -let package = Package( - name: "MyPackage", - dependencies: [ - .package(path: "../example-package-playingcard"), - ], - targets: [ - .target( - name: "MyPackage", - dependencies: ["PlayingCard"] - ), - ] -) -``` - -## System Library Targets - -System library targets supply the same metadata needed to adapt system libraries -to work with the package manager, but as a target. This allows packages to embed -these targets with the libraries that need them. - -```swift -// swift-tools-version:4.2 -import PackageDescription - -let package = Package( - name: "ZLib", - products: [ - .library(name: "ZLib", targets: ["ZLib"]), - ], - targets: [ - .systemLibrary( - name: "CZLib") - .target( - name: "ZLib", - dependencies: ["CZLib"]), - ] -) -``` diff --git a/Documentation/Usage.md b/Documentation/Usage.md index cdcfb89ab62..2367178a314 100644 --- a/Documentation/Usage.md +++ b/Documentation/Usage.md @@ -48,7 +48,7 @@ get started, create a directory and run `swift package init` command: This will create the directory structure needed for a library package with a target and the corresponding test target to write unit tests. A library package can contain multiple targets as explained in [Target Format -Reference](PackageDescriptionV4.md#target-format-reference). +Reference](PackageDescription.md#target). ### Create an executable package @@ -65,7 +65,7 @@ get started: This creates the directory structure needed for executable targets. Any target can be turned into a executable target if there is a `main.swift` present in its sources. Complete reference for layout is -[here](PackageDescriptionV4.md#target-format-reference). +[here](PackageDescription.md#target). ## Define Dependencies