The Swift package deal manifest file

Subsequent it's important to import the PackageDescription framework with a view to outline your Swift package deal. This framework incorporates the package deal manifest construction as Swift objects.

import PackageDescription

That is it now you might be prepared to explain the package deal itself. Oh by the best way you'll be able to change the model of the used instruments, you'll be able to learn extra about this within the Bundle Supervisor utilization docs.

Bundle

A package deal is only a bunch of Swift (or different) information. The manifest file is the outline of what and tips on how to construct from these sources. Each single package deal ought to have a reputation, however this isn't sufficient to really generate one thing from it. You may solely have precisely one package deal definition contained in the file. That is the shortest and most ineffective one which you can create. 🙈

let package deal = Bundle(title: "myPackage")

The package deal title goes for use if you find yourself importing packages as dependencies, so title your pacages fastidiously. For those who select a reserved title by a system framework there will be points with linking. If there is a battle it's important to use static linking as a substitute of dynamic. For those who generate a undertaking by way of the swift package deal generate-xcodeproj command that undertaking will attempt to hyperlink every little thing dynamically, however if you happen to open the Bundle.swift file utilizing Xcode 11, the dependencies can be linked statically if this was not set explicitly within the product definition part.

Platform

A platform is principally an working system with a given model which you can assist.

let package deal = Bundle(
    title: "myPackage",
    platforms: [
        .iOS(.v13),         
        .macOS(.v10_15),    
        .tvOS(.v13),        
        .watchOS(.v6),      
    ]
)

Once you add a platform you might be placing a constraint on it by way of the required model. Each single dependency ought to match the requirement of the primary package deal platforms. Lengthy story brief if it is advisable to add assist for Apple platforms, you need to specify a platform flag with a supported model, in any other case SPM will use the oldest deployment goal based mostly on the put in SDK, aside from macOS, that is going to be v10_10. Each package deal has Linux assist by default, you'll be able to't add such restrictions but, however perhaps it will change within the close to future, additionally Home windows is coming.

Product

A package deal can have a number of closing merchandise (construct artifacts). At present there are two varieties of construct merchandise: executables and libraries. The executable is a binary that may be executed, for instance this is usually a command line utility. A library is one thing that others can use, it's principally the general public API product illustration in your targets.

import PackageDescription

let package deal = Bundle(title: "myPackage", merchandise: [
    .library(name: "myPackageLib", targets: ["myPackageLib"]),
    .library(title: "myPackageStaticLib", kind: .static, targets: ["myPackageLib"]),
    .library(title: "myPackageDynLib", kind: .dynamic, targets: ["myPackageLib"]),
    .executable(title: "myPackageCli", targets: ["myPackage"])
], targets: [
    .target(name: "myPackageLib"),
    .target(name: "myPackageCli"),
])

If the library kind is unspecified, the Bundle Supervisor will mechanically select it based mostly on the consumer's choice. As I discussed this earlier generated Xcode tasks want dynamic linking, however if you happen to merely open the manifest file the app can be statically linked.

Dependency

Packages can depend on different packages. You may outline your dependencies by specifying a neighborhood path or a repository URL with a given model tag. Including a dependency into this part shouldn't be sufficient to make use of it in your targets. You even have so as to add the product offered by the package deal on the goal degree.

let package deal = Bundle(
    title: "myPackage",
    dependencies: [
        .package(path: "/local/path/to/myOtherPackage"),
        .package(url: "<git-repository-url>", from: "1.0.0"),
        .package(url: "<git-repository-url>", .branch("dev")),
        .package(url: "<git-repository-url>", .exact("1.3.2")),
        .package(url: "<git-repository-url>", .revision("<hash>")),
        .package(url: "<git-repository-url>", .upToNextMajor(from: "1.0.0")),
        .package(url: "<git-repository-url>", .upToNextMinor(from: "1.0.0")),
        .package(url: "<git-repository-url>", "1.0.0"..<"1.3.0"),
    ]
)

The URL is usually a GitHub URL, luckily you'll be able to add non-public repositories as effectively by utilizing an ssh key based mostly authentication. Simply use the [email protected]:BinaryBirds/viper-kit.git URL format, as a substitute of the HTTP based mostly, if you wish to add non-public packages. 🤫

Goal

A goal is one thing which you can construct, in different phrases it is a construct goal that may end up in a library or an executable. You need to have at the least one goal in your undertaking file in any other case you'll be able to't construct something. A goal ought to at all times have a reputation, each different settings is elective.

Settings

There are various settings that you need to use to configure your goal. Targets can rely upon different targets or merchandise outlined in exterior packages. A goal can have a customized location, you'll be able to specify this by setting the trail attribute. Additionally you'll be able to exclude supply information from the goal or explicitly outline the sources you wish to use. Targets can have their very own public headers path and you'll present construct settings each for the C, C++ and the Swift language, and compiler flags.

