The Swift Package Manager is a tool for managing distribution of source code, aimed at making it easy to share your code and reuse others’ code. The tool directly addresses the challenges of compiling and linking Swift packages, managing dependencies, versioning, and supporting flexible distribution and collaboration models.
We’ve designed the system to make it really easy to share packages on services like GitHub, but packages are also great for private personal development, sharing code within a team, or at any other granularity.
The Swift Package Manager is still in early design and development — we are aiming to have it stable and ready for use with Swift 3 but currently all details are subject to change and many important features are yet to be implemented.
Additionally, it is important to note that the Swift language syntax is not stable, so packages you write will (likely) break as Swift evolves.
The package manager is bundled with the developer snapshots available at swift.org. Please note the package manager does not come with the 2.2 release snapshots, ensure you download a developer snapshot.
If you want to verify you already have the package manager installed, enter the following in a terminal:
swift build --helpIf you get usage output, it is installed, otherwise you will see an error such as:
<unknown>:0: error: no such file or directory: 'build'
After installing a downloadable toolchain on OS X, by default you will probably see this error.
To execute the swift from your download you either need to put that swift first in your PATH,
or you need to set the TOOLCHAINS environment variable: see the next section.
The TOOLCHAINS environment variable on OS X can be used to control which
swift is instantiated:
$ xcrun --find swift
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift
$ swift --version
Apple Swift version 2.2
$ export TOOLCHAINS=swift
$ xcrun --find swift
/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swift
$ swift --version
Swift version 3.0-devOn OS X /usr/bin/swift is just a stub that forwards invocations to the active
toolchain. Thus when you call swift build it will use the swift defined by
your TOOLCHAINS enivonment variable.
To use a specific toolchain you can set TOOLCHAINS to the CFBundleIdentifier
in an .xctoolchain’s Info.plist.
Please note, this feature may by a little flakey with Xcode prior to 7.3.
The Package Manager is itself a Swift Package and thus can be used to build itself. However we recommend instead one of the three following options:
-
Using the Swift project
build-script:swift/utils/build-script --swiftpm --llbuild -
Independently with the bootstrap script:
-
Locate its
usr/bindirectory -
Run the bootstrap script:
swiftpm/Utilities/bootstrap --swiftc path/to/snapshot/usr/bin/swiftc --sbt path/to/snapshot/usr/bin/swift-build-tool
swiftc and swift-build-tool are both executables provided as part of Swift downloadable snapshots, they are not built from the sources in this repository.
- Using the Xcode Project in Support, this option requires:
- Xcode 7.3 (beta)
- llbuild cloned parallel to your SwiftPM clone
- Possibly, a more recent Swift snapshot
###Choosing Swift version
The SWIFT_EXEC environment variable specifies the swiftc executable path used by swift build. If it is not set, SPM will try to locate it:
- In
swift-build's parent directory. - (on OS X) by calling
xcrun --find swiftc - in PATH
There is further development-oriented documentation in Documentation/Internals.
The package manager’s system requirements are the same as those for Swift with the caveat that the package manager requires Git at runtime as well as build-time.
To learn about the policies and best practices that govern contributions to the Swift project, please read the Contributor Guide.
If you are interested in contributing, please read the Community Proposal, which provides some context for decisions made in the current implementation and offers direction for the development of future features.
Tests are an important part of the development and evolution of this project,
and new contributions are expected to include tests for any functionality
change. To run the tests, pass the test verb to the bootstrap script:
./Utilities/bootstrap test
Long-term, we intend for testing to be an integral part of the Package Manager itself and to not require custom support.
The Swift package manager uses llbuild as the underlying build system for compiling source files. It is also open source and part of the Swift project.
If you have any trouble with the package manager, help is available. We recommend:
- The swift-users mailing list
- Our bug tracker
If you’re not comfortable sharing your question with the list, contact details for the code owners can be found in CODE_OWNERS.txt; however, the mailing list is usually the best place to go for help.
A thorough guide to Swift and the Package Manager is available at swift.org. The following is technical documentation, describing the basic concepts that motivate the functionality of the Swift Package Manager.
Swift organizes code into modules. Each module specifies a namespace and enforces access controls on which parts of that code can be used outside of that module.
A program may have all of its code in a single module, or it may import other modules as dependencies. Aside from the handful of system-provided modules, such as Darwin on OS X or GLibc on Linux, most dependencies require code to be downloaded and built in order to be used.
Extracting code that solves a particular problem into a separate module allows for that code to be reused in other situations. For example, a module that provides functionality for making network requests could be shared between a photo sharing app and a program that displays the weather forecast. And if a new module comes along that does a better job, it can be swapped in easily, with minimal change. By embracing modularity, you can focus on the interesting aspects of the problem at hand, rather than getting bogged down solving problems you encounter along the way.
As a rule of thumb: more modules is probably better than fewer modules. The package manager is designed to make creating both packages and apps with multiple modules as easy as possible.
The Swift Package Manager and its build system needs to understand how to compile your source code. To do this, it uses a convention-based approach which uses the organization of your source code in the file system to determine what you mean, but allows you to fully override and customize these details. A simple example could be:
foo/Package.swift
foo/Sources/main.swift
Package.swiftis the manifest file that contains metadata about your package. For simple projects an empty file is OK, however the file must still exist.Package.swiftis documented in a later section.
If you then run the following command in the directory foo:
swift buildSwift will build a single executable called foo.
To the package manager, everything is a package, hence Package.swift. However
this does not mean you have to release your software to the wider world: you can
develop your app without ever publishing it in a place where others can see or
use. On the other hand, if one day you decide that your project should be
available to a wider audience your sources are already in a form ready to be
published. The package manager is also independent of specific forms of
distribution, so you can use it to share code within your personal projects,
within your workgroup, team or company, or with the world.
Of course, the package manager is used to build itself, so its own source files are laid out following these conventions as well.
Please note that currently we only build static libraries. In general this has benefits, however we understand the need for dynamic libraries and support for this will be added in due course.
Modern development is accelerated by the exponential use of external dependencies (for better and worse). This is great for allowing you to get more done with less time, but adding dependencies to a project has an associated coordination cost.
In addition to downloading and building the source code for a dependency, that dependency's own dependencies must be downloaded and built as well, and so on, until the entire dependency graph is satisfied. To complicate matters further, a dependency may specify version requirements, which may have to be reconciled with the version requirements of other modules with the same dependency.
The role of the package manager is to automate the process of downloading and building all of the dependencies for a project, and minimize the coordination costs associated with code reuse.
Dependencies are specified in your Package.swift manifest file.
Your platform comes with a wealth of rich and powerful C libraries installed via the system package manager. Your Swift code can use them.
Copyright 2015 - 2016 Apple Inc. and the Swift project authors. Licensed under Apache License v2.0 with Runtime Library Exception.
See https://swift.org/LICENSE.txt for license information.
See https://swift.org/CONTRIBUTORS.txt for Swift project authors.