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
+78-65Lines changed: 78 additions & 65 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)
@@ -24,35 +25,31 @@
24
25
25
26
The modules that `swift build` creates are determined from the filesystem layout of your source files.
26
27
27
-
For example, if you created a directory with the following layout:
28
+
For example, if you create a directory with the following layout:
28
29
29
30
example/
30
31
example/Sources/bar.swift
31
32
example/Sources/baz.swift
32
33
33
-
Running `swift build` within directory `example` would produce a single library target: `example/.build/debug/example.a`
34
+
this defines a single module (named after the package name from `Package.swift).
34
35
35
-
To create multiple modules create multiple subdirectories:
36
+
To create multiple modules, you can create multiple subdirectories:
36
37
37
38
example/Sources/foo/foo.swift
38
39
example/Sources/bar/bar.swift
39
40
40
-
Running `swift build` would produce two library targets:
41
-
42
-
*`example/.build/debug/foo.a`
43
-
*`example/.build/debug/bar.a`
41
+
which would define two modules, `foo` and `bar`.
44
42
45
43
To generate an executable module (instead of a library module) add a `main.swift` file to that module’s subdirectory:
46
44
47
45
example/Sources/foo/main.swift
48
46
example/Sources/bar/bar.swift
49
47
50
-
Running`swift build`would now produce:
48
+
and`swift build`will now produce the:
51
49
52
50
*`example/.build/debug/foo`
53
-
*`example/.build/debug/bar.a`
54
51
55
-
Where `foo` is an executable and `bar.a` a static library.
52
+
executable output file.
56
53
57
54
### Other Rules
58
55
@@ -64,17 +61,33 @@ Where `foo` is an executable and `bar.a` a static library.
64
61
65
62
## Package Manifest File Format Reference
66
63
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.
64
+
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.
65
+
66
+
### Package Declaration
67
+
68
+
Every `Package.swift` file should follow the following format:
69
+
70
+
```swift
71
+
importPackageDescription
72
+
73
+
/// The package description.
74
+
letpackage=Package(/* ... */)
75
+
76
+
// ... subsequent package configuration APIs can be used here to further
77
+
// configure the package ...
78
+
```
79
+
80
+
Conceptually, the description defined by the `Package.swift` file is _combined_ with the information on the package derived from the filesystem conventions described previously.
68
81
69
82
### Package
70
83
71
84
```swift
72
85
Package(
73
-
name: String,
74
-
pkgConfig: String?=nil,
75
-
providers: [SystemPackageProvider]?=nil,
76
-
targets: [Target] = [],
77
-
dependencies: [Dependency] = [],
86
+
name: String,
87
+
pkgConfig: String?=nil,
88
+
providers: [SystemPackageProvider]?=nil,
89
+
targets: [Target] = [],
90
+
dependencies: [Package.Dependency] = [],
78
91
exclude: [String] = []
79
92
)
80
93
```
@@ -86,7 +99,9 @@ Package(
86
99
\-[dependencies](#dependencies): Declare dependencies on external packages.
87
100
\-[exclude](#exclude): Exclude files and directories from package sources.
88
101
89
-
### name
102
+
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.
103
+
104
+
#### name
90
105
91
106
```swift
92
107
importPackageDescription
@@ -96,31 +111,30 @@ let package = Package(
96
111
)
97
112
```
98
113
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.
114
+
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.
100
115
101
-
### targets
116
+
####targets
102
117
103
-
Targets property is used when you have more than one module in your package and want to declare a dependency between them.
118
+
The targets property is required when you have more than one module in your package and need to declare a dependency between them.
104
119
105
120
```swift
106
121
importPackageDescription
107
122
108
123
letpackage=Package(
109
124
name: "Hello",
110
125
targets: [
111
-
Target(name: "TestSupport"),
112
126
Target(name: "Bar", dependencies: ["Foo"]),
113
127
]
114
128
)
115
129
```
116
130
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.
131
+
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:
118
132
119
-
Note: It is also possible to declare target dependencies between a test and regular module.
133
+
_NOTE: It is also possible to declare target dependencies between a test and regular module._
120
134
121
-
### dependencies
135
+
####dependencies
122
136
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.
137
+
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.
124
138
125
139
```swift
126
140
importPackageDescription
@@ -135,9 +149,9 @@ let package = Package(
135
149
)
136
150
```
137
151
138
-
See [Package Dependency](#package-dependency).
152
+
This is a list of `Package.Dependency` instances, see [Package Dependency](#package-dependency) for available options.
139
153
140
-
### exclude
154
+
####exclude
141
155
142
156
Use this property to exclude files and directories from the package sources.
143
157
@@ -153,7 +167,7 @@ let package = Package(
153
167
This is helpful when you want to place files like resources or fixtures that should not be considered by the convention system
154
168
as possible sources.
155
169
156
-
### pkgConfig
170
+
####pkgConfig
157
171
158
172
This property should only be used for System Module Packages. It defines the name of the pkg-config (.pc) file
159
173
that should be searched and read to get the additional flags like include search path, linker search path, system libraries
@@ -171,15 +185,14 @@ let package = Package(
171
185
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
186
using the environment variable, `PKG_CONFIG_PATH`, which will be searched before the standard locations.
173
187
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.
188
+
_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._
176
189
177
-
### providers
190
+
####providers
178
191
179
192
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
193
a system package manager like homebrew, apt-get etc.
181
194
182
-
Note: SwiftPM will *never* execute the command and only suggest the users to run it.
195
+
_NOTE: SwiftPM will *never* execute the command and only suggest the users to run it._
183
196
184
197
```swift
185
198
importPackageDescription
@@ -199,70 +212,72 @@ the user is on i.e. macOS, Ubuntu, etc.
199
212
200
213
### Package Dependency
201
214
202
-
Package Dependency represents location and Version range of an external dependency.
215
+
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.
232
+
\-*url*: URL or local path to a Package.
233
+
\-*majorVersion*: The major version which is required.
221
234
235
+
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.
261
-
Note: prereleaseIdentifiers are separated by dot (.)
276
+
where `prereleaseIdentifiers` and `buildMetadata` are optional. _NOTE: prereleaseIdentifiers are separated by dot (.)._
262
277
263
278
### Customizing Builds
264
279
265
-
That the manifest is Swift allows for powerful customization, for example:
280
+
Using Swift as the format for the manifest allows for powerful customization, for example:
266
281
267
282
```swift
268
283
importPackageDescription
@@ -280,5 +295,3 @@ With a standard configuration file format like JSON such a feature would result
280
295
### Depending on Apple Modules
281
296
282
297
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