You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/Reference.md
+96-70Lines changed: 96 additions & 70 deletions
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,7 @@
9
9
*[Source Layouts](#source-layouts)
10
10
*[Other Rules](#other-rules)
11
11
*[Package Manifest File Format Reference](#package-manifest-file-format-reference)
12
+
*[Package Declaration](#package-declaration)
12
13
*[Package](#package)
13
14
*[Package Dependency](#package-dependency)
14
15
*[Version](#version)
@@ -27,57 +28,82 @@
27
28
28
29
The modules that `swift build` creates are determined from the filesystem layout of your source files.
29
30
30
-
For example, if you created a directory with the following layout:
31
+
For example, if you create a directory with the following layout:
31
32
32
33
example/
33
34
example/Sources/bar.swift
34
35
example/Sources/baz.swift
35
36
36
-
Running `swift build` within directory `example` would produce a single library target: `example/.build/debug/example.a`
37
+
this defines a single module (named after the package name from `Package.swift).
37
38
38
-
To create multiple modules create multiple subdirectories:
39
+
To create multiple modules, you can create multiple subdirectories:
39
40
40
-
example/Sources/foo/foo.swift
41
-
example/Sources/bar/bar.swift
41
+
example/Sources/Foo/Widget.swift
42
+
example/Sources/Bar/Bazzer.swift
42
43
43
-
Running `swift build` would produce two library targets:
44
-
45
-
*`example/.build/debug/foo.a`
46
-
*`example/.build/debug/bar.a`
44
+
which would define two modules, `Foo` and `Bar`.
47
45
48
46
To generate an executable module (instead of a library module) add a `main.swift` file to that module’s subdirectory:
49
47
50
48
example/Sources/foo/main.swift
51
-
example/Sources/bar/bar.swift
52
49
53
-
Running`swift build`would now produce:
50
+
and`swift build`will now produce an:
54
51
55
52
*`example/.build/debug/foo`
56
-
*`example/.build/debug/bar.a`
57
53
58
-
Where `foo` is an executable and `bar.a` a static library.
54
+
executable output file.
55
+
56
+
### Test Suite Layouts
57
+
58
+
The package manager supports laying out test sources following a similar convention as primary sources:
59
+
60
+
example/Tests/FooTests/WidgetTests.swift
61
+
62
+
defined a `FooTests` test suite. By convention, when there is a sources module `Foo` and a matching tests module `FooTests`, the package manager will establish an implicit dependency between the test suite and the target it assumes it is trying to test.
63
+
64
+
On Linux, the `XCTest` testing framework does not support dynamic discovery of tests. Instead, packages which are intended for use on Linux should include a:
65
+
66
+
example/Tests/LinuxMain.swift
67
+
68
+
file which imports all of the individual test suites in the package, and then invokes `XCTest.XCTMain` passing it the list of all tests.
59
69
60
70
### Other Rules
61
71
62
-
*Sub directories of directory named `Tests`become test-modules and are executed by `swift test`. `Tests`or any subdirectory can be excluded via Manifest file. The package manager will add an implicit dependency between the test suite and the target it assumes it is trying to test when the sub directory in `Tests` and package *name* are the same.
63
-
*Sub directories of a directory named `Sources`, `Source`, `srcs` or `src` become modules.
72
+
*`Tests` or any other subdirectory can be excluded via Manifest file. The package manager will add an implicit dependency between the test suite and the target it assumes it is trying to test when the sub directory in `Tests` and package *name* are the same.
73
+
*Subdirectories of a directory named `Sources`, `Source`, `srcs` or `src` become modules.
64
74
* It is acceptable to have no `Sources` directory, in which case the root directory is treated as a single module (place your sources there) or sub directories of the root are considered modules. Use this layout convention for simple projects.
65
75
66
76
---
67
77
68
78
## Package Manifest File Format Reference
69
79
70
-
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.
80
+
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 module supplied with the Swift Package Manager.
81
+
82
+
### Package Declaration
83
+
84
+
Every `Package.swift` file should follow the following format:
85
+
86
+
```swift
87
+
importPackageDescription
88
+
89
+
/// The package description.
90
+
letpackage=Package(/* ... */)
91
+
92
+
// ... subsequent package configuration APIs can be used here to further
93
+
// configure the package ...
94
+
```
95
+
96
+
Conceptually, the description defined by the `Package.swift` file is _combined_ with the information on the package derived from the filesystem conventions described previously.
71
97
72
98
### Package
73
99
74
100
```swift
75
101
Package(
76
-
name: String,
77
-
pkgConfig: String?=nil,
78
-
providers: [SystemPackageProvider]?=nil,
79
-
targets: [Target] = [],
80
-
dependencies: [Dependency] = [],
102
+
name: String,
103
+
pkgConfig: String?=nil,
104
+
providers: [SystemPackageProvider]?=nil,
105
+
targets: [Target] = [],
106
+
dependencies: [Package.Dependency] = [],
81
107
exclude: [String] = []
82
108
)
83
109
```
@@ -89,7 +115,9 @@ Package(
89
115
\-[dependencies](#dependencies): Declare dependencies on external packages.
90
116
\-[exclude](#exclude): Exclude files and directories from package sources.
91
117
92
-
### name
118
+
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.
119
+
120
+
#### name
93
121
94
122
```swift
95
123
importPackageDescription
@@ -99,31 +127,30 @@ let package = Package(
99
127
)
100
128
```
101
129
102
-
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.
130
+
This 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 will be the same as the package name.
103
131
104
-
### targets
132
+
####targets
105
133
106
-
Targets property is used when you have more than one module in your package and want to declare a dependency between them.
134
+
The targets property is required when you have more than one module in your package and need to declare a dependency between them.
107
135
108
136
```swift
109
137
importPackageDescription
110
138
111
139
letpackage=Package(
112
140
name: "Hello",
113
141
targets: [
114
-
Target(name: "TestSupport"),
115
142
Target(name: "Bar", dependencies: ["Foo"]),
116
143
]
117
144
)
118
145
```
119
146
120
-
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.
147
+
The name identifies which target (or module) 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 modules present under `Sources/` directory, and a dependency is being establish on `Foo` from `Bar`. This will cause the `Foo`module to be built before `Bar` module so that it can be imported:
121
148
122
-
Note: It is also possible to declare target dependencies between a test and regular module.
149
+
_NOTE: It is also possible to declare target dependencies between a test and regular module._
123
150
124
-
### dependencies
151
+
####dependencies
125
152
126
-
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.
153
+
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.
127
154
128
155
```swift
129
156
importPackageDescription
@@ -138,9 +165,9 @@ let package = Package(
138
165
)
139
166
```
140
167
141
-
See [Package Dependency](#package-dependency).
168
+
This is a list of `Package.Dependency` instances, see [Package Dependency](#package-dependency) for available options.
142
169
143
-
### exclude
170
+
####exclude
144
171
145
172
Use this property to exclude files and directories from the package sources.
146
173
@@ -156,7 +183,7 @@ let package = Package(
156
183
This is helpful when you want to place files like resources or fixtures that should not be considered by the convention system
157
184
as possible sources.
158
185
159
-
### pkgConfig
186
+
####pkgConfig
160
187
161
188
This property should only be used for System Module Packages. It defines the name of the pkg-config (.pc) file
162
189
that should be searched and read to get the additional flags like include search path, linker search path, system libraries
@@ -174,15 +201,14 @@ let package = Package(
174
201
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
175
202
using the environment variable, `PKG_CONFIG_PATH`, which will be searched before the standard locations.
176
203
177
-
Note: This feature does not require pkg-config to be installed. However, if installed it will used to find additional platform specific pc file
178
-
locations which might be unknown to SwiftPM.
204
+
_NOTE: This feature does not require pkg-config to be installed. However, if installed it will used to find additional platform specific pc filelocations which might be unknown to SwiftPM._
179
205
180
-
### providers
206
+
####providers
181
207
182
208
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
183
209
a system package manager like homebrew, apt-get etc.
184
210
185
-
Note: SwiftPM will *never* execute the command and only suggest the users to run it.
211
+
_NOTE: SwiftPM will *never* execute the command and only suggest the users to run it._
186
212
187
213
```swift
188
214
importPackageDescription
@@ -202,70 +228,72 @@ the user is on i.e. macOS, Ubuntu, etc.
202
228
203
229
### Package Dependency
204
230
205
-
Package Dependency represents location and Version range of an external dependency.
231
+
A `Package.Dependency` represents the location and and 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.
\- majorVersion: Major version to consider. Latest available minor Version will be considered.
248
+
\-*url*: URL or local path to a Package.
249
+
\-*majorVersion*: The major version which is required.
224
250
251
+
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.
prereleaseIdentifiers and buildMetadata are optional.
264
-
Note: prereleaseIdentifiers are separated by dot (.)
292
+
where `prereleaseIdentifiers` and `buildMetadata` are optional. _NOTE: prereleaseIdentifiers are separated by dot (.)._
265
293
266
294
### Customizing Builds
267
295
268
-
That the manifest is Swift allows for powerful customization, for example:
296
+
Using Swift as the format for the manifest allows for powerful customization, for example:
269
297
270
298
```swift
271
299
importPackageDescription
@@ -313,5 +341,3 @@ A C language target is build with following flags in release mode:
313
341
### Depending on Apple Modules
314
342
315
343
At this time there is no explicit support for depending on Foundation, AppKit, etc, though importing these modules should work if they are present in the proper system location. We will add explicit support for system dependencies in the future. Note that at this time the Package Manager has no support for iOS, watchOS, or tvOS platforms.
0 commit comments