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
Merge commit '3392287aace6beccd205a021c677abf7596526e6' into swift-3.0-branch
* commit '3392287aace6beccd205a021c677abf7596526e6': (83 commits)
Add a performance fixme to OutputByteStream
[Xcodeproj] conditionally add default linker path
Minor fixes (#644)
[Documenation] Document build configurations
[ModuleMapGenerator] Remove framework modulemap support
[Xcodeproj] Create symlink'ed dylibs for C frameworks
[Basic] Move Dictionary tuple initializer to Basic
[Workspace] Use filesystem API for reading file
Remove uses of private API (String._contiguousUTF8)
Eliminate arithmetic overflows in Version.hashValue
[DependencyResolver] Use `merging` for constraint container update.
[Xcodeproj] Fix Plist to write in deterministic order.
[DependencyResolver] Clean up constraint set subscripting of unassigned identifiers.
[Xcodeproj] Add a Plist enum
[PackageBuilder] Error on invalid manifest config
[Documentation] Document the manifest file
[Utility] Priortize pkgconfig env variable
[Utility] Use FileSystem APIs to in PkgConfig
Improve the error message that's shown when trying to access a package by a local path URL that doesn't refer to a repository.
[PackageBuilder] Fix test target ref in manifest for external packages
...
# Conflicts:
# Sources/Commands/SwiftTestTool.swift
*[Package Manifest File Format Reference](#package-manifest-file-format-reference)
12
+
*[Package](#package)
13
+
*[Package Dependency](#package-dependency)
14
+
*[Version](#version)
12
15
*[Customizing Builds](#customizing-builds)
16
+
*[Build Configurations](#build-configurations)
17
+
*[Debug](#debug)
18
+
*[Release](#release)
13
19
*[Depending on Apple Modules](#depending-on-apple-modules)
14
20
*[Resources](Resources.md)
15
21
@@ -61,72 +67,210 @@ Where `foo` is an executable and `bar.a` a static library.
61
67
62
68
## Package Manifest File Format Reference
63
69
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.
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.
65
71
66
-
Here's an example of a `Package.swift` file:
72
+
### Package
73
+
74
+
```swift
75
+
Package(
76
+
name: String,
77
+
pkgConfig: String?=nil,
78
+
providers: [SystemPackageProvider]?=nil,
79
+
targets: [Target] = [],
80
+
dependencies: [Dependency] = [],
81
+
exclude: [String] = []
82
+
)
83
+
```
84
+
85
+
\-[name](#name): The name of the package.
86
+
\-[pkgConfig](#pkgconfig): Name of the pkg-config (.pc) file to get the additional flags for system modules.
87
+
\-[providers](#providers): Defines hints to display for installing system modules.
88
+
\-[targets](#targets): Additional information on each target.
89
+
\-[dependencies](#dependencies): Declare dependencies on external packages.
90
+
\-[exclude](#exclude): Exclude files and directories from package sources.
91
+
92
+
### name
93
+
94
+
```swift
95
+
importPackageDescription
96
+
97
+
letpackage=Package(
98
+
name: "FooBar"
99
+
)
100
+
```
101
+
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.
103
+
104
+
### targets
105
+
106
+
Targets property is used when you have more than one module in your package and want to declare a dependency between them.
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`.
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.
121
+
122
+
Note: It is also possible to declare target dependencies between a test and regular module.
123
+
124
+
### dependencies
80
125
81
-
If your package contains multiple targets that depend on each other you will need to specify their interdependencies. Here is an example:
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.
The targets are named how your subdirectories are named.
141
+
See [Package Dependency](#package-dependency).
142
+
143
+
### exclude
144
+
145
+
Use this property to exclude files and directories from the package sources.
99
146
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
147
+
Every item specifies a relative path from the root of the package.
A package can require dependencies that are only needed during develop, as example for testing purposes. `testDependencies` are only fetched when you build current package. They are not fetched if a package is specified as a dependency in other package.
156
+
This is helpful when you want to place files like resources or fixtures that should not be considered by the convention system
157
+
as possible sources.
158
+
159
+
### pkgConfig
160
+
161
+
This property should only be used for System Module Packages. It defines the name of the pkg-config (.pc) file
162
+
that should be searched and read to get the additional flags like include search path, linker search path, system libraries
With a standard configuration file format like JSON such a feature would result in a dictionary structure with increasing complexity for every such feature.
138
282
283
+
### Build Configurations
284
+
285
+
SwiftPM allows two build configurations: Debug (default) and Release.
286
+
287
+
#### Debug
288
+
289
+
By default, running `swift build` will build in debug configuration. Alternatively, you can also use `swift build -c debug`. The build artifacts are located in directory called `debug` under build folder.
290
+
A Swift target is built with following flags in debug mode:
291
+
292
+
*`-Onone`: Compile without any optimization.
293
+
*`-g`: Generate debug information.
294
+
*`-enable-testing`: Enable Swift compiler's testability feature.
295
+
296
+
A C language target is build with following flags in debug mode:
297
+
298
+
*`-O0`: Compile without any optimization.
299
+
*`-g`: Generate debug information.
300
+
301
+
#### Release
302
+
303
+
To build in release mode, type: `swift build -c release`. The build artifacts are located in directory called `release` under build folder.
304
+
A Swift target is built with following flags in release mode:
305
+
306
+
*`-O`: Compile with optimizations.
307
+
*`-whole-module-optimization`: Optimize input files (per module) together instead of individually.
308
+
309
+
A C language target is build with following flags in release mode:
310
+
311
+
*`-O2`: Compile with optimizations.
312
+
139
313
### Depending on Apple Modules
140
314
141
315
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