Including Swift Bundle Supervisor Assist – Half 2

Within the earlier submit I checked out a few of the historical past of how we packaged up our library code to be used by our fellow builders. We checked out a few 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 obligatory for me to allow SPM assist 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 realized within the course of.

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

With SwiftPM there isn’t any such mission file. Reasonably the whole lot is outlined in human-readable type within the Bundle.swift file.

For some fundamental terminology: we outline sure merchandise (i.e. static library, dynamic framework, app bundle and so forth, useful resource bundle, unit check bundle), that relate to a lot of targets (a bucket for a bunch of supply code recordsdata and assets). Here’s a distinction from Xcode the place goal and product is used synonymously.

Bundle Definition

Step one, and most essential one, is so as to add a bundle definition file to the basis 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 have a look at the highest folder for Bundle.swift.

Right here’s the definition for Kvitto, for reference. This has all parts you may encounter, together with a dependency on one other bundle, a few assets on high of the definition of 1 product and a number of goal.

// swift-tools-version:5.3

import PackageDescription

let bundle = Bundle(
    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: "Take a look at",
            exclude: ["Info.plist"],
            assets: [.copy("Resources/receipt"),
                        .copy("Resources/sandboxReceipt")]),
    ]
)

The primary line may solely appear like a remark to you, however it’s important for the swift instruments to find out what syntax parts are supported. Model 5.3 is required if in case you have assets in any goal. In case you set that to one thing decrease you get syntax errors concerning the useful resource definitions. In case you set that to five.3 however don’t specify useful resource definitions (for non-standard assets) you’ll get warnings about unknown recordsdata that you must both exclude or outline as assets.

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 check goal has assets. I might get extra inexperienced checkmarks on Swift Bundle 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, everyone ought to be utilizing Swift 5.3 anyway as that’s the baseline commonplace because the launch of Xcode 12.

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

The fundamental setup of the bundle definition is easy. You could have the bundle identify, then some minimal platform variations. Be aware that these minimal OS variations don’t imply that that might limit the the bundle 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 sort: .dynamic you get a dynamic framework as an alternative. The targets array specifies which targets will get merged into the ultimate product.

I believed for a second that that is perhaps good to have the assets be added to the framework as an alternative of a separate useful resource bundle, like we’re used to. However alas the dealing with of assets stays the identical and so they get bundled right into a Product_Target.bundle. So subsequently I’d slightly have the static library – which can get merged into the app binary – slightly than having yet one more separate framework bundle contained in the app bundle.

As I defined within the earlier article, dynamic frameworks ought to be prevented if the supply code for libraries is public. So we’re proud of 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 manner 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 an actual quantity or sure ranges.

Final come the targets. We’ve got an everyday goal for the bundle and a check goal for all of the unit assessments. In case you don’t specify a path then SwiftPM expects the supply code within the Sources folder beneath the goal’s folder and assets in a Assets folder. I’ve a unique construction, so I specified a customized path.

I’ve to exclude the Data.plist for each targets as a result of that is utilized by two targets outlined contained in the Xcode mission. And for the check goal I specify two assets to be copied with the trail relative to the goal customized path. These copy directions are obligatory as a result of the contained assets don’t have a sort that Xcode is aware of the right way to deal with. For issues like strings recordsdata 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. However the check goal requires the primary goal to work. That’s additionally a distinction to Xcode the place the examined code resides inside a bunch utility, the place’s right here it’s compiled into the unit check bundle.

Goal Issues

You is perhaps questioning why there’s a distinction between merchandise and targets in SPM. One purpose for that you’ve already seen: there isn’t any purpose for the check goal to be represented in a product. Easy packages will usually solely have one product that 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 may assume that Swift Bundle Supervisor would solely all you to have code written in Swift. However you’d be incorrect, Any language goes, additionally Goal-C and different C dialects. However SPM doesn’t let you combine C-based languages with Swift in a single goal.

In a single mission I had some Goal-C code for a operate with loads of ifs. I rewrote that in Swift solely to seek out that compiling this may take greater than a minute, in contrast to a couple seconds in Goal-C. So I selected to depart the operate because it was. The answer was to place it right into a separate Goal-C goal and refer that to an inner dependency from the primary Swift goal.

The opposite good purpose for a separate goal and product was to have some widespread information mannequin code that might be utilized by inner targets and in addition by way of import in an app consuming my library. In locations the place the consumer would solely want the shared definitions he would import the precise module for that. Elsewhere he would import different targets which in flip might additionally make use of these definitions internally.

Every product turns into its personal module.

Resourcefulness

I discussed above that you may let SPM do its personal factor relating to commonplace useful resource varieties, like localised strings, XIBs, storyboards and asset catalogs. In case you use string localisation although, you must specify the mission’s default language.

Different varieties you must both particularly exclude or specify what ought to be carried out for it. You possibly can both specify a .copy for every particular person useful resource or additionally for your entire Assets folder. Since I’ve solely two check recordsdata and that’s not going to vary, it wasn’t an excessive amount of work so as to add these individually.

SPM expects assets in the identical folder {that a} goal’s supply recordsdata reside in (or a sub-folder thereof). The rationale for that’s once more that there isn’t any Xcode mission file the place you may specify membership of sure recordsdata to particular targets. You specify what belongs the place by how it’s specified by the file system together of the bundle definition.

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

#!/bin/sh

echo "Eradicating present 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

carried out

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

Platform-specific Code

For the reason that bundle has no facility for limiting particular supply code to particular platforms or OS variations, you’ll face the scenario that sure code received’t compile for different platforms. A workaround for this limitation is the usage of conditional compilation directives.

For instance, the whole lot 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 your entire implementation is enclosed in:

#import 

#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 fastened it.

Contained in the Xcode Mission

The adjustments for conditional compilation apart, there’s nothing it is advisable to change in your Xcode mission – except you wish to. The principal setup for the bundle occurs in Bundle.swift. You possibly can construct the bundle with issuing swift construct.

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

In Xcode 12 there’s a bug that if you happen to try this for the mission folder itself, it appears to work, however when you shut the mission and reopen it once more, the reference turns into defunct. The best way to repair it’s to vary the reference to “Relative to Mission” and open the folder selector by way of the folder button and re-select the mission root folder.

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

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

I had the watchOS platform builds on Swift Bundle Index fail as a result of xcodebuild insists on constructing all targets, together with the check 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 would solely construct the primary goal and I achieved inexperienced checkmarks for watchOS on SPI.

Library Unit Assessments

To run the unit assessments contained within the check goal, all it is advisable to do is to run swift check on the command line, from the repository root folder.

Some magic was required to get that to work as a result of check recordsdata required by the unit assessments are usually 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 establishing a bundle identify from names of bundle and goal. Within the case of unit assessments the executable is xcrun contained within the Xcode.app bundle the place it has no probability of discovering the Kvitto_KittoTests.bundle.

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

func urlForTestResource(identify: String, ofType ext: String?) -> URL?
{
	let bundle = Bundle(for: sort(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 an alternative of the check bundle
	// that aborts unit assessments with message:
	//   Deadly error: couldn't load useful resource bundle: /Functions/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 shall 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 bundle. With this workaround, the earlier mechanisms of working the unit check scheme by way of 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 Bundle Supervisor as progressed sufficiently to begin including assist 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.

Essentially 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 Bundle Index coupled with the discoverability of parts additionally make it enticing for library distributors to think about supporting Swift Bundle Supervisor. Having the dependency administration taken care of by Xcode is the best characteristic of all.

Additionally revealed on Medium.

Classes: Administrative