.goal(title: "myPackage",
        dependencies: [
            .target(name: "other"),
            .product(name: "package", package: "package-kit")
        ],
        path: "./Sources/myPackage",
        exclude: ["foo.swift"],
        sources: ["main.swift"],
        publicHeadersPath: "./Sources/myPackage/headers",
        cSettings: [
            .define("DEBUG"),
            .define("DEBUG", .when(platforms: [.iOS, .macOS, .tvOS, .watchOS], configuration: .debug)),
            .outline("DEBUG", to: "yes-please", .when(platforms: [.iOS], configuration: .debug)),
            .headerSearchPath(""),
            .headerSearchPath("", .when(platforms: [.android, .linux, .windows], configuration: .launch)),
            .unsafeFlags(["-D EXAMPLE"]),
            .unsafeFlags(["-D EXAMPLE"], .when(platforms: [.iOS], configuration: .debug)),
        ],
        cxxSettings: [
            
        ],
        swiftSettings: [
            .define("DEBUG"),
            .define("DEBUG", .when(platforms: [.iOS, .macOS, .tvOS, .watchOS], configuration: .debug)),
            .unsafeFlags(["-D EXAMPLE"]),
            .unsafeFlags(["-D EXAMPLE"], .when(platforms: [.iOS], configuration: .debug)),
        ],
        linkerSettings: [
            .linkedFramework("framework"),
            .linkedLibrary("framework", .when(platforms: [.iOS], configuration: .debug)),
            .linkedLibrary("library"),
            .linkedLibrary("library", .when(platforms: [.macOS], configuration: .launch)),
            .unsafeFlags(["-L example"]),
            .unsafeFlags(["-L example"], .when(platforms: [.linux], configuration: .launch)),
        ]),

As you'll be able to see you'll be able to outline preprocessor macros for each single language. You need to use the secure circumstances for fundamental stuff, however there's an unsafeFlags case for the reckless ones. The good factor is which you can assist a platform situation filter together with construct configuration to each single settings because the final param.

Obtainable platforms are:

• .iOS
• .macOS
• .watchOS
• .tvOS
• .android
• .linux
• .home windows

The construct configuration will be .debug or .launch

Check targets

Check targets are used to outline take a look at suites. They can be utilized to unit take a look at different targets utilizing the XCTest framework. They appear to be precisely the identical as common targets.

.testTarget(title: String,
    dependencies: [Target.Dependency],
    path: String?,
    exclude: [String],
    sources: [String]?,
    cSettings: [CSetting]?,
    cxxSettings: [CXXSetting]?,
    swiftSettings: [SwiftSetting]?,
    linkerSettings: [LinkerSetting]?)

I feel the one distinction between a goal and a take a look at goal is which you can run a take a look at goal utilizing the swift take a look at command, however from a structural standpoint, they're principally the identical.

Bundle configs and system libraries

You may wrap an present system library utilizing Swift, the great thing about that is that you need to use packages written in C, CPP or different languages. I will present you a fast instance by means of the superb Kanna(鉋) - XML/HTML parser repository. I am utilizing this instrument so much, thanks for making it Atsushi Kiwaki. 🙏

#if swift(>=5.2) && !os(Linux)
let pkgConfig: String? = nil
#else
let pkgConfig = "libxml-2.0"
#endif

#if swift(>=5.2)
let suppliers: [SystemPackageProvider] = [
    .apt(["libxml2-dev"])
]
#else
let suppliers: [SystemPackageProvider] = [
    .apt(["libxml2-dev"]),
    .brew(["libxml2"])
]
#endif

let package deal = Bundle(title: "Kanna",
pkgConfig: "",
suppliers: [
  .apt(["libsqlite-dev"]),
  .brew(["sqlite3"])
],
merchandise: [
  .library(name: "Kanna", targets: ["Kanna"])
],
targets: [
.target(name: "myPackage"),
.systemLibrary(name: "libxml2",
               path: "Modules",
               pkgConfig: pkgConfig,
               providers: providers)
])

There's a module definition file on the Modules listing. You will want a module.modulemap file to export a given library, you'll be able to learn extra about Modules on the LLVM web site.

module libxml2 [system] {
    hyperlink "xml2"
    umbrella header "libxml2-kanna.h"
    export *
    module * { export * }
}

You may outline your individual umbrella header and inform the system what to import.

#import <libxml2/libxml/HTMLtree.h>
#import <libxml2/libxml/xpath.h>
#import <libxml2/libxml/xpathInternals.h>

I barely use system libraries, however it is a good reference level. In any case, if it is advisable to wrap a system library I assume that you will have the required information to make it occur. 😅

Language settings

You may as well specify the record of Swift verisons that the package deal is appropriate with. If you're making a package deal that incorporates C or C++ code you'll be able to inform the compiler to make use of a selected language commonplace throughout the construct course of.

swiftLanguageVersions: [.v4, .v4_2, .v5, .version("5.1")],


cLanguageStandard: .c11,


cxxLanguageStandard: .gnucxx11)

You may see all of the at the moment accessible choices within the feedback. I do not know what number of of you utilize these directives, however personally I by no means needed to work with them. I am not writing an excessive amount of code from the C language household these days, but it surely's nonetheless good that SPM has this feature built-in. 👍

Abstract

The Swift Bundle Supervisor shouldn't be the right instrument simply but, but it surely's on a superb observe to turn into the de facto commonplace by slowly changing CocoaPods and Carthage. There are nonetheless some lacking options which might be necessities for many of the builders. Don't fret, SPM will enhance so much within the close to future. For instance the binary dependency and useful resource assist is coming alongside Swift 5.3. You may observe the package deal evolution course of on the official Swift Evolution dashboard.

You may learn extra concerning the Bundle Supervisor on the official Swift web site, but it surely's fairly obsolate. The documentation on Apple's web site can be very outdated, however nonetheless helpful. There's a good learn me file on GitHub concerning the utilization of the Swift Bundle Supervisor, however nothing is up to date continuously. 😢