The Swift bundle manifest file

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

import PackageDescription

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

Package deal

A bundle is only a bunch of Swift (or different) recordsdata. The manifest file is the outline of what and construct from these sources. Each single bundle ought to have a reputation, however this isn't sufficient to truly generate one thing from it. You'll be able to solely have precisely one bundle definition contained in the file. That is the shortest and most ineffective one that you could create. 🙈

let bundle = Package deal(identify: "myPackage")

The bundle identify goes for use if you end up importing packages as dependencies, so identify your pacages rigorously. In the event you select a reserved identify by a system framework there will be points with linking. If there is a battle it's a must to use static linking as a substitute of dynamic. In the event you generate a undertaking through the swift bundle generate-xcodeproj command that undertaking will attempt to hyperlink all the things dynamically, however when you open the Package deal.swift file utilizing Xcode 11, the dependencies will likely 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 that you could help.

let bundle = Package deal(
    identify: "myPackage",
    platforms: [
        .iOS(.v13),         
        .macOS(.v10_15),    
        .tvOS(.v13),        
        .watchOS(.v6),      
    ]
)

Once you add a platform you might be placing a constraint on it through the required model. Each single dependency ought to match the requirement of the primary bundle platforms. Lengthy story quick if it's good to add help for Apple platforms, you must 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, apart from macOS, that is going to be v10_10. Each bundle has Linux help by default, you may't add such restrictions but, however possibly this can change within the close to future, additionally Home windows is coming.

Product

A bundle can have a number of ultimate merchandise (construct artifacts). At the moment there are two forms of construct merchandise: executables and libraries. The executable is a binary that may be executed, for instance this generally is 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 bundle = Package deal(identify: "myPackage", merchandise: [
    .library(name: "myPackageLib", targets: ["myPackageLib"]),
    .library(identify: "myPackageStaticLib", kind: .static, targets: ["myPackageLib"]),
    .library(identify: "myPackageDynLib", kind: .dynamic, targets: ["myPackageLib"]),
    .executable(identify: "myPackageCli", targets: ["myPackage"])
], targets: [
    .target(name: "myPackageLib"),
    .target(name: "myPackageCli"),
])

If the library kind is unspecified, the Package deal Supervisor will routinely select it based mostly on the consumer's desire. As I discussed this earlier generated Xcode initiatives desire dynamic linking, however when you merely open the manifest file the app will likely be statically linked.

Dependency

Packages can depend on different packages. You'll be able to outline your dependencies by specifying an area path or a repository URL with a given model tag. Including a dependency into this part just isn't sufficient to make use of it in your targets. You even have so as to add the product supplied by the bundle on the goal stage.

let bundle = Package deal(
    identify: "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 generally is a GitHub URL, thankfully you may add personal repositories as properly through the use of 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 personal packages. 🤫

Goal

A goal is one thing that you could construct, in different phrases it is a construct goal that can lead to a library or an executable. It's best to have a minimum of one goal in your undertaking file in any other case you may't construct something. A goal ought to all the time have a reputation, each different settings is optionally available.

Settings

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

.goal(identify: "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 may see you may outline preprocessor macros for each single language. You should use the protected instances for fundamental stuff, however there may be an unsafeFlags case for the reckless ones. The good factor is that you could help 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

Take a look at targets

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

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

I believe the one distinction between a goal and a check goal is that you could run a check goal utilizing the swift check command, however from a structural perspective, they're principally the identical.

Package deal configs and system libraries

You'll be able to wrap an current 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 via 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 bundle = Package deal(identify: "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 may want a module.modulemap file to export a given library, you may learn extra about Modules on the LLVM web site.

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

You'll be able to 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. Anyhow, if it's good to wrap a system library I assume that you will have the required data to make it occur. 😅

Language settings

You can too specify the record of Swift verisons that the bundle is appropriate with. In case you are making a bundle that incorporates C or C++ code you may inform the compiler to make use of a particular language commonplace through the construct course of.

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


cLanguageStandard: .c11,


cxxLanguageStandard: .gnucxx11)

You'll be able to see all of the at the moment out there choices within the feedback. I do not know what number of of you employ 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 selection built-in. 👍

Abstract

The Swift Package deal Supervisor just isn't the proper instrument simply but, but it surely's on an excellent monitor to turn into the de facto commonplace by slowly changing CocoaPods and Carthage. There are nonetheless some lacking options which can be necessities for a lot of the builders. Don't fret, SPM will enhance so much within the close to future. For instance the binary dependency and useful resource help is coming alongside Swift 5.3. You'll be able to monitor the bundle evolution course of on the official Swift Evolution dashboard.

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