Within the earlier publish I checked out a number of the historical past of how we packaged up our library code to be used by our fellow builders. We checked out a number of the advantages of static libraries versus dynamic frameworks which additionally include headers wanted by the integrator.

Now let’s dive into the steps that have been mandatory for me to allow SPM help on the primary few libraries DTCoreText, DTFoundation and Kvitto. It took me a number of days to iron out all of the kinks and I’d like to share with you what I discovered within the course of.

We’re used to utilizing Xcode to explain what goes right into a construct: Which information to compile, what exterior libraries to hyperlink to, what sources are wanted and likewise basic construct settings just like the vary and kinds of supported platforms. Extra exactly, these settings are contained within the challenge.pbxproj file inside your xcodeproj bundle.

With SwiftPM there isn’t a such challenge file. Reasonably all the things is outlined in human-readable type within the Package deal.swift file.

For some fundamental terminology: we outline sure merchandise (i.e. static library, dynamic framework, app bundle and many others, useful resource bundle, unit take a look at bundle), that relate to plenty of targets (a bucket for a bunch of supply code information and sources). Here’s a distinction from Xcode the place goal and product is used synonymously.

Package deal Definition

Step one, and most essential one, is so as to add a package deal definition file to the foundation folder of the repository. It must be on this place as a result of Swift Packages are referenced by the repository URL and SwiftPM will solely take a look at the highest folder for Package deal.swift.

Right here’s the definition for Kvitto, for reference. This has all parts you would possibly encounter, together with a dependency on one other package deal, a few sources on prime of the definition of 1 product and a number of goal.

// swift-tools-version:5.3

import PackageDescription

let package deal = Package deal(
    identify: "Kvitto",
    platforms: [
        .iOS(.v9),         //.v8 - .v13
        .macOS(.v10_10),    //.v10_10 - .v10_15
        .tvOS(.v9),        //.v9 - .v13
    ],
    merchandise: [
        .library(
            name: "Kvitto",
            targets: ["Kvitto"]),
    ],
    dependencies: [
        .package(url: "https://github.com/Cocoanetics/DTFoundation.git", 
		from: "1.7.15"),
    ],
    targets: [
        .target(
            name: "Kvitto",
            dependencies: [
                .product(name: "DTFoundation", 
				package: "DTFoundation"),
            ],
            path: "Core",
            exclude: ["Info.plist"]),
        .testTarget(
            identify: "KvittoTests",
            dependencies: ["Kvitto"],
            path: "Check",
            exclude: ["Info.plist"],
            sources: [.copy("Resources/receipt"),
                        .copy("Resources/sandboxReceipt")]),
    ]
)

The primary line would possibly solely appear to be a remark to you, however it will be significant for the swift instruments to find out what syntax parts are supported. Model 5.3 is required when you have sources in any goal. For those who set that to one thing decrease you get syntax errors relating to the useful resource definitions. For those who set that to five.3 however don’t specify useful resource definitions (for non-standard sources) you’ll get warnings about unknown information that you must both exclude or outline as sources.

I discovered myself conflicted about that, as I had talked about within the earlier article. All code would work on Swift 5.0 and up and solely the take a look at goal has sources. I may get extra inexperienced checkmarks on Swift Package deal Index if I eliminated the .testTarget definition.

On the opposite facet the swift instruments allow you to run thusly outlined unit assessments from the command line and functioning unit assessments additionally ought to depend as an indication of fine library high quality. Lastly, all people needs to be utilizing Swift 5.3 anyway as that’s the baseline normal because the launch of Xcode 12.

That’s why I selected to depart it at that.

The essential setup of the package deal definition is simple. You could have the package deal identify, then some minimal platform variations. Word that these minimal OS variations don’t imply that that might prohibit the the package deal to particular platforms.

The merchandise part defines what sort of library comes out of the construct course of. The default setting (invisible) is to supply a static library, by specifying kind: .dynamic you get a dynamic framework as a substitute. The targets array specifies which targets will get merged into the ultimate product.

I assumed for a second that that may be good to have the sources be added to the framework as a substitute of a separate useful resource bundle, like we’re used to. However alas the dealing with of sources stays the identical and so they get bundled right into a Product_Target.bundle. So due to this fact I’d moderately have the static library – which is able to get merged into the app binary – moderately than having one more separate framework bundle contained in the app bundle.

As I defined within the earlier article, dynamic frameworks needs to be averted if the supply code for libraries is public. So we’re pleased with the static library default.

The dependencies part lists the exterior reference to different packages. You specify the repository URL and the minimal variations. The proven method with from and a model would settle for all 1.x.x variations from and together with 1.7.15. There are additionally different methods to specify a precise quantity or sure ranges.

Final come the targets. We’ve an everyday goal for the package deal and a take a look at goal for all of the unit assessments. For those who don’t specify a path then SwiftPM expects the supply code within the Sources folder beneath the goal’s folder and sources in a Assets folder. I’ve a unique construction, so I specified a customized path.

