The Swift package deal manifest file


This text is an entire Swift Package deal Supervisor cheatsheet for the package deal manifest file, utilizing the most recent Swift 5.2 instruments model.

Swift


If you wish to be taught learn how to use the Swift Package deal Supervisor you must learn my different article, as a result of that’s extra like an introduction for many who have by no means labored with SPM but.


Package deal sorts

There are a number of package deal sorts you can create with the swift package deal init command. You may specify the --type flag with the next values: empty, library, executable, system-module, manifest. You may as well outline a customized package deal title by means of the --name flag.

  • The empty package deal will create the default file construction with out the pattern code recordsdata.
  • The library kind will create a reusable library product template.
  • The executable kind will create a Swift software with an executable product definition within the package deal and a primary.swift file as a place to begin.
  • The system-module kind will create a wrapper round a system supplied package deal, comparable to libxml, we’ll discuss this in a while.
  • The manifest kind will solely create a Package deal.swift file with out the rest.





The Package deal manifest file

Each single SPM venture has this particular file inside it referred to as Package deal.swift. I already wrote a put up about how the package deal supervisor and the Swift toolchain works behind the scenes, this time we will focus solely on the manifest file itself. Let’s get began. 📦

Each single Package deal.swift file begins with a particular remark line the place it’s important to outline the model of the used Swift instruments. The newest model is kind of completely different from the older ones.



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


import PackageDescription

That is it now you're prepared to explain the package deal 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 readme.





Package deal

A package deal is only a bunch of Swift (or different) recordsdata. The manifest file is the outline of what and learn how to construct from these sources. Each single package deal ought to have a reputation, however this isn't enought 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 you can create. 🙈


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


The package deal title goes for use if you end up importing packages as dependencies, so title your pacages fastidiously. When you select a reserved title by a system framework there may be points with linking. If there is a battle it's important to use static linking as an alternative of dynamic. When you generate a venture through the swift package deal generate-xcodeproj command that venture will attempt to hyperlink every thing dynamically, however if you happen to open the Package deal.swift file utilizing Xcode 11, the dependencies will probably be linked statically if this was not set explicitly within the product definition part.




Platform

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


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


Whenever you add a platform you're placing a constraint on it through the required model. Each single dependency ought to match the requirement of the primary package deal platforms. Lengthy story quick if you might want to add assist 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, aside from macOS, that is going to be v10_10. Each package deal has Linux assist by default, you may't add such restrictions but, however possibly this may change within the close to future, additionally Home windows is coming.





Product

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



import PackageDescription

let package deal = Package deal(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 Package deal Supervisor will mechanically select it based mostly on the consumer's desire. As I discussed this earlier generated Xcode initiatives favor dynamic linking, however if you happen to merely open the manifest file the app will probably 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 will not be sufficient to make use of it in your targets. You even have so as to add the product supplied by the package deal on the goal stage.

let package deal = Package deal(
    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 generally is a GitHub url, fortuitously you may add non-public repositories as properly by utilizing an ssh key based mostly authentication. Simply use the [email protected]:BinaryBirds/viper-kit.git url format, as an alternative of the HTTP based mostly, if you wish to add non-public packages. 🤫




Goal

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


Settings

There are various settings that you need to use to configure your goal. Targets can depend upon 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 need 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(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 may see you may outline preprocessor macros for each single language. You should utilize the secure circumstances for primary stuff, however there's an unsafeFlags case for the reckless ones. The good factor is you can assist a platform situation filter together with construct configuration to each single settings because the final param.

Accessible platforms are: .iOS, .macOS, .watchOS, .tvOS, .android, .linux, .home windows
The construct configuration may be .debug or .launch


Check targets

Check 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(title: 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 you can run a check goal utilizing the swift check command, however from a structural viewpoint, they're mainly the identical.




Package deal configs and system libraries

You may wrap an current system library utilizing Swift, the fantastic 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 wonderful 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 = Package deal(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 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 may outline your individual umbrella header and thell the system what to import.





I barely use system libraries, however it is a good reference level. Anyhow, if you might want 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 listing of Swift verisons that the package deal is appropriate with. In case you are making a package deal that accommodates C or C++ code you may inform the compiler to make use of a particular language normal through 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 out there 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, however it's nonetheless good that SPM has this selection built-in. 👍



Abstract

The Swift Package deal Supervisor will not be the proper instrument simply but, however it's on observe to turn into the de facto normal by slowly changing CocoaPods and Carthage. There are nonetheless some lacking options which might be necessities for many of the builders. Don't be concerned, 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 Package deal Supervisor on the official Swift web site, however it's fairly obsolate. The documentation on Apple's web site can be very outdated, however nonetheless helpful. There's a good readme file on GitHub concerning the utilization of the Swift Package deal Supervisor, however nothing is up to date continuously. 😢