diff --git a/documentation/package-manager/_basic-usage.md b/documentation/package-manager/_basic-usage.md deleted file mode 100644 index 28f416b70..000000000 --- a/documentation/package-manager/_basic-usage.md +++ /dev/null @@ -1,217 +0,0 @@ -## Example Usage - -In [Getting Started](/getting-started/cli-swiftpm/), -a simple command-line tool is built with the Swift Package Manager. - -To provide a more complete look at what the Swift Package Manager can do, -the following example consists of three interdependent packages: - -* [PlayingCard][PlayingCard] - Defines `PlayingCard`, `Suit`, and `Rank` types. -* [DeckOfPlayingCards][DeckOfPlayingCards] - Defines a `Deck` type that shuffles and deals an array of `PlayingCard` values. -* [Dealer][Dealer] - Defines an executable that creates a `DeckOfPlayingCards`, shuffles it, and deals the first 10 cards. - -> You can build and run the complete example -> by downloading the source code of the [Dealer project from GitHub][Dealer] -> and running the following commands: -> -> ~~~ shell -> $ git clone https://github.com/apple/example-package-dealer.git -> $ cd example-package-dealer -> $ swift run dealer -> ~~~ - -### Creating a Library Package - -We'll start by creating a target representing -a playing card in a standard 52-card deck. -The `PlayingCard` target defines the `PlayingCard` type, -which consists of a `Suit` enumeration value (Clubs, Diamonds, Hearts, Spades) -and a `Rank` enumeration value (Ace, Two, Three, ..., Jack, Queen, King). - -~~~ swift -public enum Rank: Int { - case two = 2 - case three, four, five, six, seven, eight, nine, ten - case jack, queen, king, ace -} - -public enum Suit: String { - case spades, hearts, diamonds, clubs -} - -public struct PlayingCard { - let rank: Rank - let suit: Suit -} -~~~ - -By convention, a target includes any source files located in the `Sources/` directory. - -~~~ shell -example-package-playingcard -├── Sources -│   └── PlayingCard -│   ├── PlayingCard.swift -│   ├── Rank.swift -│   └── Suit.swift -└── Package.swift -~~~ - -Because the `PlayingCard` target does not produce an executable, -it can be described as a _library_. -A library is a target that builds a module which can be imported by other packages. -By default, a library module exposes all of the `public` types and methods -declared in source code located in the `Sources/` directory. - -When creating a library package intended for use as a dependency in other projects, -the `Package.swift` manifest must reside at the top level/root of the -package directory structure. - -Run `swift build` to start the Swift build process. -If everything worked correctly, -it will compile the Swift module for `PlayingCard`. - -> The complete code for the `PlayingCard` package can be found at -> . - -### Importing Dependencies - -The `DeckOfPlayingCards` package brings in the previous package: -It defines a `Deck` type. - -To use the `PlayingCards` module, the `DeckOfPlayingCards` package must declare -the package as a dependency in its `Package.swift` manifest file. - -~~~ swift -// swift-tools-version:5.3 -import PackageDescription - -let package = Package( - name: "DeckOfPlayingCards", - products: [ - .library(name: "DeckOfPlayingCards", targets: ["DeckOfPlayingCards"]), - ], - dependencies: [ - .package(url: "https://github.com/apple/example-package-playingcard.git", from: "3.0.0"), - ], - targets: [ - .target( - name: "DeckOfPlayingCards", - dependencies: ["PlayingCard"]), - .testTarget( - name: "DeckOfPlayingCardsTests", - dependencies: ["DeckOfPlayingCards"]), - ] -) -~~~ - -Each dependency specifies a source URL and version requirements. -The source URL is a URL accessible to the current user that resolves to a Git repository. -The version requirements, -which follow [Semantic Versioning (SemVer)](http://semver.org) conventions, -are used to determine which Git tag to check out and use to build the dependency. -For the `PlayingCard` dependency will use the most recent version with a major version equal to `3`. - -When the `swift build` command is run, -the Package Manager downloads all of the dependencies, -compiles them, -and links them to the package module. -This allows `DeckOfPlayingCards` -to access the public members of its dependent modules -with `import` statements. - -You can see the downloaded sources in the `.build/checkouts` directory at the root of your project, -and intermediate build products in the `.build` directory at the root of your project. - -> The complete code for the `DeckOfPlayingCards` package can be found at -> . - -### Resolving transitive dependencies - -With everything else in place, -now you can build the `Dealer` module. -The `Dealer` module depends on the `DeckOfPlayingCards` package, -which in turn depends on the `PlayingCard` package. -However, because the Swift Package Manager automatically resolves transitive dependencies, -you only need to declare the `DeckOfPlayingCards` package as a dependency. - -~~~ swift -// swift-tools-version:5.5 - -import PackageDescription - -let package = Package( - name: "dealer", - products: [ - .executable(name: "Dealer", targets: ["Dealer"]), - ], - dependencies: [ - .package(url: "https://github.com/apple/example-package-deckofplayingcards.git", from: "3.0.0"), - ], - targets: [ - .target( - name: "Dealer", - dependencies: ["DeckOfPlayingCards"]), - ] -) -~~~ - -Swift requires that a source file import the modules for any types -that are referenced in code. -For the `Dealer` module's `main.swift` file, -the `Deck` type from `DeckOfPlayingCards` -and the `PlayingCard` type from `PlayingCard` are referenced. - -~~~ swift -import DeckOfPlayingCards - -let numberOfCards = 10 - -var deck = Deck.standard52CardDeck() -deck.shuffle() - -for _ in 1...numberOfCards { - guard let card = deck.deal() else { - print("No More Cards!") - break - } - - print(card) -} -~~~ - -By convention, a target containing a file named `main.swift` in its directory -produces an executable. - -Running the `swift build` command -starts the Swift build system -to produce the `Dealer` executable, -which can be run from the `.build/debug` directory. - -~~~ shell -$ swift build -$ ./.build/debug/Dealer -♠︎6 -♢K -♢2 -♡8 -♠︎7 -♣︎10 -♣︎5 -♢A -♡Q -♡7 -~~~ - -> The complete code for the `Dealer` package can be found at -> . - -* * * - -For more information about using the Swift Package Manager, -see the documentation provided in the [Swift Package Manager project on GitHub](https://github.com/swiftlang/swift-package-manager). - - -[PlayingCard]: https://github.com/apple/example-package-playingcard -[DeckOfPlayingCards]: https://github.com/apple/example-package-deckofplayingcards -[Dealer]: https://github.com/apple/example-package-dealer diff --git a/documentation/package-manager/_conceptual-overview.md b/documentation/package-manager/_conceptual-overview.md deleted file mode 100644 index 08c36dbf4..000000000 --- a/documentation/package-manager/_conceptual-overview.md +++ /dev/null @@ -1,60 +0,0 @@ -## Conceptual Overview - -This section describes the basic concepts that motivate -the functionality of the Swift Package Manager. - -### Modules - -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 the 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 macOS -or Glibc on Linux, -most dependencies require code to be downloaded and built in order to be used. - -When you use a separate module for code that solves a particular problem, -that code can be reused in other situations. -For example, a module that provides functionality for making network requests -can be shared between a photo sharing app and a weather app. -Using modules lets you build on top of other developers' code -rather than reimplementing the same functionality yourself. - -### Packages - -A _package_ consists of Swift source files and a manifest file. -The manifest file, called `Package.swift`, -defines the package's name and its contents -using the `PackageDescription` module. - -{% comment %} - TODO: "You can find API documentation for the `PackageDescription` module here: ..." -{% endcomment %} - -A package has one or more targets. -Each target specifies a product -and may declare one or more dependencies. - -### Products - -A target may build either a library or an executable as its product. -A _library_ contains a module that can be imported by other Swift code. -An _executable_ is a program that can be run by the operating system. - -### Dependencies - -A target's dependencies are modules that are required by code in the package. -A dependency consists of a relative or absolute URL to the source of the package -and a set of requirements for the version of the package that can be used. -The role of the package manager is to reduce coordination costs -by automating the process of downloading and building all of the dependencies for a project. -This is a recursive process: -A dependency can have its own dependencies, -each of which can also have dependencies, -forming a dependency graph. -The package manager downloads and builds everything that is needed -to satisfy the entire dependency graph. diff --git a/documentation/package-manager/index.md b/documentation/package-manager/index.md index 602e53f9e..4943bf547 100644 --- a/documentation/package-manager/index.md +++ b/documentation/package-manager/index.md @@ -2,31 +2,10 @@ redirect_from: "/package-manager/" layout: page title: Package Manager +redirect_to: https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/ --- + + -The Swift Package Manager (SwiftPM) is a tool for managing the distribution of Swift code. -It's integrated with the Swift build system -to automate the process of downloading, compiling, and linking dependencies. - -The Package Manager is included in Swift 3.0 and above. - -{% include_relative _conceptual-overview.md %} - -* * * - -
-The following section assumes a working knowledge of Swift. -If you're new to the language, -you may want consult one of the introductory resources first. -We recommend [A Swift Tour][TSPL] in -_The Swift Programming Language_. - -If you want to follow along with the code examples, -you'll need to have a working installation of Swift. -You can find instructions for how to install Swift in -[Getting Started](/getting-started/#installing-swift). -
- -{% include_relative _basic-usage.md %} - -[TSPL]: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ +This page should redirect automatically to the updated location for +the [Swift Package Manager (SwiftPM) documentation](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/).