I’ve to exclude the Information.plist for each targets as a result of that is utilized by two targets outlined contained in the Xcode challenge. And for the take a look at goal I specify two sources to be copied with the trail relative to the goal customized path. These copy directions are mandatory as a result of the contained sources don’t have a sort that Xcode is aware of find out how to deal with. For issues like strings information or XIBs you don’t should specify something.

Examine the dependencies key of each targets. On the one hand you see that I’m referencing the exterior dependency of the primary goal. Then again the take a look at goal requires the primary goal to work. That’s additionally a distinction to Xcode the place the examined code resides inside a bunch software, the place’s right here it’s compiled into the unit take a look at bundle.

Goal Concerns

You may be questioning why there’s a distinction between merchandise and targets in SPM. One motive for that you’ve got already seen: there isn’t a motive for the take a look at goal to be represented in a product. Easy packages will usually solely have one product which may solely consist of 1 goal.

Though I already discovered two extra causes, to separate code out into extra particular person targets after which additionally merchandise.

You would possibly assume that Swift Package deal Supervisor would solely all you to have code written in Swift. However you’ll be fallacious, Any language goes, additionally Goal-C and different C dialects. However SPM doesn’t mean you can combine C-based languages with Swift in a single goal.

In a single challenge I had some Goal-C code for a perform with a whole lot of ifs. I rewrote that in Swift solely to search out that compiling this could take greater than a minute, in contrast to some seconds in Goal-C. So I selected to depart the perform because it was. The answer was to place it right into a separate Goal-C goal and refer that to an inside dependency from the primary Swift goal.

The opposite good motive for a separate goal and product was to have some frequent knowledge mannequin code that might be utilized by inside targets and likewise through import in an app consuming my library. In locations the place the consumer would solely want the shared definitions he would import the particular module for that. Elsewhere he would import different targets which in flip may additionally make use of these definitions internally.

Every product turns into its personal module.

Resourcefulness

I discussed above which you can let SPM do its personal factor with regards to normal useful resource varieties, like localised strings, XIBs, storyboards and asset catalogs. For those who use string localisation although, it’s a must to specify the challenge’s default language.

Different varieties it’s a must to both particularly exclude or specify what needs to be completed for it. You may both specify a .copy for every particular person useful resource or additionally for the complete Assets folder. Since I’ve solely two take a look at information and that’s not going to alter, it wasn’t an excessive amount of work so as to add these individually.

SPM expects sources in the identical folder {that a} goal’s supply information reside in (or a sub-folder thereof). The explanation for that’s once more that there isn’t a Xcode challenge file the place you would specify membership of sure information to particular targets. You specify what belongs the place by how it’s specified by the file system together of the package deal definition.

Say you have got a single place the place you have got localised strings information downloaded from a translation website like POEditor however you need them to be included in several targets. A way to realize that’s to create soft-links contained in the goal’s useful resource folders to the information. I wrote this shell script to create the lproj folders for all languages after which create the hyperlinks.

#!/bin/sh

