Swift Package Manager (SwiftPM) — это инструмент для управления распространением кода Swift. Он интегрирован со средой построения Swift для автоматизации процесса скачивания, компиляции и компоновки зависимостей.

Управляющая программа пакетов включена в Swift 3.0 и выше.

Обзор концепции

В этом разделе описаны основные концепции, которые мотивируют функциональность Swift Package Manager.

Модули

Swift организует код в модули. Каждый модуль определяет пространство имён и навязывает контроль доступа к тем частям кода, которые могут использоваться за пределами модуля.

Программа может содержать весь свой код в одном модуле или импортировать другие модули в качестве зависимостей. Помимо нескольких системных модулей, таких как Darwin на macOS или Glibc на Linux, большинство зависимостей требуют загрузки и построения кода для использования.

Когда вы используете отдельный модуль для кода, решающего определённую задачу, этот код можно повторно использовать в других ситуациях. Например, модуль, предоставляющий функциональность для выполнения сетевых запросов, может быть использован как в приложении для обмена фотографиями, так и в приложении для прогноза погоды. Использование модулей позволяет вам использовать код других разработчиков вместо повторной реализации одной и той же функциональности.

Пакеты

Пакет состоит из файлов исходного кода Swift и файла манифеста. Файл манифеста, называемый Package.swift, определяет имя пакета и его содержимое, используя модуль PackageDescription.

Пакет имеет один или несколько целевых модулей. Каждый целевой модуль определяет продукт и может объявлять одну или несколько зависимостей.

Продукты

Целевой модуль может создавать либо библиотеку, либо исполняемый файл в качестве продукта. Библиотека содержит модуль, который можно импортировать в другой код Swift. Исполняемый файл — это программа, которую может запустить операционная система.

Зависимости

Зависимости целевого модуля — это модули, которые требуются кодом в пакете. Зависимость состоит из относительного или абсолютного URL-адреса источника пакета и набора требований к версии пакета, который может использоваться. Целью управляющей программы пакетов является снижение затрат на координацию путём автоматизации процесса загрузки и построения всех зависимостей для проекта. Это рекурсивный процесс: зависимость может иметь свои собственные зависимости, каждая из которых также может иметь зависимости, образуя граф зависимостей. Управляющая программа пакетов загружает и строит всё необходимое для удовлетворения всего графа зависимостей.

Примеры использования

В Начало работы с помощью Swift Package Manager создаётся простая утилита командной строки.

Для более полного представления возможностей Swift Package Manager следующий пример состоит из трёх взаимозависимых пакетов:

• PlayingCard — определяет типы PlayingCard, Suit и Rank.
• DeckOfPlayingCards — определяет тип Deck, который перемешивает и раздаёт массив значений PlayingCard.
• Dealer — определяет исполняемый файл, который создаёт DeckOfPlayingCards, перемешивает его и раздаёт первые 10 карт.

Вы можете собрать и запустить весь пример, скачав исходный код проекта Dealer с GitHub и выполнив следующие команды:

$ git clone https://github.com/apple/example-package-dealer.git
$ cd example-package-dealer
$ swift run dealer <count>

Создание пакета библиотеки

Начнём с создания целевого модуля, представляющего карту в стандартной колоде из 52 карт. Целевой модуль PlayingCard определяет тип PlayingCard, который состоит из значения перечисления Suit (Бубны, Червы, Крести, Пики) и значения перечисления Rank (Туз, Двойка, Тройка, …, Валет, Дама, Король).

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
}

По соглашению, целевой модуль включает все файлы исходного кода, расположенные в каталоге Sources/<target-name>.

example-package-playingcard
├── Sources
│   └── PlayingCard
│       ├── PlayingCard.swift
│       ├── Rank.swift
│       └── Suit.swift
└── Package.swift

Поскольку целевой модуль PlayingCard не генерирует исполняемый файл, его можно назвать библиотекой. Библиотека — это целевой модуль, который создаёт модуль, который может быть импортирован другими пакетами. По умолчанию модуль библиотеки раскрывает все типы и методы public, объявленные в исходном коде, расположенном в каталоге Sources/<target-name>.

При создании пакета библиотеки, предназначенного для использования в качестве зависимости в других проектах, файл манифеста Package.swift должен находиться в корневой папке структуры каталогов пакета.

Запустите swift build, чтобы начать процесс построения Swift. Если всё прошло успешно, он скомпилирует модуль Swift для PlayingCard.

Полный код пакета PlayingCard можно найти по адресу https://github.com/apple/example-package-playingcard.

Импортирование зависимостей

Пакет DeckOfPlayingCards подключает предыдущий пакет: он определяет тип Deck.

Для использования модуля PlayingCards пакет DeckOfPlayingCards должен объявить пакет в качестве зависимости в своём файле манифеста Package.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"]),
    ]
)

Каждая зависимость указывает URL-адрес источника и требования к версии. URL-адрес источника — это доступный для текущего пользователя URL-адрес, который разрешается в хранилище Git. Требования к версии, которые следуют соглашениям Семантической версификации (SemVer), используются для определения того, какую метку Git необходимо проверить и использовать для построения зависимости. Для зависимости PlayingCard будет использована последняя версия с главным номером, равным 3.

При выполнении команды swift build управляющая программа пакетов загружает все зависимости, компилирует их и связывает их с модулем пакета. Это позволяет DeckOfPlayingCards получить доступ к публичным членам своих зависимых модулей с помощью инструкций import.

Вы можете увидеть загруженные источники в каталоге .build/checkouts в корне вашего проекта, а промежуточные продукты построения — в каталоге .build в корне вашего проекта.

Полный код пакета DeckOfPlayingCards можно найти по адресу https://github.com/apple/example-package-deckofplayingcards.

Разрешение транзитивных зависимостей

При наличии всего остального, теперь можно построить модуль Dealer. Модуль Dealer зависит от пакета DeckOfPlayingCards, который, в свою очередь, зависит от пакета PlayingCard. Однако, поскольку Swift Package Manager автоматически разрешает транзитивные зависимости, вам нужно объявить только пакет DeckOfPlayingCards в качестве зависимости.

// 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 требует, чтобы файл исходного кода импортировал модули для всех типов, на которые ссылается код. Для файла Dealer модуля main.swift тип Deck из DeckOfPlayingCards и тип PlayingCard из PlayingCard ссылаются на эти типы.

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)
}

По соглашению, целевой модуль, содержащий файл, имя которого main.swift в его каталоге, генерирует исполняемый файл.

Выполнение команды swift build запускает систему построения Swift для создания исполняемого файла Dealer, который можно запустить из каталога .build/debug.

$ swift build
$ ./.build/debug/Dealer
♠︎6
♢K
♢2
♡8
♠︎7
♣︎10
♣︎5
♢A
♡Q
♡7

Полный код пакета Dealer можно найти по адресу https://github.com/apple/example-package-dealer.

Дополнительную информацию об использовании Swift Package Manager см. в документации, предоставленной в проекте Swift Package Manager на GitHub.