Skip to content

Commit d3f5975

Browse files
aciidghaciidgh
authored
Merge pull request #625 from aciidb0mb3r/manifest-docs
[Documentation] Document the manifest file
2 parents ee38fd2 + e6a0ac2 commit d3f5975

File tree

1 file changed

+170
-16
lines changed

1 file changed

+170
-16
lines changed

‎Documentation/Reference.md

Lines changed: 170 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99
* [Source Layouts](#source-layouts)
1010
* [Other Rules](#other-rules)
1111
* [Package Manifest File Format Reference](#package-manifest-file-format-reference)
12+
* [Package](#package)
13+
* [Package Dependency](#package-dependency)
14+
* [Version](#version)
1215
* [Customizing Builds](#customizing-builds)
1316
* [Depending on Apple Modules](#depending-on-apple-modules)
1417
* [Resources](Resources.md)
@@ -61,51 +64,202 @@ Where `foo` is an executable and `bar.a` a static library.
6164

6265
## Package Manifest File Format Reference
6366

64-
Instructions for how to build a package are provided by a manifest file, called `Package.swift`. You can customize this file to declare build targets or dependencies, include or exclude source files, and specify build configurations for the module or individual files.
67+
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. The Package is configured via the APIs used to form that object.
6568

66-
Here's an example of a `Package.swift` file:
69+
### Package
70+
71+
```swift
72+
Package(
73+
name: String,
74+
pkgConfig: String? = nil,
75+
providers: [SystemPackageProvider]? = nil,
76+
targets: [Target] = [],
77+
dependencies: [Dependency] = [],
78+
exclude: [String] = []
79+
)
80+
```
81+
82+
\- [name](#name): The name of the package.
83+
\- [pkgConfig](#pkgconfig): Name of the pkg-config (.pc) file to get the additional flags for system modules.
84+
\- [providers](#providers): Defines hints to display for installing system modules.
85+
\- [targets](#targets): Additional information on each target.
86+
\- [dependencies](#dependencies): Declare dependencies on external packages.
87+
\- [exclude](#exclude): Exclude files and directories from package sources.
88+
89+
### name
90+
91+
```swift
92+
import PackageDescription
93+
94+
let package = Package(
95+
name: "FooBar"
96+
)
97+
```
98+
99+
It is the minimal requirement for a manifest to be valid. When the sources are located directly under `Sources/` directory, there is only one module and the module name is same as the package name.
100+
101+
### targets
102+
103+
Targets property is used when you have more than one module in your package and want to declare a dependency between them.
67104

68105
```swift
69106
import PackageDescription
70107

71108
let package = Package(
72109
name: "Hello",
73-
dependencies: [
74-
.Package(url: "ssh://[email protected]/Greeter.git", versions: Version(1,0,0)..<Version(2,0,0)),
110+
targets: [
111+
Target(name: "TestSupport"),
112+
Target(name: "Bar", dependencies: ["Foo"]),
75113
]
76114
)
77115
```
78116

79-
A `Package.swift` file is a Swift file that declaratively configures a Package using types defined in the `PackageDescription` module. This manifest declares a dependency on an external package: `Greeter`.
117+
Here `Foo` and `Bar` are modules present under `Sources/` directory. `Foo` module will be built before `Bar` module and `Bar` can import `Foo` if `Foo` is a library.
118+
119+
Note: It is also possible to declare target dependencies between a test and regular module.
80120

81-
If your package contains multiple targets that depend on each other you will need to specify their interdependencies. Here is an example:
121+
### dependencies
122+
123+
This is the list of packages that the current package depends on. You can specify a URL (or local path) to any valid Swift package.
82124

83125
```swift
84126
import PackageDescription
85127

86128
let package = Package(
87129
name: "Example",
88-
targets: [
89-
Target(
90-
name: "top",
91-
dependencies: [.Target(name: "bottom")]),
92-
Target(
93-
name: "bottom")
130+
dependencies: [
131+
.Package(url: "ssh://[email protected]/Greeter.git", versions: Version(1,0,0)..<Version(2,0,0)),
132+
.Package(url: "../StringExtensions", "1.0.0"),
133+
.Package(url: "https://github.com/MyAwesomePackage", majorVersion: 1, minor: 4),
94134
]
95135
)
96136
```
97137

98-
The targets are named how your subdirectories are named.
138+
See [Package Dependency](#package-dependency).
139+
140+
### exclude
99141

100-
If you want to exclude some files and folders from Package, you can simple list them in the `exclude`. Every item specifies a relative folder path from the Root folder of the package
142+
Use this property to exclude files and directories from the package sources.
143+
144+
Every item specifies a relative path from the root of the package.
101145

102146
```swift
103147
let package = Package(
104-
name: "Example",
105-
exclude: ["tools", "docs", "Sources/libA/images"]
148+
name: "Foo",
149+
exclude: ["Sources/Fixtures", "Sources/readme.md", "Tests/FooTests/images"]
150+
)
151+
```
152+
153+
This is helpful when you want to place files like resources or fixtures that should not be considered by the convention system
154+
as possible sources.
155+
156+
### pkgConfig
157+
158+
This property should only be used for System Module Packages. It defines the name of the pkg-config (.pc) file
159+
that should be searched and read to get the additional flags like include search path, linker search path, system libraries
160+
to link etc.
161+
162+
```swift
163+
import PackageDescription
164+
165+
let package = Package(
166+
name: "CGtk3",
167+
pkgConfig: "gtk+-3.0"
168+
)
169+
```
170+
171+
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
172+
using the environment variable, `PKG_CONFIG_PATH`, which will be searched before the standard locations.
173+
174+
Note: This feature does not require pkg-config to be installed. However, if installed it will used to find additional platform specific pc file
175+
locations which might be unknown to SwiftPM.
176+
177+
### providers
178+
179+
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
180+
a system package manager like homebrew, apt-get etc.
181+
182+
Note: SwiftPM will *never* execute the command and only suggest the users to run it.
183+
184+
```swift
185+
import PackageDescription
186+
187+
let package = Package(
188+
name: "CGtk3",
189+
pkgConfig: "gtk+-3.0",
190+
providers: [
191+
.Brew("gtk+3"),
192+
.Apt("gtk3")
193+
]
106194
)
107195
```
108196

197+
In this case if SwiftPM determines that GTK 3 package is not installed, it will output an appropriate hint depending on which platform
198+
the user is on i.e. macOS, Ubuntu, etc.
199+
200+
### Package Dependency
201+
202+
Package Dependency represents location and Version range of an external dependency.
203+
204+
```swift
205+
Dependency.Package(url: String, versions: Range<Version>)
206+
```
207+
\- url: URL or local path to a Package.
208+
\- versions: A range of [Version](#version).
209+
210+
```swift
211+
Dependency.Package(url: String, versions: ClosedRange<Version>)
212+
```
213+
\- url: URL or local path to a Package.
214+
\- versions: A closed range of [Version](#version).
215+
216+
```swift
217+
Dependency.Package(url: String, majorVersion: Int)
218+
```
219+
\- url: URL or local path to a Package.
220+
\- majorVersion: Major version to consider. Latest available minor Version will be considered.
221+
222+
223+
```swift
224+
Dependency.Package(url: String, majorVersion: Int, minor: Int)
225+
```
226+
\- url: URL or local path to a Package.
227+
\- majorVersion: Major version to consider.
228+
\- minor: Minor version to consider.
229+
230+
```swift
231+
Dependency.Package(url: String, _ version: Version)
232+
```
233+
\- url: URL or local path to a Package.
234+
\- version: The specific [Version](#version) to consider.
235+
236+
### Version
237+
238+
A struct representing [Semantic Versioning](http://semver.org).
239+
240+
```swift
241+
Version(
242+
_ major: Int,
243+
_ minor: Int,
244+
_ patch: Int,
245+
prereleaseIdentifiers: [String] = [],
246+
buildMetadataIdentifier: String? = nil
247+
)
248+
```
249+
250+
\- major: The major version, incremented when you make incompatible API changes.
251+
\- minor: The minor version, incremented when you add functionality in a backwards-compatible manner.
252+
\- patch: The patch version, incremented when you make backwards-compatible bug fixes.
253+
\- prereleaseIdentifiers: Used to denote a pre-released version for eg: alpha, beta, etc.
254+
\- buildMetadataIdentifier: Optional build meta data for eg: timestamp, hash, etc.
255+
256+
Version can be initialized using a string literal in following format:
257+
258+
``` "major.minor.patch[-prereleaseIdentifiers][+buildMetadata]" ```
259+
260+
prereleaseIdentifiers and buildMetadata are optional.
261+
Note: prereleaseIdentifiers are separated by dot (.)
262+
109263
### Customizing Builds
110264

111265
That the manifest is Swift allows for powerful customization, for example:

0 commit comments

Comments
 (0)