echo "Eradicating current strings"
rm -rf ../TFMViews/Assets/*.lproj
rm -rf ../TFMExtension/Assets/*.lproj

PWD=`pwd`

for entry in *.lproj
do
  echo "Linking $entry..."

  mkdir ../TFMViews/Assets/$entry
  ln -s ../../../Strings/$entry/TFMViews.stringsdict 
     ../TFMViews/Assets/$entry
  ln -s ../../../Strings/$entry/TFMViews.strings 
     ../TFMViews/Assets/$entry

  mkdir ../TFMExtension/Assets/$entry
  ln -s ../../../Strings/$entry/TFMExtension.stringsdict 
     ../TFMExtension/Assets/$entry
  ln -s ../../../Strings/$entry/TFMExtension.strings 
     ../TFMExtension/Assets/$entry

completed

The identical strategy of soft-links will also be employed for Goal-C based mostly packages the place you may hyperlink to all related public headers in an embody folder.

Platform-specific Code

Because the package deal has no facility for limiting particular supply code to particular platforms or OS variations, you’ll face the state of affairs that sure code gained’t compile for different platforms. A workaround for this limitation is using conditional compilation directives.

For instance, all the things that references UIKit can’t be compiled for macOS or watchOS, so I’ve a couple of locations in DTCoreText or DTFoundation (each written in Goal-C) the place the complete implementation is enclosed in:

#import <TargetConditionals.h>

#if TARGET_OS_IPHONE && !TARGET_OS_WATCH
...
#endif

I additionally discovered that typically I needed to additionally import the TargetConditionals header for the defines to work. Particularly sure Goal-C class extensions in DTCoreText wouldn’t be seen within the public interface if I didn’t import this header. I’ve no rationalization as to why, however including the import for the header mounted it.

Contained in the Xcode Mission

The modifications for conditional compilation apart, there may be nothing you want to change in your Xcode challenge – except you wish to. The principal setup for the package deal occurs in Package deal.swift. You may construct the package deal with issuing swift construct.

I discovered it handy so as to add a reference to the package deal contained in the Xcode challenge as a result of this lets you debug your code within the context of being compiled for a package deal. For those who drag any folder (containing a package deal definition) into the challenge navigator pane, Xcode will add a neighborhood package deal reference for you, with a logo of a cute little field.

In Xcode 12 there’s a bug that should you do this for the challenge folder itself, it appears to work, however when you shut the challenge and reopen it once more, the reference turns into defunct. The best way to repair it’s to alter the reference to “Relative to Mission” and open the folder selector through the folder button and re-select the challenge root folder.

This additionally creates a scheme for constructing the package deal and the package deal’s merchandise turn into obtainable to hyperlink/embed to your app. Package deal merchandise have an icon of a greek temple. If they’re static libraries then they may get merged into the app binary, dynamic frameworks will probably be added to the app’s Frameworks folder.

Xcode additionally creates a scheme for the package deal, inserting it in .swiftpm/xcode/xcshareddata/xcschemes/. I moved it into the shared schemes folder of the xcodeproj and renamed it to Kvitto-Package deal.xcscheme.

I had the watchOS platform builds on Swift Package deal Index fail as a result of xcodebuild insists on constructing all targets, together with the take a look at goal. This fails as a result of unit assessments require XCTest which doesn’t excite for watchOS.

By offering an aptly named shared scheme it’s going to solely construct the primary goal and I achieved inexperienced checkmarks for watchOS on SPI.

Library Unit Exams

To run the unit assessments contained within the take a look at goal, all you want to do is to run swift take a look at on the command line, from the repository root folder.

Some magic was required to get that to work as a result of take a look at information required by the unit assessments usually are not bundled within the .xctest bundle. For normal packages a useful resource bundle accessor is being robotically generated, which you should utilize with Bundle.module.

The accessor works by figuring out the trail of the executable and developing a bundle identify from names of package deal and goal. Within the case of unit assessments the executable is xcrun contained within the Xcode.app bundle the place it has no likelihood of discovering the Kvitto_KittoTests.bundle.

My ugly, however useful, workaround for that is as follows:

func urlForTestResource(identify: String, ofType ext: String?) -> URL?
{
	let bundle = Bundle(for: kind(of: self))
		
	#if SWIFT_PACKAGE
		
	// there's a bug the place Bundle.module factors to the trail of xcrun contained in the Xcode.app bundle, as a substitute of the take a look at bundle
	// that aborts unit assessments with message:
	//   Deadly error: couldn't load useful resource bundle: /Purposes/Xcode.app/Contents/Developer/usr/bin/Kvitto_KvittoTests.bundle: file KvittoTests/resource_bundle_accessor.swift, line 7
		
	// workaround: attempt to discover the useful resource bundle on the construct path
	let buildPathURL = bundle.bundleURL.deletingLastPathComponent()
		
	guard let resourceBundle = Bundle(url: buildPathURL.appendingPathComponent("Kvitto_KvittoTests.bundle")),
	   let path = resourceBundle.path(forResource: identify, ofType: ext) else
	{
		return nil
	}
		
	return URL(fileURLWithPath: path)
		
	#else
		
	guard let path = bundle.path(forResource: identify, ofType: ext) else
	{
		return nil
	}
		
	return URL(fileURLWithPath: path)
		
	#endif
}

This depends on the truth that the useful resource bundle will probably be created parallel to the xctest bundle, in the identical construct folder. The #if SWIFT_PACKAGE conditional compilation will solely be added if this code is constructed as a part of a swift package deal. With this workaround, the earlier mechanisms of working the unit take a look at scheme through Xcode continues to work.

The wonderful thing about Swift being open supply, is that we will additionally examine the code for the useful resource accessor on GitHub. It seems that the talked about bug has already been addressed there. The repair was made too late to make it into Swift 5.3 in Xcode 12 however has been confirmed to be current in Xcode 12.2.

Conclusion

I discover that the evolution of Swift Package deal Supervisor as progressed sufficiently to start out including help for it to my libraries. It’s attainable and advisable to take action along with different methods of integration, like Xcode subproject, Cocoapods or Carthage.

Probably the most annoying limitation remaining is that you just can not restrict targets to sure platforms or specify a spread of supported OS variations per goal. However these can simply be labored round with conditional compilation directives.

The standard standards partially enforced by the Swift Package deal Index coupled with the discoverability of elements additionally make it engaging for library distributors to contemplate supporting Swift Package deal Supervisor. Having the dependency administration taken care of by Xcode is the best function of all.

Additionally revealed on Medium.

Classes: Administrative