Andrew Jaffee - AppCoda

Using SwiftUI and WidgetKit to Make Your App Content Indispensable

Andrew Jaffee — Mon, 22 Nov 2021 01:19:55 GMT

By using a combination of SwiftUI and WidgetKit, you can increase the visibility of your app’s content and enhance the user experience by placing one or more “widgets” on the user’s iOS Home screen, macOS Notification Center, and/or iOS Today View.

Widgets should display your app’s most relevant content, allowing users to get important information with a glance. When a user taps/clicks a widget, they go straight to your app and should land on a page that gives them more details about what they just glanced at. Take a look at your iPhone’s Today View right now. There are widgets for weather, battery power, maps, stock exchanges — with many more available. For example, you can get an almost-instant read on the current atmospheric conditions by glancing at one of several available weather widgets. This time of year, before I leave the house, I glance at the weather widget to determine if I need a coat and hat before going outside. If I want to get the forecast for later in the day, I just tap on that weather widget to open the respective weather app.

Since widgets display content with SwiftUI views, they are generally easy to create and portable across Apple’s devices, like iPhones and Macs. Each of your apps can provide multiple widgets, multiple instances of the same or different widgets, and three different sizes of the same widgets.

Let’s talk about at an example of design considerations for building a widget, from my sample project. You should click that link and download my project to follow along with this article. I used Xcode 13.1 to write this sample app and iOS 15.0 on the Simulator and on an iPhone 12 to test.

My “Events” app has a widget that shows the important events that occur during a workday along with the times at which they occur. Look at the following two images. The first highlights my widget showing the events of the day in fast motion, because we wouldn’t want to wait to watch the widget over a 15-hour period. The widget simply shows the nearest-occurring event and its time; information that can be seen at a glance. The second image shows what happens when you tap on the widget: the app opens showing all the events of the day including the one that was being shown in the widget at the time of the tap. Remember that this app is a proof of concept highlighting WidgetKit and SwiftUI, and is not fully-functional.

It should be apparent to you by now that, because of a widget’s limited amount of space, it should only display information that users see as most valuable in your app. Don’t clutter things up. Design for simplicity, ease of use, and elegance.

Because widgets are portable between iOS and macOS, are pretty small, and should convey concise, glanceable information, SwiftUI is the perfect tool to use for building their user interfaces. Indeed, WidgetKit requires that you use SwiftUI views to design and render widgets’ content.

A word about my sample app

The sample app that we’ll walk through in this article is very simple and not fully functional on purpose. I want you to get a basic understanding of SwiftUI and WidgetKit without getting bogged down in a bunch of implementation details about how a daily to-do list app would be written. My app implements just enough of a to-do list to introduce you to SwiftUI and WidgetKit; the rest is a facade.

So, if fully functional, my app would allow a user to define 5 to 6 essential life events in a day, assign times to those events, and, at any time, glance at the widget to see the nearest approaching event, based on some type of timing algorithm. If the app was completed, tapping on the widget would take a user to a detail screen for the nearest event where one could, say, make some notes, set a reminder or alarm, add contacts, add directions, then go back to the main summary screen showing a list of all the day’s events and times, and edit another event. Since my app is still a prototype, when the user taps on the widget (or opens the app itself), he or she is sent directly to a screen to see a read-only list of events and times.

Creating the base app

Let’s walk through the steps I went through to develop my sample “Events” app. I made it a SwiftUI-based app. Open Xcode 13.x and go to:

New > Project…
On the Choose a template for your new project: screen, select iOS and App, then click Next.
On the Choose options for your new project: screen, fill in Product Name: with “Events,” select your own Team:, set your own Organization Identifier:, set the Interface: to “SwiftUI,” set the “Language:” to “Swift,” then click Next.
Select the new project location and click Create.

The new app will have two code files, “EventsApp.swift” and “ContentView.swift.” We’ll leave “EventsApp.swift” alone. It’s custom App protocol conformer, EventsApp, provides the entry point into the app and will render the simple user interface defined in “ContentView.swift.”

Take a look at “ContentView.swift.” I wrote a simple declarative SwiftUI user interface (UI) using the struct named ContentView. The app’s entire UI is in the body member of the ContentView:

import SwiftUI

let events = ["Wake up", "Breakfast", "Go to work", "Lunch", "Come home", "Go to sleep"]
let eventTimes = ["7:00 AM", "8:00 AM", "8:30 AM", "12:00 PM", "5:00 PM", "11:00 PM"]

struct ContentView: View {

    var body: some View {
    
        // Screen title
        Text("Daily Events").bold().italic().padding()
    
        // List of daily events with times
        Form {
            ForEach(0..





First, I used a Text view to give my list of events a title, using some view modifiers to highlight that title (.bold().italic().padding()). Then I used a Form view as the main container for the app’s list of events because, in real life, I’d allow editing of my events here. Right now, the app only displays the events and their times read-only, but always think ahead. The ForEach writes out the events and their respective times as Text views, one per line, for all to-do list items that I’ve stored in arrays. The Form has a colored border and some padding around it. There’s a reason I used 2 arrays and it has to do with widgets auto-updating, but that’s beyond the scope of this article.



Running the “Events” app now shows this screen:







For those of you following along, test your “Events” app and make sure it looks like the previous picture.



Adding the WidgetKit extension



Widget functionality can be added to the SwiftUI “Events” app I started up above. All’s I have to do is to add a new target — a WidgetKit extension — to my existing app. Head back to Xcode 13 and go to:



File > New > Target…
On the Choose a template for your new target: screen, select iOS and Widget Extension, then click Next.







On the Choose options for your new target: screen, fill in Product Name: with “EventTimes,” select your own Team:, set your own Organization Identifier: (same as “Events” app), do not set the Include Configuration Intent, make sure that “Project:” and “Embed in Application:” are both set to “Events,” and then click Finish.







You’ll be prompted to activate your new “EventTimesExtension” scheme; make sure you press the “Activate” button now.



A few items have been added to your “Events” app project, most notably, the “EventTimes.swift” WidgetKit code and the WidgetKit.framework. We’ll spend most of the rest of the article discussing “EventTimes.swift.”



Data sharing between the app and widget?



Notice that I’ve defined the same data model (2 arrays) at the top of the extension’s “EventTimes.swift” that I already defined in the containing app’s “ContentView.swift”:



let events = ["Wake up", "Breakfast", "Go to work", "Lunch", "Come home", "Go to sleep"]
let eventTimes = ["7:00 AM", "8:00 AM", "8:30 AM", "12:00 PM", "5:00 PM", "11:00 PM"]



Remember that “Even though an app extension bundle is nested within its containing app’s bundle, the running app extension and containing app have no direct access to each other’s containers.” In other words, the 2 arrays defined in just the containing app are not accessible to the extension and vice versa. One solution would be to define an app group to which both the “Events” app and “EventTimesExtension” extension belong. They could then share the same data model. But that is way beyond the scope of this article — and I already wrote a tutorial on app groups for AppCoda which I urge you to read: “Using App Groups for communication between macOS/iOS apps from the Same Vendor”.



How WidgetKit works



Widgets are driven by, like many other aspects of our reality, time. With my “Events” app and widget, we have a relatively fixed list of events that occur throughout the day. What drives the updating of the widget to show the next nearest coming-up event is that event’s time. Think of the iPhone weather widget. It also is driven by time, probably polling a server every 30 seconds so it can update the current conditions, the current temperature, and the day’s current high and low.



Let’s go through the code in the WidgetKit extension’s “EventTimes.swift” file from top to bottom, even though that might not may be the most logical order. But if I jump around, you’re likely to get confused — plus I urge you to compare my version of the file to the template version as first generated when you created the WidgetKit extension.



Let’s start at the top of the file:



import WidgetKit
import SwiftUI

let events = ["Wake up", "Breakfast", "Go to work", "Lunch", "Come home", "Go to sleep"]
let eventTimes = ["7:00 AM", "8:00 AM", "8:30 AM", "12:00 PM", "5:00 PM", "11:00 PM"]
var currentEvent = 0

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), eventName: "Daily event", eventTime: "N/A")
    }

.
.
.



From the first struct we encounter, of type TimelineProvider, you can see why I said that widgets are driven by time. The placeholder function “displays a generic representation of your widget, giving the user a general idea of what the widget shows”. It is called if your widget is displayed but no real data is ready to be displayed, perhaps because the containing app hasn’t been configured or established network connections yet. SimpleEntry is the struct that holds instances of data that are shown one at a time in your widget. To be specific, this SimpleEntry reference is the struct constructor that returns an instance.



.
.
.

    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = SimpleEntry(date: Date(), eventName: events[currentEvent], eventTime: eventTimes[currentEvent])
        completion(entry)
    }

.
.
.



The getSnapshot function provides an app timeline entry for the current time (and perhaps state) of the widget. For my “Events” app, this would be the nearest event in time in your daily schedule about to occur.



.
.
.

    func getTimeline(in context: Context, completion: @escaping (Timeline) -> ()) {
        var entries: [SimpleEntry] = []

        // Generate a timeline consisting of six entries an second apart, starting from the current time.
        let currentDate = Date()
    
        for timeOffset in 0 ..< events.count {
            let entryDate = Calendar.current.date(byAdding: .second, value: timeOffset, to: currentDate)!
            let entry = SimpleEntry(date: entryDate, eventName: events[timeOffset], eventTime: eventTimes[timeOffset])
            entries.append(entry)
        }
        currentEvent = 0
    
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    } // end getTimeline

.
.
.



For a static prototype like my sample “Events” app, the getTimeline function can build the entire timeline to be displayed in my widget. Because of the policy: .atEnd, the timeline is created over and over. I already explained why a real version of my “Events” app would need a more sophisticated algorithm to calculate a timeline of the “next, nearest” event relative to the current point in time. For a weather app, some type of polling algorithm could be used to make network requests to get the current conditions for the current times throughout the day.



struct SimpleEntry: TimelineEntry {
    let date: Date
    let eventName: String
    let eventTime: String
}



As I mentioned above, the SimpleEntry is the struct that holds instances of data that are shown one at a time in your widget. Note that the date is essential to a timeline.



struct EventTimesEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text(entry.eventTime)
            Text(entry.eventName)
        }
    }
} // end EventTimesEntryView



This is the SwiftUI I used to display the widget. Do I even need to explain what I’m drawing here? Just look at my widget. It just amazes me how I can write such short, simple, and elegant code to get a UI. The declarative UI is here!



@main
struct EventTimes: Widget {
    let kind: String = "EventTimes"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            EventTimesEntryView(entry: entry)
        }
        .configurationDisplayName("My Daily Events")
        .description("Shows my typical workday schedule.")
    }
} // end EventTimes



The @main attribute specifies the single entry point to my Widget extension. My widget is given a string tag for system identification purposes. I’m specifying the SwiftUI that my widget uses and I provide template text that people will see when they look up my widget so they can add it to my iPhone Home or Today View screens, as described in the next section.



Adding widgets after the app is installed



Once you install my sample app on an iPhone, you want to install one or more instances of its widget in one or more of the three available sizes. This ani-GIF shows you how to install a widget on the Home screen:







Note that I started the process by long-pressing on empty Home screen space. You can follow the same process on the Today View or, instead of starting by long-pressing, you can scroll down to the bottom of the page and tap the “Edit” button.



Static versus user-configurable widgets



Mainly because my “Events” app and widget are proofs of concept, they are static. While I’ve mentioned possibilities for editing the events and times, those values are currently fixed. But you can make your widget user-configurable. When the good folks who were writing the iPhone weather app added their widget extension, they ticked the Include Configuration Intent checkbox — that’s the checkbox we didn’t tick.



To make a long story short, you can configure the weather widget by long-tapping it until the context menu appears and selecting the “Edit Widget” item. The widget “flips over” to present an interface that allows you select from a list of nationwide locations that the widget will then show weather snapshots for.



Conclusion



Adding a widget to your app can add a whole lot of value to your app. You can make it so much more useful by allowing one glance to give users the gist of the main purpose of your app. Think of ways to make your apps indispensable to users — an essential part of their lives. Widgets are one of the best ways I’ve seen in recent years to accomplish this lofty goal.



Deep Dive into Swift 5.5's Async/await Concurrency Model
Andrew Jaffee — Mon, 05 Jul 2021 16:20:00 GMT



In designing the async/await construct, Apple is hoping to increase the readability, and thus maintainability, of implementing concurrency/parallelism in Swift. What I see in it are attempts:



to make asynchronous/parallel code almost look like synchronous/sequential code; and,
to make asynchronous/parallel code much more semantically clear (more readable, less verbose, compact, doing what it says).



These are laudable and ambitious goals, but I’d say Apple’s heading in the right direction. I’m glad because I write a lot a asynchronous code to keep my apps responsive — to create the best possible user experience for my customers. I have a feeling that most of you write a lot of concurrent code, too.



We’ll walk through how to use async/await in detail, but I will limit my discussion to it. You need to understand async/await before trying to use Swift’s other new concurrency features, like actors, continuations, the AsyncSequence protocol, the TaskGroup generic structure, task cancellation, and a few other concepts.



The Swift team has added hundreds of async (or “awaitable”) methods to the language, but I’d like you to focus on the pattern I use to implement most any call involving async/await, not on specific functions. To take an even broader view, I’ll compare using Swift’s async/await to using Swift’s Grand Central Dispatch (GCD) implementation. Both technologies offer “generic” support for parallelism. In other words, they both can support asynchronous/parallel code in a wide variety of applications, from long-running multi-step mathematical computations to large file downloads that all need to be run in the background. We’ll go over a common async/await beginner’s pitfall and finally end with some advice about where to go next with Swift concurrency.



Please note that async/await is not unique to Swift. Javascript, C++, Python, and C# are some examples of languages which support this construct. Also note that while async/await is nice to have, I wouldn’t want to give up access to GCD. It’s too powerful, despite its use of closures.



Please download my sample Xcode 13 beta project, written in Swift 5.5, essential for getting the most out of this tutorial. The Base SDK is iOS 15 beta and I used an iPhone 12 Pro Max for the base UI layout in my storyboard.



The heart of the problem



When faced with writing concurrent/asynchronous code, Swift developers are used to submitting a specific task, like downloading a big file, and then waiting for the download to finish in a completion handler or delegate callback. If you review an example of using Apple’s downloadTask(with:completionHandler:) SDK call that I used in another article right here on AppCoda, you’ll see that the code is a bit awkward, verbose, complex, hard to read, and spread out. Look at where I have to call task.resume() to start the download. Note that I defined the ImageDownloadCompletionClosure elsewhere in the code. It’s not super intuitive.



...
func download(completionHanlder: @escaping ImageDownloadCompletionClosure)
{

    let sessionConfig = URLSessionConfiguration.default
    let session = URLSession(configuration: sessionConfig)
    let request = URLRequest(url:imageURL)

    let task = session.downloadTask(with: request) { (tempLocalUrl, response, error) in

        if let tempLocalUrl = tempLocalUrl, error == nil {
            if let statusCode = (response as? HTTPURLResponse)?.statusCode {
                let rawImageData = NSData(contentsOf: tempLocalUrl)
                completionHanlder(rawImageData!)
                print("Successfully downloaded. Status code: \(statusCode)")
            }
        } else {
            print("Error took place while downloading a file. Error description: \(String(describing: error?.localizedDescription))")
        }
    } // end let task

    task.resume()

} // end func download
...



Apple, language architects, and many developers feel that the block–completion handler model is hard to read, especially when you’re nesting calls of this type. As Apple puts it:



…Even in [the] simple[st] case, because the code has to be written as a series of completion handlers, you end up writing nested closures. In this style, more complex code with deep nesting can quickly become unwieldy.



So, to nested completion handlers, add error checking, like guard, if let, do, try, catch, defer, throw, Error — even NSError, which also can be nastily nested, you truly get yourself into a major pyramid of doom. Note that my sample project has very little in the way of error checking, not to be sloppy, but so you can concentrate on the subject of this article without distraction.



Enter the Swift 5.5 async/await keywords, which by no means constitute all the new Swift concurrency features. I believe you should first learn about async/await before exploring the rest of Swift’s new concurrency model.



Good old GCD



Let’s start out talking about a tool that many of us have used in the past to perform long-running operations in the background, thus freeing our apps to do other things, and allowing the user interface (UI) to remain responsive. One common scenario is downloading a background image for an app’s login screen while not preventing user interaction (like typing their username and password). Most of you should know about GCD, but if you don’t, I’ve written an extremely in-depth article on using it with Swift. In fact, the sample code I discussed in that article is used right here.



Let’s first read through my downloadImageGCD method, part of this article’s companion project. We’ll talk about that function in just a minute:



...
// example of GCD asynchronous code; as
// soon as an image download is queued, control
// flows immediately onwards
func downloadImageGCD(for url: String, with index:Int) -> Void {

    DispatchQueue.global(qos: DispatchQoS.QoSClass.default).async {

        _ = self.isCodeOnMainThread(named: "start GCD image \(index) downloading...")
        let imageURL = URL(string: url)
        // this call blocks until the image data is downloaded,
        // BUT we're running in the background
        let imageData = NSData(contentsOf: imageURL!)
        // convert the data into an image
        let image = UIImage(data: imageData! as Data)

        DispatchQueue.main.async {
            self.imageViewStellar.image = image
            self.imageViewStellar.setNeedsDisplay()
            print("GCD image \(index) downloaded/displayed")
        }

    } // end DispatchQueue.global(qos: ...

} // end func downloadImageGCD
...



By wrapping my GCD code in a for loop, the downloading of 22 big image files are queued up, but the downloads occur in the background, so the UI remains responsive, and I can click any of my sample app’s buttons at any time and they do some concurrent work. The following for loop is called when you click the “Start GCD Downloading” button on the app’s main screen:



...
func startGCDAsyncImageDownload()
{
    for index in 0..




Watch the video of my app working and check out my print statements to the console. Notice there’s a bit of stuttering when I click the “Increment” button, but that’s mainly due to updating the UIImageView on the main thread:







My downloadImageGCD function is intrinsically asynchronous. Given a URL, you schedule a task to download the data at that URL on a background thread. Then you specify a completion handler to display the downloaded data in a UIImageView and move on. Code flow whips right through this function. By the time the images start displaying in the UI, you can be off somewhere else in the app’s code. REMEMBER: As shown above, always update your UI on the main thread. See my updateImageView(with:) used throughout the sample project.



Since I’m running my code on a multi-core processor, calling downloadImageGCD demonstrates true parallelism. Concurrency/asynchrony involves a stochastic (random) element. Look at my console output to see the random queuing and completion of tasks — and go to Xcode’s Debug navigator -> CPU to see worker threads being created and eventually cleaned up:



start GCD image 0 downloading... ON BACKGROUND THREAD
start GCD image 1 downloading... ON BACKGROUND THREAD
start GCD image 2 downloading... ON BACKGROUND THREAD
start GCD image 4 downloading... ON BACKGROUND THREAD
start GCD image 3 downloading... ON BACKGROUND THREAD
start GCD image 5 downloading... ON BACKGROUND THREAD
...
GCD image 9 downloaded/displayed
GCD image 21 downloaded/displayed
GCD image 7 downloaded/displayed
GCD image 18 downloaded/displayed
GCD image 12 downloaded/displayed
GCD image 5 downloaded/displayed



I purposely used the init(contentsOf:) initializer of NSData to download image data because it is a synchronous, blocking call, a concept central to this article. Yes, it blocks until all data at the specified URL downloads, but I’m using that NSData initializer on a background thread. If you called that function on your main thread, your app would freeze until all URL data downloads. Remember that I submitted the synchronous download inside a block passed to the very asynchronous DispatchQueue...async {...}. Later, we’ll see that “blocking” or “suspending” have a different meaning in async/await.



The SDKs available to Swift have been populated with many, many calls that include completion handlers or delegate callbacks, not just DispatchQueue. I have a lot of good asynchronous code that’s already been written using the block–completion handler pattern. I’m certainly not going to go back and rewrite it all using the new Swift concurrency gimmicks. But looking forward, I will consider using constructs like async/await.



The Swift 5.5 async/await construct



Let’s define some terminology essential to understanding Swift’s new concurrency model.



async:



add this keyword to a function signature (declaration) to denote that that method is asynchronous, i.e., can potentially run code in parallel with other code, and can be subject to suspension and later resumption
suspension may occur, for example, to await the results of some long-running task
suspension may occur, for example, for short-term tasks like updating the UI
suspension may not occur at all
functions marked async must themselves call await to be suspended (see below)
when an async function suspends, it does not block its thread
when an async function suspends, the operating system can queue and execute other processes on it’s thread



await:



obviously marks a potential suspension point in your code, making that suspension point clear to people reading the code
the code on the rest of the line following the await can be scheduled by the system for running a long task
that long task can be suspended once or many times so the system can execute other work
a shorter task might not be suspended at all and it can run to completion
once its task finishes, the await line finishes, and execution continues on the next line
when Swift suspends the current thread, other code is allowed to execute on that same thread



async-let:



lets you call asynchronous functions when you don’t need the return value immediately
you can start one or many tasks that can be run in parallel
other code can run while your asynchronous functions process



async {...}:



enables you to kick off asynchronous work from within regular, synchronous code, like from within a function not labelled async
you call your asynchronous code between the “{” and “}”



How to write code with async/await



Now that we’ve defined the terms async and await at a theoretical level, let’s learn how to write code using these constructs. As an alternative to my downloadImageGCD method, which uses GCD with a completion handler, let’s write an async function that you call with an image URL and it returns the image data, kind of like a synchronous function would do so. But it doesn’t block, it possibly suspends for a relatively brief period while the image downloads, probably on a background thread, but that is not guaranteed as I understand the new Swift construct (see my definitions above).



...
func downloadImageAsync(for url: String, with index:Int) async throws -> UIImage {

    _ = isCodeOnMainThread(named: "start awaitable image \(index) downloading...")
    let request = URLRequest(url: URL(string: url)!)
    let (data, response) = try await URLSession.shared.data(for: request)
    guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw HTTPError.withIdentifier((response as! HTTPURLResponse).statusCode) }
    let downloadedImage = UIImage(data: data)
    return downloadedImage!

} // end func downloadImageAsync
...



Notice that we place the async keyword just after the method signature’s parameter list but before the throws and the return type. Pause for a moment to review my async keyword definition up above.



The key to this method is this line:



    let (data, response) = try await URLSession.shared.data(for: request)



Since URLSession.shared.data is async (“awaitable”), we must call it with await; it also throws. If an async function throws, you always put a try before the await, as we did here when calling the function. The lines of code both before and after data(for:) on the shared URLSession are synchronous. The code after this network download call is dependent on the data and response it returns, so it must suspend while the image data at url downloads. Here’s the magic: while this line (and its containing method) suspend, other work in the app can be done.



A great benefit of writing code with async/await is the enhanced readability. You can obviously see asynchronous code and potential suspension points. There’s also less clutter without the closure syntax.



Our first try at async/await



To prove to you that async/await works efficiently and allows other app work to be done simultaneously, let’s do an experiment with my code. I’ve got some code commented out, but don’t make any changes yet. Let’s review what you’ll do first. Here’s the code that my app’s “Start Proper Awaitable Downloading” button calls:



...
@IBAction func startProperAwaitableDownloadingButtonClicked(_ sender: Any) {

    counter = 0;
    counterTextField.text = "0"
    imageViewStellar.image = nil

    async {

        let image = try! await downloadImageAsync(for: imageAltURLs[0], with: 0)
        updateImageView(with: image)
        print("GIANT FILE FINALLY DOWNLOADED")
        //await startRightNewSimpleSyncImageDownload()
        //await startRightNewSimpleAsyncImageDownload()
        //await startExperimentAsyncImageDownload()
        //await startTaskGroupAsyncImageDownload()
    }

} // end startProperAwaitableDownloadingButtonClicked
...



While this @IBAction func is synchronous, note that you can call async code by wrapping it in the async{...} construct as defined above. The image at the URL in imageAltURLs[0] is gigantic and takes awhile to download. You already saw earlier that my downloadImageGCD function downloads and displays 22 large image files. Ready? Run my app and press the “Start Proper Awaitable Downloading” button, then quickly press the “Start GCD Downloading” button.



Your console output should be similar to that shown next, though not exactly the same. You’ll see the async call to download the huge file start up and suspend. Then you’ll see the GCD function simultaneously queuing and downloading 22 images. Most of the time, the async file will download later to last when considering all total 23 downloads, not because there’s anything wrong with async, but because it’s downloading a very large file.



start awaitable image 0 downloading... ON MAIN THREAD
start GCD image 0 downloading... ON BACKGROUND THREAD
start GCD image 1 downloading... ON BACKGROUND THREAD
start GCD image 2 downloading... ON BACKGROUND THREAD
start GCD image 3 downloading... ON BACKGROUND THREAD
...
start GCD image 19 downloading... ON BACKGROUND THREAD
start GCD image 21 downloading... ON BACKGROUND THREAD
start GCD image 20 downloading... ON BACKGROUND THREAD
GCD image 0 downloaded/displayed
GCD image 4 downloaded/displayed
GCD image 2 downloaded/displayed
...
GCD image 20 downloaded/displayed
GCD image 21 downloaded/displayed
GCD image 16 downloaded/displayed
GIANT FILE FINALLY DOWNLOADED



How NOT to use async/await



Unless you’re enforcing some specific order of execution because of certain interdependencies, I would advise you to avoid using a bunch of await calls in sequence. Let’s look at two examples from my project. Here’s a “manual” example:



...
// these downloads occur SEQUENTIALLY because we
// start each download with the "await" keyword
func startRightNewSimpleSyncImageDownload() async -> Void {

    let stellarImage0 = try! await downloadImageAsync(for: imageURLs[0], with: 0)
    let stellarImage1 = try! await downloadImageAsync(for: imageURLs[1], with: 1)
    let stellarImage2 = try! await downloadImageAsync(for: imageURLs[2], with: 2)

    _ = isCodeOnMainThread(named: "startRightNewAsyncImageDownload")

    // no await is needed
    updateImageView(with: stellarImage0)
    print("stellarImage0 with index 0 downloaded")
    updateImageView(with: stellarImage1)
    print("stellarImage1 with index 1 downloaded")
    updateImageView(with: stellarImage2)
    print("stellarImage2 with index 2 downloaded")

} // end func startRightNewSimpleSyncImageDownload
...



Here’s a “automated” example (I used a for loop):



...
// this method is a misguided attempt to
// call a bunch of blocking calls all at once
func startWrongNewAsyncImageDownload()
{

    async {

        for index in 0..




Why would I impose such a sequential ordering, especially if I were preparing an image gallery and/or the thumbnails for a UICollectionView? Even with concurrency involved, think of what would happen if each of the image downloads was in the order of 170 MB, as opposed to the ~30 MB files I’m downloading from my URL array’s addresses. Or suppose I had a long list of mathematically intense calculations? I’d have a lot of uninterruptible tasks that would make my app run sluggishly at best. Even if I were required to enforce a sequence of tasks, each dependent on the previous one, this wouldn’t be the most optimal way to encode my work. See the console output:



start awaitable image 0 downloading... ON MAIN THREAD
awaitable image 0 downloaded/displayed
start awaitable image 1 downloading... ON MAIN THREAD
awaitable image 1 downloaded/displayed
start awaitable image 2 downloading... ON MAIN THREAD
awaitable image 2 downloaded/displayed
start awaitable image 3 downloading... ON MAIN THREAD
awaitable image 3 downloaded/displayed
start awaitable image 4 downloading... ON MAIN THREAD
awaitable image 4 downloaded/displayed
start awaitable image 5 downloading... ON MAIN THREAD
awaitable image 5 downloaded/displayed
start awaitable image 6 downloading... ON MAIN THREAD
awaitable image 6 downloaded/displayed
start awaitable image 7 downloading... ON MAIN THREAD
awaitable image 7 downloaded/displayed
start awaitable image 8 downloading... ON MAIN THREAD
awaitable image 8 downloaded/displayed
start awaitable image 9 downloading... ON MAIN THREAD
awaitable image 9 downloaded/displayed
start awaitable image 10 downloading... ON MAIN THREAD
awaitable image 10 downloaded/displayed
start awaitable image 11 downloading... ON MAIN THREAD
awaitable image 11 downloaded/displayed
start awaitable image 12 downloading... ON MAIN THREAD
awaitable image 12 downloaded/displayed
start awaitable image 13 downloading... ON MAIN THREAD
awaitable image 13 downloaded/displayed
start awaitable image 14 downloading... ON MAIN THREAD
awaitable image 14 downloaded/displayed
start awaitable image 15 downloading... ON MAIN THREAD
awaitable image 15 downloaded/displayed
start awaitable image 16 downloading... ON MAIN THREAD
awaitable image 16 downloaded/displayed
start awaitable image 17 downloading... ON MAIN THREAD
awaitable image 17 downloaded/displayed
start awaitable image 18 downloading... ON MAIN THREAD
awaitable image 18 downloaded/displayed
start awaitable image 19 downloading... ON MAIN THREAD
awaitable image 19 downloaded/displayed
start awaitable image 20 downloading... ON MAIN THREAD
awaitable image 20 downloaded/displayed
start awaitable image 21 downloading... ON MAIN THREAD
awaitable image 21 downloaded/displayed



As we’ll see below, I can use async/await to download a whole bunch of images in parallel/simultaneously.



Running multiple parallel tasks with async/await



I always try to learn a new technology myself instead of waiting for someone else to figure it out and then doing copy and paste programming. I like to actually work through a practice test before looking at the answers in the back of the book. I want to figure out why I got some answers wrong.



Such was the case with figuring out how to run multiple parallel tasks with async/await. I was able to figure out how to manually use async-let. When I say “manually,” I mean I could start a fixed number of tasks, but couldn’t figure out how generalize my code for some varying number of tasks. I think the problem with async-let is that the construct has a let, implying a constant, not a variable.



Here’s my successful attempt at spawning 3 image downloads in parallel — and displaying the images from the downloaded data:



...
// each download occurs asynchronously -- even simultaneously
func startRightNewSimpleAsyncImageDownload() async -> Void {

    async let stellarImage0 = try! downloadImageAsync(for: imageURLs[0], with: 0)
    async let stellarImage1 = try! downloadImageAsync(for: imageURLs[1], with: 1)
    async let stellarImage2 = try! downloadImageAsync(for: imageURLs[2], with: 2)

    _ = isCodeOnMainThread(named: "startRightNewAsyncImageDownload")

    updateImageView(with: await stellarImage0)
    print("stellarImage0 with index 0 downloaded")
    updateImageView(with: await stellarImage1)
    print("stellarImage1 with index 1 downloaded")
    updateImageView(with: await stellarImage2)
    print("stellarImage2 with index 2 downloaded")

} // end func startRightNewSimpleAsyncImageDownload
...



OK, this works, but it is way too specific of a solution. What if I wanted to be able to download 2, 10, 30, or 60 images using some kind of repetitive language construct, like for or while? I tried to figure this repetitive thing out for awhile — without looking for somebody else’s solution. Look at my startExperimentAsyncImageDownload() function for evidence of my failed attempts.



Using a TaskGroup with async/await



In an effort to find a repetitive solution to downloading any number of images, I did some research. All’s I found was a brief section in some Swift documentation with a theoretical and not really usable solution. But I did get something working. Look at my sample code for a method named startTaskGroupAsyncImageDownload(), study it, run it, look at the console output, and watch my sample app’s screen while the function is working. Here’s the code:



...
// new Swift structured concurrency using
// tasks and task groups
func startTaskGroupAsyncImageDownload() async -> Void {

    _ = self.isCodeOnMainThread(named: "startRightNewAsyncImageDownload started")

    await withTaskGroup(of: UIImage.self) { taskGroup in

        for index in 0..




Now this code acts truly concurrent. Hey, wait a minute. We’re using a closure. Hmmm…



I’m not going into a detailed explanation of this method as the main purpose of this article is introducing readers to async/await. But let me share one insight. See my comment above this line of code?



        for await image in taskGroup {



This was key to figuring out how to make my experimental code work. I found this not on the Swift website, but in the Xcode context sensitive help when I clicked on the withTaskGroup keyword:



To collect the results of tasks that were added to the group, you can use the following pattern: …



Conclusion



Understanding Swift 5.5’s new concurrency features starts with async/await. I hope you learned a lot here today. I encourage you to practice using async/await with my sample code, study the links I’ve included in this article, and then to push forward through all the WWDC 2021 presentations on Swift’s other new concurrency features, like on actors, continuations, the AsyncSequence protocol, the TaskGroup generic structure, task cancellation, and a few other concepts. I especially recommend the WWDC 2021 sessions on “Explore structured concurrency in Swift”, “Protect mutable state with Swift actors”, and “Swift concurrency: Behind the scenes”.



One bit of homework: Look at my sample code’s isCodeOnMainThread(named:) function. Can you explain why the function prints “…ON MAIN THREAD” in some places while “…ON BACKGROUND THREAD” in others? I’m sure the Thread.isMainThread is working properly. I’ll respond to any comments left on my article regarding this question, or respond to any other comments you may have.



Enjoy!





Deploying Mac Apps Outside App Store: How to Remember User Intent for Folders
Andrew Jaffee — Thu, 27 Aug 2020 10:42:11 GMT



When a macOS user specifically grants a sandboxed app access to a file/folder outside of that app’s container, that special access only survives until the app is closed. If the user reopens the app and wants to again read from and write to that “outside” folder, they have to go through the whole process of showing macOS their “intent” to stray out of the container — unless the developer adds something called “security-scoped bookmarks.” These bookmarks are the topic of today’s tutorial.



I’ll be explaining in-depth how developers can create these special bookmarks, store them, access them later, including two required steps that must take place just before and just after a stored bookmark is referenced. Specifically, I’ll be clarifying Apple’s rather terse documentation on “the methods, constants, and entitlements to use for implementing security-scoped bookmarks in your app.”



Please download my sample Xcode 11.6 project, written in Swift, essential for getting the most out of this tutorial.



A series of tutorials



This is the fourth part in a four-part series of tutorials comparing the differences between distributing macOS apps inside and outside of the Mac App Store (MAS), comparing sandboxed and non-sandboxed apps, and considering app security.



In Part I of this series, I built a non-sandboxed app, discussed certificates, signed the app, notarized it, briefly talked about building an installer, signed and notarized the installer, and lastly touched on distribution of the app installer.



In my second tutorial (Part II), I examined the app sandbox and then built an app that, whether sandboxed or not sandboxed, could read and write outside of its container — and could be sold and distributed either outside the MAS or through the MAS, both with Apple’s blessings.



Part III was my detailed guide on how to use Packages, by far one of the most popular macOS development tools, for creating app installers, allowing you too securely distribute your products and help your customers easily add your functionality to their Macs. You can review my column here on AppCoda for a list of all four parts of my series, as well as all my other articles.



Review of app sandboxing



My Part II article has a detailed definition of sandboxing in the section entitled “What is an app sandbox?”. Please review, but let me briefly explain how today’s tutorial gives you additional control over sandbox restrictions.



You should think of the sandbox as a very constrictive fence surrounding your app. Of course, an app would be useless if this fence was impenetrable. Apps are only useful if they can act on some type of input and produce meaningful output. Apple wants us as developers to start with very little access to system resources and then only request more resources on an as-needed basis. Because of scope, time, and space constraints, I’ve confined the discussion of resources to the file system, but keep in mind that your vulnerable surface area includes Mac components like network connections, microphones, the camera, Bluetooth, etc. To reiterate, in this tutorial, we’re going to “bookmark” a resource — a folder’s URL — outside the sandbox so the user doesn’t have to approve access to that folder every time he/she opens the app.



To keep this article focused on one topic, let me just be precise in my terminology. There are actually two types of security-scoped bookmarks. Using Apple’s language, we’ll only be talking about an app-scoped bookmark, one which “provides your sandboxed app with persistent access to a user-specified file or folder.” The other type, a document-scoped bookmark, is similar but slightly more complex and “typically supports the notion of a project document that refers to other files.” I leave it to you to do some research and easily extrapolate from the knowledge provided in this tutorial.



Review of getting user intent for folders outside the sandbox



If a user wants to access a file/folder that is outside of the container, Apple requires the user to explicitly select that file/folder using an NSOpenPanel. Apple is getting the user’s overt permission — they call “intent” — to access that folder/file. This is one of Apple’s methods for limiting the vulnerable surface area of the app to attack by malware. Remember that no permission is needed from the user to access the file system inside the app’s sandboxed container.



Configuring and implementing this intent-getting feature requires some preparation via Xcode which is discussed in detail in Part II of this series. Please review the section in that article entitled “Getting user intent for folders outside the sandbox.” We’ll review the code shown in that section again as a slightly modified version of it is also incorporated into the source included with this tutorial’s sample project.



I determine the user’s “intent” by running my app, clicking my Select folder button, and recording the URL of the folder the user picked (~/Documents). What I’m doing is saying “If you want to access a folder outside of the container, you have to explicitly tell me it’s OK for the app to read and/or write there.” When you look at my sample source code for this tutorial, you’ll notice some new code I’ve added to the function in which user intent for a folder (and its URL) is obtained: I create a security-scoped bookmark for that folder/URL. Here’s a short video showing how my app gets the user’s permission to access their Mac’s ~/Documents folder and then creates a security-scoped bookmark for that folder:







This would be a really good time for you to open up my sample project and start following along.



Implementing security-scoped bookmarks



Let’s discuss my code so you can implement security-scoped bookmarks in your own macOS apps. I’ve placed some step numbers (e.g., “STEP 1”) in my source commentary that will make it easier for us to talk about my code here in the tutorial while also easily being able to find it in my project.



Project configuration



I’ve mentioned “Step 1” in my code just as a reminder, but it is an Xcode project configuration option. Open the project’s AppNotaryAndDistrib.entitlements file and make sure you take notice of 1) the entitlement turning on sandboxing and 2) the entitlement enabling security-scoped bookmarks, like so:







    com.apple.security.app-sandbox
    
    com.apple.security.files.user-selected.read-write
    
    com.apple.security.files.bookmarks.app-scope
    





Selecting a folder to bookmark



Now let’s dive into my Swift. Look at the selectFolderBtnClicked(_ sender: Any) method in my sample project’s ViewController.swift file:



...
/**
 We encourage the user to select a folder, like ~/Documents,
 showing their "intent" to grant our app access to that folder.
 That directory is OUTSIDE of this app's sandbox. We do this
 in preparation for allowing us to reach out of our container. What's
 new in this version of the code is BOOKMARKING the selected folder.
*/
@IBAction func selectFolderBtnClicked(_ sender: Any) {

    self.pathTextField.stringValue = "..."

    let folderSelectionDialog = NSOpenPanel() // a modal dialog

    folderSelectionDialog.prompt = "Select"
    folderSelectionDialog.message = "Please select a folder"

    folderSelectionDialog.canChooseFiles = false
    folderSelectionDialog.allowedFileTypes = ["N/A"]
    folderSelectionDialog.allowsOtherFileTypes = false

    folderSelectionDialog.allowsMultipleSelection = false

    folderSelectionDialog.canChooseDirectories = true

    // open the MODAL folder selection panel/dialog
    let dialogButtonPressed = folderSelectionDialog.runModal()

    // if the user pressed the "Select" (affirmative or "OK")
    // button, then they've chosen a folder
    if dialogButtonPressed == NSApplication.ModalResponse.OK {

        if folderSelectionDialog.urls.count == 1 {

            if let url = folderSelectionDialog.urls.first {

                // if the user doesn't select anything, then
                // the URL "file:///" is returned, which we ignore
                if url.absoluteString != "file:///" {

                    // save the user's selection so that we can
                    // access the folder they specified later
                    self.userSelectedFolderURL = url

                    print("User selected folder: \(url)")
                    self.pathTextField.stringValue = url.absoluteString

                    // STEP 1 - add the entitlement to our target notifying
                    // macOS that we're using security-scoped bookmarks

                    // STEP 2 - create a persistent bookmark for the
                    // folder the user just selected
                    _ = saveBookmarkForSelectedURL()

                } else {
                    print("User did not select a folder: file:///")
                }

            } // end if let url = folderSelectionDialog.urls.first {

        } else {

            print("User did not select a folder")

        } // end if folderSelectionDialog.urls.count

    } else if dialogButtonPressed == NSApplication.ModalResponse.cancel { // user clicked on "Cancel"

        print("User cancelled folder selection panel")

    } // end if dialogButtonPressed == NSApplication.ModalResponse.OK

} // end func selectFolderBtnClicked
...



What I’m doing in here is popping up an NSOpenPanel, allowing the user to browse through their Mac’s file system, and enabling him/her to select a folder outside the sandbox. There’s one important difference between the Part II code and that shown immediately above: Once I obtain the URL of the folder for which the user has clearly shown their intent, I bookmark that folder. By doing this, the app remembers the folder so the user doesn’t have to go through all the rigamarole required to give permission to access that folder every time the app is run. Remember that I showed you a video up above of this process.



It might be a good idea to provide a checkbox in an accessoryView you wire into your NSOpenPanel with a prompt saying something like “Remember this folder?” This would provide a higher level of security by requiring your users to decide whether a folder outside the container should remain accessible “forever” or not. That’s a style issue I leave to you. Note that NSOpenPanel inherits from NSSavePanel.



Bookmarking a folder outside the container



Let’s continue talking about my selectFolderBtnClicked(_ sender: Any) method, but concentrate on the new bookmarking code. In an effort help developers understand my code, I added a project configuration reminder: “STEP 1 – add the entitlement to our target notifying macOS that we’re using security-scoped bookmarks.” In other words, don’t forget to add the com.apple.security.files.bookmarks.app-scope entitlement before doing anything else. STEP 2 is the call to my saveBookmarkForSelectedURL() method. There, I create a persistent bookmark for the folder/URL the user just selected. I pass the URL to the bookmarkData(options:includingResourceValuesForKeys:relativeTo:) instance method of the NSURL class (STEP 2.1) and then save the new bookmark in UserDefaults (STEP 2.2). The bookmark is some kind of Data blob (with metadata?), most likely encrypted so that malicious software with prying eyes can’t read it from a preferences .plist file. Remember to store the bookmark data value in preferences with a meaningfully-named key:



...
func saveBookmarkForSelectedURL() -> Bool {

    do {

        if let selectedURL = self.userSelectedFolderURL {

            // STEP 2.1 - create a security-scoped bookmark
            // "Returns bookmark data for the URL, created with specified options and resource values."
            // Return Value: Type: Data - A bookmark for the URL.
            let bookmarkData = try selectedURL.bookmarkData(options: .withSecurityScope, includingResourceValuesForKeys: nil, relativeTo: nil)

            // get an instance of UserDefaults
            let userDefaults = UserDefaults.standard

            // STEP 2.2 - store the newly-created bookmark in UserDefaults
            // accessible with a meaningful key; user defaults supports storing
            // and fetching the Data/NSData types
            userDefaults.set(bookmarkData, forKey: "PermanentFolderBookmark")

            // creating the bookmark did not throw an error, so return positive
            return true

        } else {
            print("ERROR: You cannot bookmark a URL that is nil")
            return false
        }

    } catch let error {

        print("Could not create a bookmark because: ", error)
        return false

    }

} // end func saveBookmarkForSelectedURL()
...



Retrieving a bookmarked folder/URL



Now we’ll see how a security-scoped bookmark lasts across app launches. Let’s assume that the user of my app has explicitly used the Select folder button in my app’s UI, thus executing my selectFolderBtnClicked(_ sender: Any) method, and added the ~/Documents folder to their app sandbox as we just finished discussing. Let’s further assume that the user closed my app after bookmarking ~/Documents and it is now 5 days later. They launch my app and then click the Write to file button. The IBAction bound to that button, writeToFileBtnClicked(_ sender: Any), is shown below, but in this section we’ll only talk about STEP 3.



Getting the bookmark stored in UserDefaults is a whole step in and of itself. Accessing — reading from or writing to — the bookmark/URL takes some special handling that we’ll talk about separately. We’ll talk about STEP 4, STEP 5, and STEP 6 in the next section.



Read through the following code and take special notice of STEP 3, the call to getPersistentFileURL(). We’ll talk about that method just below the code for writeToFileBtnClicked(_ sender: Any).



...
@IBAction func writeToFileBtnClicked(_ sender: Any) {

    self.pathTextField.stringValue = "..."

    // STEP 3 - get the permanent folder location the user selected earlier
    if var persistentURL = getPersistentFileURL() {

        // STEP 4 - "Explicitly indicate that you want to use the file-system resource whose URL you obtained in step 3. Do this immediately after obtaining the security-scoped URL..."
        _ = persistentURL.startAccessingSecurityScopedResource()

        // create the FULLY-QUALIFIED path to the file by
        // appending a file name to the URL (path)
        persistentURL = persistentURL.appendingPathComponent("test.txt", isDirectory: false)
        print("Persistent URL: ", persistentURL)

        // STEP 5 - prepare text to write to the file
        let fileText = "This is the text in the file.";

        // try writing file to a non-sandboxed folder...
        do {
            try fileText.write(to: persistentURL, atomically: false, encoding: String.Encoding.utf8)
            self.pathTextField.stringValue = persistentURL.absoluteString
        }
        catch let error // ... or find out why write fails
        {
            print(error.localizedDescription)
            // write some code to recover from error
        }

        // STEP 6 - "When done using the resource, explicitly indicate that you want to stop using it. Do this as soon as you know that you no longer need access to the resource (typically, after you close it)."
        persistentURL.stopAccessingSecurityScopedResource()

    } // end if var persistentURL = ...

} // end func writeToFileBtnClicked
...



STEP 3 is the call to getPersistentFileURL() which returns our previously-bookmarked URL. To get our bookmark, first we need to retrieve the bookmark’s Data value from UserDefaults by using the key with which we originally saved it. In STEP 3.1, we extract the URL from our bookmark’s Data by passing that blob to init(resolvingBookmarkData:options:relativeTo:bookmarkDataIsStale:), an initializer of NSURL. It’s pretty obvious that we want a URL from our stored bookmark, so there’s no need to dissect this SDK method call. The only thing I’ll highlight is the bookmarkDataIsStale variable that I pass as a pointer into the resolvingBookmarkData initializer. If an app gets deleted and reinstalled, macOS is upgraded, or some such unforeseen eventuality occurs, it’s possible that our bookmark may be wrong or outdated. We certainly don’t want a URL that points to garbage or nil, thus you see the code I’ve written to handle a “stale” bookmark in STEP 3.2. When getPersistentFileURL() returns, STEP 3 is done, and we’ve got our URL from our bookmark. Please go back up and review my writeToFileBtnClicked(_ sender: Any) method up above and we’ll pick up in the next section with STEP 4.



...
func getPersistentFileURL() -> URL? {

    // STEP 3 - get the permanent folder location the user selected earlier
    // get from UserDefaults
    let userDefaults = UserDefaults.standard
    if let bookmarkData = userDefaults.data(forKey: "PermanentFolderBookmark") {

        do {

            // we'll pass this variable by value so it can be set
            // by an SDK method
            var bookmarkDataIsStale = false
            // STEP 3.1 - "When you later need access to a bookmarked resource, resolve its security-scoped bookmark by calling the the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: method of the NSURL class"
            let urlForBookmark = try URL(resolvingBookmarkData: bookmarkData, options: .withSecurityScope, relativeTo: nil, bookmarkDataIsStale: &bookmarkDataIsStale)

            // STEP 3.2 - a bookmarks might be "stale" because the app hasn't been used
            // in many months, macOS has been upgraded, the app was
            // re-installed, the app's preferences .plist file was deleted, etc.
            if bookmarkDataIsStale {
                print("The bookmark is outdated and needs to be regenerated.")
                _ = saveBookmarkForSelectedURL()
                return nil

            } else {
                return urlForBookmark
            }

        } catch {
            print("Error resolving bookmark:", error)
            return nil
        }

    } else { // bookmarkData is nil

        print("Error retrieving persistent bookmark data.")
        return nil

    } // end if let bookmarkData =

} // end getPersistentFileURL
...



Accessing a bookmarked folder/URL



Let’s pick up where we left off in my writeToFileBtnClicked(_ sender: Any) method up above. Remember we took a short detour to examine how a URL is obtained from bookmark Data stored in UserDefaults. Let’s assume have our URL and resume our discussion with STEP 4. You cannot read from or write to a resolved bookmark’s URL directly. We’ll be writing a file to our bookmark folder’s URL in this case. Apple requires a special step both before and after we write (well, access in general).



I believe there is sound method in Apple’s madness. They want developers to be absolutely certain they know that they’re potentially accessing a file/folder that’s “outside” the sandbox, even though the user already provided their intent — permission — to do so. If a developer were careless in accessing a file/folder, they may accidentally expand the attackable surface area of their app. This could be especially dangerous if faced with a very aggressive and innovative invader.



Let’s walk through the remaining steps involved in accessing — writing to — a file in a bookmarked folder. Please again review the writeToFileBtnClicked(_ sender: Any) method shown above while pondering these final steps:



STEP 4: Before writing data to the file, you must call the startAccessingSecurityScopedResource() instance method of the bookmark’s NSURL.



STEP 5: Write text to file at the location specified by the bookmark’s URL, where I’ve hardcoded and appended a filename to the URL.



STEP 6: Immediately after you’re finished with a bookmark, in this case, writing to a file in the folder it represents, you must call the stopAccessingSecurityScopedResource() instance method of the bookmark’s NSURL. It is very important that you remember to balance every call to startAccessingSecurityScopedResource() with a call to stopAccessingSecurityScopedResource() because:



If you fail to relinquish your access to file-system resources when you no longer need them, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, such as via Powerbox or security-scoped bookmarks, until relaunched.



Now you’ve gone through the complete cycle of getting user intent for a file/folder (resource) outside the sandbox, bookmarking that resource, saving the bookmark, closing and reopening the app perhaps multiple times, reading the bookmark, and accessing it without driving the user crazy with too many prompts, from beginning to end. Here’s a video showing my app writing a file to a folder, ~/Documents, that was bookmarked several sessions back; i.e., writing to a bookmark after the app has been closed and reopened several times:







Conclusion



After this four-part series covering macOS development, I’ve covered a lot of ground, including comparing the differences between distributing macOS apps inside and outside of the Mac App Store, comparing sandboxed and non-sandboxed apps, and considering app security. I’ve especially highlighted secure coding techniques in a world increasingly reliant on technology, but also besieged by throngs of malicious hacker-attackers. On a positive note, I’ve also shown you how lucrative it can be when you have macOS skills. With the blurring of the lines between iOS and macOS just around the corner with macOS Big Sur 11 and iOS 14, it will be increasingly important for you to know about both environments.



This tutorial has shown you how to allow macOS apps to conveniently — at least for the user — reach outside of their sandboxes without requiring repetitive tasks. Always keep a good user experience in mind when designing your code.



Happy coding!





Using Packages to create an installer for distributing macOS apps outside of the Mac App Store
Andrew Jaffee — Fri, 10 Jul 2020 01:31:10 GMT



macOS developers will most likely be faced with the requirement to build an installer for apps they want to — or must — distribute outside of the Mac App Store (MAS). There is also substantial economic incentive to explore macOS development targeting sales outside of the MAS. In this tutorial, I’ll be explaining how to use Packages, by far one of the most popular tools for developing macOS app installers. It is used by macOS developers worldwide. I’ll provide step-by-step instructions, including many screenshots, walking you through the entire process of building installers. Very importantly, Packages is freeware.



A 2019 survey found that more macOS app developers exclusively sell outside the MAS than exclusively inside the MAS, a near majority sell both inside and outside the MAS, and 58% of macOS developers’ revenue comes from outside-the-MAS sales.





A series of tutorials



This is the third part in a four-part series of tutorials comparing the differences between distributing macOS apps inside and outside of the MAS, comparing sandboxed and non-sandboxed apps, and considering app security.



In the first tutorial in this series, I built a non-sandboxed app, discussed certificates, signed the app, notarized it, briefly talked about building an installer, signed and notarized the installer, and lastly touched on distribution of the app installer.



In my second tutorial, I examined the app sandbox and then built an app that, whether sandboxed or not sandboxed, could read and write outside of its container — and could be sold and distributed either outside the MAS or through the MAS, both with Apple’s blessings.



Finally, in Part IV, I’ll guide you step-by-step through the process of “remembering” a user’s intent regarding access to system resources that Apple considers vulnerable to attack by malicious software. Specifically, I’ll be discussing a technology called “security-scoped bookmarks.” Please check my column here on AppCoda for Part IV.



What is a package?



Packages can be used to deliver a variety of assets to any number of Macs, but this tutorial will concentrate on building a distributable that installs a macOS app onto a Mac, MacBook Pro, MacBook Air, etc. So, in essence, a package (.pkg) is an app that installs another app — plus a few optional dependencies. I’ll use the terms “package,” “installer,” and “distributable” interchangeably herein.



In this tutorial, we’ll only talk about a “flat” installer, in other words, our distributable will be one single file with a .pkg extension. You’ll see how, despite the fact that my Packages installer project is composed of multiple files, the final .pkg will only be one file. Building “bundle” installers is beyond the scope of this article.



Finally, did you know that “Packages’ distribution is built using Packages. Would you care about a solution that would not do that?” I care about and use Packages.



Creating an installer



While Packages is a very intuitive tool, if you’ve never used it before and/or never built an installer, it’s best to start with a tutorial like mine herein so you know what to expect, get an idea of the general workflow, and learn how to “build” (generate/compile) an installer, a .pkg. You can download my sample Packages project and associated assets, required for getting the most out of this tutorial. It’s a .zip file. After downloading it, extract it to a convenient folder on your Mac.



Get Packages installed on your Mac



Download the latest version of Packages from this link and install it on your Mac. Open the file you just downloaded and follow the onscreen instructions to install Packages. The latest version at the time of writing this tutorial was 1.2.9. Please keep in mind that this excellent tool is freeware. I believe Packages is the best app for creating installers for macOS. Full disclosure: I have no personal or financial relationship or interest with Packages’ author, Stéphane Sudre. I urge you to use his app and, by doing so, support his efforts.



Preparing the environment and metadata for your installer



Our installer will have a splash screen, “readme” file, and a license agreement, all contained in three separate files in my downloadable .zip. I’ll just show you how to add such files to a Packages installer. I don’t need to tell you how to create a text file or rich text file with images (.rtfd), both of which can be created with an editor like macOS’s builtin TextEdit app.



The three files I just discussed can be found in the UI_Assets folder with these names:



Introduction.rtfd
ReadMe.rtf
License.rtf



When working in production, I urge you to store your Packages projects and user interface (UI) assets in folders that are under source control. If you’re using Git, you’d git add all your distribution-related files and folders to your repo, commit, and push.



Creating a new Packages project



All the work I’ll discuss in the following sections has already been done in my sample Packages project, so you can just follow along or you can recreate the steps I’m about to enumerate and elucidate.



We’ll start a new installer project by using the Packages Distribution template. Start Packages, go to the File menu, select the New Project… option, and the Choose a template for your project: window will pop up:







After you select the Distribution template, click Next button. The Choose the name and location for your project: window will be displayed:







Make your Project Name meaningful, like in this example, since the app is named AppNotaryAndDistrib, I’ll call it, well, AppNotaryAndDistrib. Click the Choose… button to select a Project Directory in which to store the new project file. Save it in the AppDistribution directory in my sample that you downloaded and click the Create button.



Just before your new project file is created, Packages will try to access your contacts, thus causing macOS to go security-gaga and prompt you with this dialog:







I click the Don’t Allow button because I create installers using a variety of Internet domain-based identifiers (e.g., com.domainName.pkg.AppName).



Packages will create a file named AppNotaryAndDistrib.pkgproj where .pkgproj is the extension used for project files. This screen will appear next:







Look at the left sidebar for a blue icon with the word Project next to it. Below this, you’ll also notice a list of your project’s Packages, as a project can be configured to build multiple distributables, like an Xcode project can have multiple targets. Each distributable has a yellow/brown “box” (package?) icon and, next to it, its name. In today’s tutorial, we’ll just have one package, which is the name I just assigned the project (AppNotaryAndDistrib).



Highlight the blue Project icon and we’ll go through and configure its Settings, Presentation, Requirements & Resources, and Comments tabs respectively. NOTE: You should be constantly saving changes made to this new Packages project as we go.



The project Settings tab



You can accept most of the default values on this tab, with several exceptions, but let’s go through each one. I’m referring to the last screenshot I just discussed directly above.



The Name field will contain the same value you just entered as the Project Name. I usually leave this as-is so that the installer we build later will be called [APP_NAME].pkg. Leave the Path field set to build so that the installer we compile will be placed in a folder called build in the AppDistribution project folder I created for this installer. (Note that you can change the build location to whatever you want.) Leave the Reference Folder set to Project Folder so that all project assets and distributables will be referenced relative to the project home folder we chose earlier, and thus be portable and maintainable. Leave the Format set to Flat. This means that your installer will be one (clean) single file with a .pkg extension. Finally, don’t change the Exclusions as these are files that rightfully should not be included in your installer. If you find the need to exclude certain files from your installer, e.g., Git files, this would be the place to do so.



The project Presentation tab



On the project’s Presentation tab, we’ll customize the new installer’s user interface and configure some installation options. We’ll work our way through the bulleted list of buttons, starting with Introduction going all the way down to Summary:







Let’s start by adding a splash screen. Click on the Introduction button and then click the + button. A placeholder will appear under the Custom Introduction Localizations section, with the default locality being the USA. Activate the dropdown and choose the Introduction.rtfd file in my Packages project file system’s UI_Assets folder, as shown in the last screenshot. Notice that Packages already provides terse and basic installer UI screens if you don’t want to customize.



Make sure you configure the path to Introduction.rtfd to be Relative to Project so the new .pkgproj is portable, maintainable, and self-contained. Do the same with the “readme” and license files, like so:







Packages immediately previews what my introduction file is going to look like when the installer runs:







Go ahead and use the same process to add the custom “readme” and licensing files I mentioned earlier. I urge you to always provide a license with software you distribute, but keep in mind that I am not a lawyer and this does not constitute legal advice. It is up to you to seek out legal counsel and discuss your potential liabilities before you release any software to a client and/or to the public.



The Destination Select button does not apply to us, so we’ll skip it and click on Installation Type. This is just a way to give users options as to how and where they’ll install the actual .app. We’ll keep things super simple and choose to install my sample app using the Standard Install Only protocol. You can give users more options, but I leave it to you to explore those on your own time:







Notice that I’ve highlighted Standard Install on “Catalina New”. The standard install in this case defaults to the current macOS boot partition on which we’ve got Packages running (mine is “Catalina New”). This means the .pkg will attempt to install the app on the user’s current bootable partition.



The Installation button is not relevant to our discussion and the Summary button just shows a screen telling the user that the installation succeeded. I’ll show you images of the real installer screens later.



The project Requirements & Resources tab



When you distribute a lot of software, it can make maintenance easier to have all your customers install your app the same way. This tab affords you precise control over where your app can be installed. For example, I have one customer who always ticks the “Install on startup disk only” checkbox:







There’s no need to go to the Comments tab, so I’ll skip it. We’re now done with all the Project tabs. Let’s move to the Packages tabs.



The package’s Settings tab



Remember when we started our new installer project, I pointed out that Packages is the title for the left sidebar of the app? Since a project can be configured to build multiple distributables, each one has a yellow/brown icon next to its name. Remember that we have just one package, which is the name I assigned to the project upon its creation. Click on the package icon named AppNotaryAndDistrib:







The Identifier field will be pre-filled with com.mygreatcompany.pkg.AppNotaryAndDistrib, but since this package is for my company, I renamed it. I used us.microit.pkg.AppNotaryAndDistrib. Notice how it starts with the reverse of my company website’s domain, http://microit.us. This is also known as your installer’s “tag,” just like your app has a Bundle Identifier.



I left the Version number at 1.0, but please use this field to track the version history of your distributables. For On Success, meaning when the installer finishes without a problem, I usually leave it set to Do Nothing but you can also Require Restart, Require Shutdown, or Require Logout. I almost always leave Location as Embedded and you will too most of the time. Trust me — or do your own research about the other possible values. Finally, I prefer that Require admin password for installation be ticked so that only the Mac’s owner can install software. You can see that there are quite a few options you can set to customize your installer. I urge you to fiddle with these settings and learn about the possibilities.



The package’s Payload tab



Without the Payload tab, your Packages project would be useless. The payload is the app to be installed. Here’s how I use drag and drop to add my sample app bundle, AppNotaryAndDistrib.app, to our Packages project:







Remember that the app to be installed must already be signed and notarized before being added to an installer. I’ve included a signed and notarized version of my sample app in [the download for this tutorial](INSERT LINK TO MY PACKAGES PROJECT). I select the signed and notarized version of my sample app in Finder, highlight it, and drag it into Packages’ virtual Finder-like representation of the target Mac’s file system. My sample Packages project is arranged so that the target .app sits in the same folder as the project file we’re now editing. In most cases you’ll drag your app bundle into the project’s virtual /Applications folder so your payload, in most cases, an app, will be installed where most other apps are installed.



Notice that as soon as I drag my AppNotaryAndDistrib.app file into the Payload tab, a sheet entitled Choose options for adding these files: pops up asking me if I want configure my project to reference an Absolute Path or Relative Path. If you chose a Reference Style of Absolute Path, then your project will be hardcoded to look for the target app (deliverable) in a specific location on your Mac every time you build your installer. I rather use a Relative Path, that is, relative to the Packages project file. That way, as long as I Xcode-build my target app into the same location specified in my Packages project, I can always build an installer regardless of any hardcoded paths. An example is in order: Which is more supportable, this hardcoded path, /Users/andrewjaffee/Documents/path/to/the/file/target_app_name.app, or this relative path, ./target_app_name.app?



The same sheet where you specify the target path has an Ownership checkbox. I suggest you leave this alone now and just set the Reference Style as you’ll have the opportunity to scrutinize the target app’s permissions in just a moment. Just click the Finish button.



Since I don’t want to get into a discussion about macOS (Unix) file permissions, I suggest you leave all the default settings provided by Packages on this Payload tab, like so:







This is a nice summary of where and how the .pkg will install the app. The bottom line here is that the permissions should only allow a Mac owner with sufficient rights to allow the installation of a new app in /Applications and not allow just any other user to delete or tamper with apps installed in that same folder.



I leave it to you to do your own research and explore the remaining options on this tab.



Building the Packages installer



We’re now ready to create a distributable capable of installing my sample app on any compatible Mac. To create the installer/package (.pkg), which is universally understood and executed by macOS, we need to “build” the installer. Think of this process as akin to compiling an app using Xcode.



Go to the Build menu and select the Build option. You can watch the entire process live in the Build Results window that automatically pops open when you hit that Build option. I encourage you to expand all the line items in the Build Results window and inspect their contents, like so:







If any errors occur in your package project configuration, say a missing target app or dependency (e.g., license file), you’ll see them in this results dialog. The installer will be placed in the build folder next to my .pkgproj file. As you can see, Packages is a sophisticated software platform that covers all the bases.



Hopefully, the app you’re distributing will be well-accepted by your customer base. That probably means you’ll be updating your app as time goes by and you’ll be reusing your .pkgproj project file. My policy is to save and save often. I regularly save my work as I configure and build a new project and/or update an existing one. Just in case you aren’t the regularly-saving type, you’ll be prompted to save your new Packages project as soon as you hit that Build menu option.



Signing the Packages installer



In order for you to properly distribute your app so your installer runs without generating scary messages from the macOS Gatekeeper, you need to 1) sign and 2) notarize the installer. I already covered this process in great detail here on AppCoda several tutorials back. Please read the section in that tutorial entitled “Creating an installer to distribute the app,” including all its subsections. Then sign and notarize the installer you just built.



You’ve just successfully created your first macOS installer!



Running the Packages installer



Double click on the signed and notarized installer and you’ll see the following series of screens. AppNotaryAndDistrib.app, version 1.0, will be installed in your /Applications folder. Here are the steps the installer will walk you through:







Double-click on the app and in your /Applications folder and, voila, it runs:







Conclusion



Considering that a clear majority of macOS developers distribute and earn revenues on their apps outside of the Mac App Store, I would hope that I piqued your interest in Packages. You can’t beat the fact that Packages is freeware so, not only did you learn something new about macOS software today, you’re opening the doors to beneficial opportunities for yourselves. Enjoy!





Beyond App Sandbox: Going outside of the macOS app container
Andrew Jaffee — Fri, 19 Jun 2020 11:54:02 GMT



Did you know that a macOS app can read and write outside of its container when sandboxed? Did you know that a non-sandboxed macOS app has no container? Were you aware that you can sell and distribute non-sandboxed macOS apps without using the Mac App Store? Since the focus of most Apple development seems concentrated on iOS, many developers probably take the sandbox for granted. Some might not even be fully aware of the sandbox’s existence, especially in the case of iOS where all apps must be sandboxed. By ignoring the sandbox — and possibly macOS development entirely — developers run the risk of neglecting to understand a fundamental piece of Apple’s security infrastructure, and fail to take advantage of earning income from developing macOS apps.



Today, we’ll take an in-depth look at the sandbox’s benefits (and drawbacks) to both users and developers. We’ll discover, when merited, how to read/write outside the sandbox, and when and how to develop apps that are not sandboxed at all.



Editor’s note: If you are new to macOS development, you can check out our macOS tutorial series.





A series of tutorials



This is the second part in a three-part series of tutorials on sandboxing, signing, notarizing, and distributing macOS apps outside of the Mac App Store. In this tutorial I’ll give you in-depth insight into the sandbox and then build an app that, whether sandboxed or not sandboxed, can read and write outside of its container — and can be either sold and distributed outside the Mac App Store (MAS) or through the MAS, both with Apple’s blessings. I’ll demonstrate how you can build apps safe from malicious code and/or malicious exploitation even if you make exceptions to the sandboxing rules — or even if you turn off the sandbox entitlement completely.



You should definitely read my first tutorial in this series where I built a non-sandboxed app, discussed certificates, signed the app, notarized it, briefly talked about building an installer, signed and notarized the installer, and lastly covered distribution of the app installer.



Finally, in Part III, I’ll guide you step-by-step through the process of using the excellent freeware app Packages to create an installer for distributing your macOS apps outside the MAS. We’ll build an installer that has a splash page, installation instructions, a licensing agreement, and provides installation options for users.



What is an app sandbox?



Apple’s “App Sandbox Design Guide” is a bit outdated, stating:



An app that is not sandboxed has access to all user-accessible system resources–including the built-in camera and microphone, network sockets, printing, and most of the file system. If successfully attacked by malicious code, such an app can behave as a hostile agent with wide-ranging potential to inflict harm.



I say “outdated” because, since the advent of Mojave and especially Catalina, I’ve seen non-sandboxed macOS apps that, when trying to access system resources, get a system prompt asking if it’s OK, for example, to read/write data in the user’s ~/Documents folder. So we’ve defined non-sandboxed apps with my provisos; now let’s talk about sandboxed apps.



The app sandbox is meant to keep users safe from apps that contain malicious code or contain vulnerabilities that an attacker can exploit for malicious purposes. The sandbox protects users’ assets from damage or theft. Apple mandates app sandboxing in iOS app development and strongly recommends it, though doesn’t require it, for macOS apps. Apple describes their notion of sandboxing thusly:



Fine-grained restriction over access to system resources is the heart of how App Sandbox provides protection should an app become compromised by malicious code. Resolving such violations involves adding specific entitlements in Xcode corresponding to the capabilities your app needs.



Think of the sandbox as a very constrictive fence surrounding your app. Of course, an app would be useless if this fence was impenetrable. Apps are only useful if they can act on some type of input and produce meaningful output. A sandboxed app comes with its own file system and can solicit input from the user via a user interface. As iOS developers well know, a lot can be done within the sandbox, but notice that, especially soon after installing a new app, iOS intercepts and asks the user for permission for your app to interact with, for example, the microphone, the camera, Bluetooth, location services, etc. macOS apps used to be pretty much free of such constant micromanagement — until Mojave and Catalina debuted. Let’s briefly talk about a tangible attribute of a sandboxed app to help you fully appreciate the sandboxing concept.



Take a little time to review the file system created by macOS for each sandboxed app. After you run the sandboxed version of my sample app for the first time, look in ~Library/Containers for a folder named after the app’s Bundle Identifier, with the form com.yourDomain.AppNotaryAndDistrib. Compare that folder’s contents to those in your own user-level file system at /Users/YOUR_USERNAME, where my own is /Users/andrewjaffee. Notice anything similar? Different? What about the symbolically linked folders in my app’s container? Don’t just look at those folders, try double-clicking on some and see where you end up.



Remember the quote I posted above from Apple? They want us to start with very little access to system resources and then only request more resources on an as-needed basis. Let’s use a real project to explore our options for writing apps with varying degrees of access to system resources. Because of scope, time, and space constraints, I’ll confine the discussion of resources to the file system, but keep in mind that your vulnerable surface area includes Mac components like network connections, microphones, the camera, Bluetooth, etc.



The sample code



If you want to build a project yourself and follow along, then open up Xcode 11.x and create a new application based on the macOS App template. You can look at my storyboard and code for guidance. Or if you just want to follow along using my existing code, then open my “AppNotaryAndDistrib” project and walk through it while reading this article. You can download my sample project, built against the OS X 10.15 (Catalina) SDK at this link.



If you use my code, remember that you’ll have to use Xcode 11.x to configure the settings under TARGETS -> [TARGET_NAME] -> Signing & Capabilities -> Signing with your own Team, Bundle Identifier, Signing Certificate, and possibly Provisioning Profile.



Add automatic signing, remove sandboxing, and keep hardening



Since we’re exploring the app sandbox, let’s first configure my code not to use that security entitlement, i.e., we’ll remove the com.apple.security.app-sandbox entitlement via the Xcode UI. Most of you use the Automatically manage signing setting. Go to TARGETS -> [TARGET_NAME] -> Signing & Capabilities and make sure that setting is checked. Delete the App Sandbox capability (entitlement) and leave the default Hardened Runtime capability (build setting), like this, and notice my annotations in red:







Please read Part I of this series if you need a refresher on hardening.



Testing the code



When it comes to non-sandboxed apps, working inside Xcode lets you get away with things you couldn’t do outside of it. To make sure my code is actually functional to this tutorial’s specifications, you should have the requisite certificates and then clean, build, archive, sign (with Developer ID), upload, notarize the app, and drag it into /Applications in each section below where we play outside the sandbox. Sandboxed apps can be tested within Xcode or just run from the build folder.



Getting outside the app sandbox



There’s no doubt that malicious software is out of control. I worked with a government agency that was subject to 10,000 attacks on its IT infrastructure every day. It’s no surprise that Apple has increasingly emphasized macOS security, most notably with the advent of Mojave and especially Catalina. While sandboxing is not the only security mechanism available to you as a developer, it’s a starting point. Let’s look at your options for both sandboxed and non-sandboxed apps.



Going without sandboxing



Remember that we removed the sandbox entitlement when we started working with my sample project. You’ll have an AppNotaryAndDistrib.entitlements file in the Xcode Project Navigator, but it will be empty. I’m going to try to write a new text file to the user’s ~/Documents folder from an app without an entitlement for sandboxing. Here’s my code in ViewController.swift:



...
@IBAction func writeToFileBtnClicked(_ sender: Any) {

    // create the FULLY-QUALIFIED path to the file so
    // we're SURE we write OUTSIDE any container
    let url = URL(fileURLWithPath: "/Users/andrewjaffee/Documents/test.txt");

    // prepare text to write to the file
    let fileText = "This is text in the file";

    // try writing file to the non-sandboxed ~/Documents folder...
    do {
        try fileText.write(to: url, atomically: false, encoding: String.Encoding.utf8)
    }
    catch let error { // ... or find out why write fails
        print(error.localizedDescription)
        // write some code to recover from error
    }

} // end func writeToFileBtnClicked
...



So while this app didn’t come from the MAS and isn’t sandboxed, it is notarized, and therefore I can write a file to to the user’s ~/Documents folder, not a folder in the app sandbox. I get no special prompts asking for permission to write to the ~/Documents folder, though I swear it happens sometimes, maybe when an app is downloaded from the web and/or is installed using an installer? Here, it just works:







Using Full Disk Access



You may have installed apps from websites that, when run for the first time, ask you to go, on your Mac, to System Preferences -> Security & Privacy -> Privacy, unlock settings, and grant Full Disk Access to the app that prompted you. These are almost always un-sandboxed apps that need access to as much of your file system as is possible, like malware scanners, disk cleanup utilities, or file backup services. If you didn’t grant Full Disk Access, macOS would prompt you for access permission to folders a billion times, thus rendering such software almost useless. As the preference panel for Full Disk Access says, we’re talking about permission for:



…data like Mail, Messages, Safari, Home, Time Machine backups, and certain administrative settings for all users of this Mac.



You can make it easier on users by wiring up a button like in my sample app entitled “Select Full Disk Access.” It is wired to this @IBAction:



...
@IBAction func selectFullDiskAccessBtnClicked(_ sender: Any) {

    // we use an Apple-specific URL to open System Preferences
    let url = URL.init(string: "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles")
    // we present System Preferences for "Full Disk Access" to the user
    NSWorkspace.shared.open(url!)

}
...



As you see from the image below, my button and code does what it says:







Do not conflate or confuse Full Disk Access with sandboxing. If you grant Full Disk Access to a sandboxed app and it reads outside of its container, it will crash immediately, killed by the macOS sandboxd daemon. I’ll provide an example in the next section.



Going with sandboxing



By now, you understand the simplicity and convenience of using macOS apps that are not sandboxed. But suppose you are required to use sandboxing, for example, because you want to submit your app to the Mac App Store (MAS). Add the sandbox capability (and thus entitlement) to your app:







If you add the App Sandbox capability, a corresponding entitlement is added to the project’s configuration. Here’s the project’s .entitlements file after adding sandboxing:







    com.apple.security.app-sandbox
    





What happens if we press my sample app’s “Write to file” button after adding the sandbox entitlement? Give it a try. The app crashes, right? Let’s look in Console.app for (redacted) crash logging reported by the system process/daemon sandboxd as an ERROR of category Violation:



Sandbox: AppNotaryAndDist(7030) deny(1) file-write-create /Users/andrewjaffee/Documents/test.txt
Violation:       deny(1) file-write-create /Users/andrewjaffee/Documents/test.txt
Process:         AppNotaryAndDist [7030]
Path:            /path/to/folder/Build/Products/Debug/AppNotaryAndDistrib.app/Contents/MacOS/AppNotaryAndDistrib
Load Address:    0x100000000
Identifier:      com.yourDomain.AppNotaryAndDistrib
Version:         1 (1.0)
Code Type:       x86_64 (Native)
Parent Process:  debugserver [7032]
Responsible:     /path/to/folder/Build/Products/Debug/AppNotaryAndDistrib.app/Contents/MacOS/AppNotaryAndDistrib
User ID:         501
...



At its simplest, when an app is sandboxed, you can only write to and read from the folders in the app’s container. If you want to get down into the really nitty-gritty, you can also read from a list of “world readable [files], in certain directories, including /bin /sbin …,” and a few others, but those generally apply to special use cases.



Getting user intent for folders outside the sandbox



What if I determine the user’s “intent” by running my app, clicking my “Select folder” button, recording the folder the user picked (~/Documents), and then writing a file to that location? What I’m doing is saying, “Pick a folder (outside the container) where it’s OK for the app to read and write.” This is one of Apple’s methods for limiting the vulnerable surface area of the app to attack by malware. This requires some preparation via Xcode.



Go to TARGETS -> [TARGET_NAME] -> Signing & Capabilities -> App Sandbox -> File Access -> Type -> User Selected File and change Permission & Access from “None” to “Read/Write,” as show here:







This will add the com.apple.security.files.user-selected.read-write entitlement to your project. Then follow all the usual steps we’ve discussed to get a notarized app and run it. Now let’s click my Select folder button, choose the ~/Documents folder by browsing to it using the NSOpenPanel, highlighting the folder, and pressing the Select button. If we do all this before we click my Write file button, then macOS will let us write the test.txt file to the user-selected location, like so:







The app didn’t crash because the user told us that writing to ~/Documents was OK. Here’s the code behind my app’s Select folder button. It’s semantically clear and well-commented, so you shouldn’t have any problem reading it:



...
/**
 We encourage the user to select a folder, like ~/Documents,
 showing their "intent" to grant our app access to that folder.
 That directory is OUTSIDE of this app's sandbox. We do this
 in preparation for allowing us to reach out of our container.
*/
@IBAction func selectFolderBtnClicked(_ sender: Any) {

    let folderSelectionDialog = NSOpenPanel() // a modal dialog

    folderSelectionDialog.prompt = "Select"
    folderSelectionDialog.message = "Please select a folder"

    folderSelectionDialog.canChooseFiles = false
    folderSelectionDialog.allowedFileTypes = ["N/A"]
    folderSelectionDialog.allowsOtherFileTypes = false

    folderSelectionDialog.allowsMultipleSelection = false

    folderSelectionDialog.canChooseDirectories = true

    // open the MODAL folder selection panel/dialog
    let dialogButtonPressed = folderSelectionDialog.runModal()

    // if the user pressed the "Select" (affirmative or "OK")
    // button, then they've probably chosen a folder
    if dialogButtonPressed == NSApplication.ModalResponse.OK {

        if folderSelectionDialog.urls.count == 1 {

            if let url = folderSelectionDialog.urls.first {

                // if the user doesn't select anything, then
                // the URL "file:///" is returned, which we ignore
                if url.absoluteString != "file:///" {

                    // save the user's selection so that we can
                    // access the folder they specified (in Part II)
                    self.userSelectedFolderURL = url
                    print("User selected folder: \(url)")

                } else {
                    print("User did not select a folder: file:///")
                }

            } // end if let url = folderSelectionDialog.urls.first {

        } else {

            print("User did not select a folder")

        } // end if folderSelectionDialog.urls.count

    } else { // user clicked on "Cancel"

        print("User cancelled folder selection panel")

    } // end if dialogButtonPressed == NSApplication.ModalResponse.OK

} // end func selectFolderBtnClicked
...



I find this all very fascinating. Apple is making sure the user carefully considers what folders their already-sandboxed apps will be able to access. This is another tool in the fight to reduce or control the attackable surface area to which apps are exposed.



Persistent access outside of the sandbox



There’s a catch to the user showing their intent as in the previous section. The folder selected by the user is only added to your sandbox until the app is closed. If you were to write to that folder after reopening the app, the app would crash. There is a solution, but it’s really going beyond the scope of this tutorial. There’s not enough space and time to cover everything, so I leave you with Apple’s very detailed documentation on remembering user intent across app launches. In a nutshell, these docs show you how “you can retain access to file-system resources by employing a security mechanism, known as security-scoped bookmarks, that preserves user intent.”



Specify entitlements to specific Apple-defined folders



Remember how we obtained access to a folder of the user’s choosing outside of the app container in the section above entitled “Getting user intent for folders outside the sandbox?” Apple provides a simple mechanism for you to declaratively specify permanent access to user-level folders that everyone knows and loves. Go to TARGETS -> [TARGET_NAME] -> Signing & Capabilities -> App Sandbox -> File Access -> Type and change Permission & Access from None to Read/Write or Read Only for Downloads Folder, Pictures Folder, Music Folder, and/or Movies Folder. Of course, these correspond to the paths ~/Downloads, ~/Pictures, ~/Music, and/or ~/Movies, respectively. Here’s a sample configuration:







Using app groups for interprocess communication between your apps



It’s important to have options when creating software solutions to complex problems. Remember that two tutorials back, I wrote about how apps from the same vendor can share a common container, even if some of the apps are sandboxed, some of the apps are not sandboxed, all are sandboxed, or all are not sandboxed. It would be advantageous for you to read that tutorial.



Conclusion



The sandbox can be a powerful tool in the arsenal used to protect users from malicious code. In an ideal world, hopefully in the not-so-distant future, I would hope that the operating system and possibly smart hardware will be improved to reduce the vulnerable surface area of the app runtime environment. Then developers will be able to spend more time on solving problems for users rather than spending hours and hours trying to learn about sandboxing, app groups, security-scoped bookmarks, etc., ad nauseum. Users should be considered, too.



What type of experience is it for users to be constantly bombarded (interrupted) with prompts asking them to make decisions about things they might not even understand, like whether some app needs to access some directory or whether the app can install some “helper?”



I know I’m being hard on OS and hardware designers — being a bit of an armchair quarterback — but I already put a lot of time into considering how to make my code less vulnerable to malicious exploitation. My hope is for a division of labor, where the OS and hardware folks can strengthen IT security, developers can concentrate on creativity and problem sovling, all so we can all achieve our common goal: useful, creative, and safe apps.



That being said, I hope I’ve helped you understand the sandbox, or how not to use the sandbox, and I hope I’ve encouraged at least a few developers to give macOS development a chance, especially outside of the MAS, so that they can learn something new and make some extra money.





Beyond the Sandbox: Signing and distributing macOS apps  outside of the Mac App Store
Andrew Jaffee — Fri, 29 May 2020 12:48:40 GMT



Since the advent of OS X Mojave and especially Catalina and the requirement for app notarization, some of us old-time macOS developers are concerned that Apple will pull the plug on the apps that we distribute ourselves. Many of you have downloaded and installed macOS software directly from websites, i.e., not from the Mac App Store. Have you ever really considered it? 



You can’t download an iOS app outside of the App Store. Yes, I know about the Apple Developer Enterprise Program, but it only “allows large organizations to develop and deploy proprietary, internal-use apps to their employees.” How many of you have obtained tools like Skype, Zoom, Atom, or Sourcetree? These are all “third-party” apps not distributed through the Mac App Store. You probably downloaded Xcode from Apple’s developer portal (because downloading it from the App Store usually doesn’t work). 



I would like to share my experiences in developing and distributing macOS apps outside of the Mac App Store and show you how you can do it too. Today, I’ll help you understand how to navigate the rather convoluted process of signing and notarizing both an app and its installer. Apple’s signing and notarization process can be quite complex and the documentation is not that clear on the subject, especially for installers.



Editor’s note: If you are new to macOS development, you can check out our macOS tutorial series.






A series of tutorials



This is the first part in a three-part series of tutorials on sandboxing, signing, notarizing, and and distributing macOS apps outside of the Mac App Store. In this tutorial, we’ll build a non-sandboxed app, talk about certificates, sign the app, notarize it, briefly talk about building an installer, sign and notarize the installer, and finally cover distribution. In the second tutorial in this series, we’ll turn the sandboxing capability and entitlement on in my sample app and explore ways that users can still gain access to files and folders outside of the app’s container. We’ll also discuss the pros and cons of sandboxing and try to understand Apple’s reasoning behind providing loopholes for sandboxed apps. Finally, in Part III, I’ll guide you step-by-step through the process of using the excellent freeware app Packages to create an installer for distributing your app. We’ll build an installer that has a splash page, installation instructions, a licensing agreement, and provides installation options for users.



Advantages of staying out of the Mac App Store



There are several big advantages to distributing macOS apps outside of the Mac App Store. You have much more creative, design, development, distribution, financial, and feature-full options than you would by putting all your work at the risk of sometimes arbitrary rejection by Apple’s notoriously fickle and opaque app reviewers.



For example, you don’t have to sandbox your apps, giving you access to much of the macOS file system. Another good reason to avoid the App Store: you don’t have to follow Apple’s sometimes confusing and often draconian Human Interface Guidelines. Probably the best reason: you save lots of money!



Here’s a succinct list of the best reasons to distribute your macOS apps outside of the Mac App Store:



you get to advertise, distribute, and sell your app any way and any place you like;
you don’t have to pay Apple a 30%/15% fee for selling your apps or for subsequent “in app” purchases (you can call purchases from within your app anything you’d like to call them);
you don’t have to follow Human Interface Guidelines; and,
you avoid the coin toss of ending up with the disgruntled app reviewer who’s just having a bad day.



What is Gatekeeper and notarization?



Before we get started with the tactical discussion, let’s clarify the meaning and importance of what Apple calls “notarization.” There’s a quote from Apple describing Gatekeeper, positing a situation exactly as I’ll discuss herein, where:



… you download and install apps from the internet or directly from a developer, macOS continues to protect your Mac. When you install Mac apps, plug-ins, and installer packages from outside the App Store, macOS checks the Developer ID signature to verify that the software is from an identified developer and that it has not been altered. By default, macOS Catalina also requires software to be notarized, so you can be confident that the software you run on your Mac doesn’t contain known malware. Before opening downloaded software for the first time, macOS requests your approval to make sure you aren’t misled into running software you didn’t expect. …



My sample code



Let’s get started. If you want to build a project yourself and follow along, then open up Xcode (I’m using 11.2.1) and create a new application based on the macOS App template. You can look at my storyboard and code for guidance. Or if you just want to follow along using my existing code, then open my “AppNotaryAndDistrib” project and walk through it while reading this article. You can download my sample project, built against the OS X 10.15 (Catalina) SDK at this link. If you use my code, remember that you’ll have to use Xcode 11.x to configure the settings under TARGETS -> [TARGET_NAME] -> Signing & Capabilities -> Signing with your own Team, Bundle Identifier, Signing Certificate, and possibly Provisioning Profile.



I won’t be going into Swift coding specifics today as this tutorial is concentrated on distributing safe code outside the Mac App Store. We’ll concentrate on app configuration herein. If you stay with me, you’ll configure, build, sign, and notarize my app. Then you’ll configure, build, sign, and notarize an installer for my app. When you run the installer and then run my sample app, you’ll see this:







Let’s take just a few minutes to go over the code wired to the button in the center of my main window entitled “Select folder.” Remember that in Part II of this tutorial, we’ll be having a very in-depth discussion about how a user can grant a sandboxed app access to specific folders outside of its container. Keep that in mind. For now, let’s just say that, from my project’s NSViewController subclass, I’m using NSOpenPanel to enable the user to select individual folders:



...
@IBAction func selectFolderBtnClicked(_ sender: Any) {

    let folderSelectionDialog = NSOpenPanel()

    folderSelectionDialog.prompt = "Select"
    folderSelectionDialog.message = "Please select a folder"

...

    if dialogButtonPressed == NSApplication.ModalResponse.OK {

...
                    self.userSelectedFolderURL = url
                    print("User selected folder: \(url)")
...

    } // end if dialogButtonPressed == NSApplication.ModalResponse.OK

} // end func selectFolderBtnClicked
...



App signing and notarization



Most of you are familiar with building apps and submitting them to the iOS App Store or, in the case of this tutorial, submitting them for review and distribution to the Mac App Store. You also should know why apps must be digitally signed. If not, please take the time to read up on certificates and signing.



Preparing for app signing



I can’t cover all the prerequisite components, protocols, and methodologies required to sign and notarize your apps, as this article would turn into a rather lengthy book. Let me point you at some documentation that Apple has provided so that, for example, you can reproduce what I’m showing you in this tutorial on your own Macs. Please read “Signing Your Apps for Gatekeeper”, “Create, export, and delete signing certificates”, and “Distribute outside the Mac App Store (macOS)”.



Because I regularly develop, sign, notarize, and distribute macOS apps outside the App Store, I have certificates with the following types of names in my Mac’s Keychain, shown below. If you want to distribute outside of the Mac App Store, you’ll need to create and export the same type of certificates from your account on Apple’s developer portal and install them into your own Keychain, where TEAM_NAME is your own name or your company’s “Team Name,” and TEAM_ID is your/your company’s “Team ID,” from your portal’s account. He are the some of the relevant certificates I can see in my Keychain:



Developer ID Installer: TEAM_NAME (TEAM_ID)
Developer ID Application: TEAM_NAME (TEAM_ID)
Apple Worldwide Developer Relations Certification Authority
Developer ID Certification Authority



This is not an exhaustive list of all certificates you need for day-to-day development. These are just the ones most important for signing and notarizing apps and installers. It behooves you to burn the phrase Developer ID into your brain’s neural net. From Apple’s docs:



For software and applications that are downloaded from places other than the Mac App Store, developers can get a Developer ID certificate and submit their software for notarization by Apple. Digitally signing software with a unique Developer ID and including a notarization ticket from Apple lets Gatekeeper verify that the software is not known malware and has not been tampered with.



To get you started, here is a screenshot from Apple’s developer portal showing how you would create the certificates you need for distribution outside the Mac App Store. It shows the Certificates, Identifiers & Profiles section when you Create a New Certificate:







Once you create these certificates, you download and install them into your Mac’s Keychain.



Add automatic signing, remove sandboxing, and keep hardening



We’re going to diverge from from the default macOS app template while simultaneously leaving other settings as-is, re: sandboxing and hardening, respectively. Most of you use the Automatically manage signing setting. Go to TARGETS -> [TARGET_NAME] -> Signing & Capabilities and make sure that setting is checked. Delete the App Sandbox capability (entitlement) and leave the default Hardened Runtime capability (build setting), like this, and notice my annotations in red:







Many apps benefit greatly from having the convenience of accessing files/folders anywhere on your Mac, excluding protected system areas, so my sample app is not sandboxed. As for hardening, according to Xcode 11 help:



Hardened Runtime defends your application by preventing modifications to its code and provides fine-grained controls over what can run in your process. Hardening the runtime also prevents access to sensitive resources unless your application pre-declares its intent to use them, which reduces the attack surface by eliminating unnecessary access. These properties help prevent exploitation of your application and this capability is required for your app to be notarized. [My emphasis added.]



Building, signing, and notarizing



You all are familiar with cleaning and building apps. I’m not sure how many of you are involved in the signing of your apps beyond using Xcode’s automated certification process when uploading to the App Store. We’ll do some manual digital signing herein. We’ll walk through the process step-by-step below. Here’s an image you know well — Xcode’s Product menu:







Let’s Clean Build Folder, Build, and then Archive. The Xcode Organizer window will appear showing the archive you just created:







Click the Distribute App button as highlighted in red in the previous image. This will pop up the Select a method of distribution: dialog, where you’ll select Developer ID (with subtitle “Distribute directly to customers.”), like with the certificates I discussed above. Remember the significance of Developer ID. Click the Next button as shown in red in the next image:







The next step is the Select a destination: dialog, where you’ll select the Upload option (with subtitle “Send to Apple notary service.”), where you’ll click the Next button to, well, upload your app bundle to Apple for notarization, as shown in the following image:







Remember the significance of notarization. You’re sending your app to Apple for a safety inspection. Apple “scans your software for malicious content [and] checks for code-signing issues.”



Now you’ll see the Re-sign “[APP_NAME]”: pop-up, where APP_NAME should obviously be the name of the app we want to notarize. Here, it’s my sample app, “AppNotaryAndDistrib.” You’ll select Manually manage signing (with caption “Select certificates and profiles from your team.”), and then click the Next button:







We next get the Select certificate and Developer ID profiles: dialog, where your Team is already known, you set Distribution certificate: to a valid Developer ID certificate that’s in your Keychain as I discussed above, and we set the dropdown adjacent to my app’s name, specifying provisioning profiles, to “None.” I can select “None” because I didn’t add any capabilities to this app. (I removed sandboxing and since hardening is required, is there by default, is really a build setting, then it’s not considered a capability). Click the Next button:







Now we land on a screen entitled Review [APP_NAME].zip content:, where APP_NAME is my sample app, “AppNotaryAndDistrib.” You may ask yourself, “Why the .zip extension?” An app bundle is often going to contain a plugin or extension, though in this case it doesn’t, and remember that a bundle is a directory structure that often contains components that can be compressed, so zipping adds to performance. Also, the notary service needs to be able to scan one single, definable file. This is your chance to review your app before wasting time because you forgot something. You get to see entitlements, plugins, extensions, core app, team, certificate, provisioning profile, etc. When done reviewing, click the Upload button.







On the next screen, you’ll see some messages about handshaking with the Apple server(s), preparing content for upload, and a progress bar showing uploading status. When your app bundle has successfully been sent to Apple’s server, you’ll see this:







Now you wait… The length of time it takes for notarization depends on issues like how busy Apple’s servers are at the time and how large is your app bundle, but it generally only takes a few minutes. I don’t think I’ve ever waited longer than 5-7 minutes, and that was back when Apple first started requiring notarization on Catalina, and everyone was scurrying to get their 3rd-party apps inspected:







Click the Export… button and place the file in a folder of your choosing. I often save it straight to the /Applications folder, because I’m literally “installing” an app that’s ready for prime time. If I double-click on my newly-notarized app in /Applications, it runs immediately because it’s been notarized. Apple’s Gatekeeper looks at it and let’s it run. But that’s not how you should distribute your apps. We need to create an installer.



Creating an installer to distribute the app



It is beyond the scope of this tutorial to go into all the details involved in creating an installer. That being said, please come back in about three weeks and look at my posts here on AppCoda. I’ll provide a very detailed, step-by-step tutorial on using the freeware app Packages to make the installer used in this tutorial. I believe Packages is the best app for creating installation packages on Mac. Full disclosure: I have no personal or financial relationship or interest with Packages’ author, Stéphane Sudre. I urge you to use his app and, by doing so, support his efforts.



The best way for you to start learning about building installers using Packages is to download the app, read about it, poke around, start a new project, check out related resources, check out its technical specifications, and read some of the tutorials. Remember that in Part III of this series of tutorials I’m writing, I’ll be showing you exactly how to use Packages to build an installer for the app we’re discussing today.



Here’s a tip for my upcoming Packages tutorial: Your installer needs a “tag,” also knows as an “identifier,” just like your app has a Bundle Identifier. I used us.microit.pkg.AppNotaryAndDistrib. Notice how it starts with the reverse of my company website’s domain, again, just like your app bundle ID.



Here’s a brief look at how I add my sample app bundle, AppNotaryAndDistrib.app, to the Packages project I created to build a distributable .pkg installer:




/content/images/wordpress/2020/05/addAppToInstaller.mp4




After configuring and building my Packages project, I now have a fully functional installer which I named AppNotaryAndDistrib.pkg. Remember: I can’t distribute this installer because… it’s not signed OR notarized and Apple’s Gatekeeper will tell users that it may contain malicious content and that it’s from an unknown distributor. So what do we do? We sign the installer and then we notarize it. Believe it or not, this is not a simple process. So let me walk you through it.



Installer signing



You all should know that an installer needs to be signed with a valid certificate, right? It’s an application that installs another application on someone’s Mac and we don’t want anyone tampering with it. Let’s sign my installer using one of the Developer ID certificates I discussed earlier using the productsign command in Terminal, and check the output. This command has the form:



productsign --sign "Developer ID Installer: TEAM_NAME (TEAM_ID)" "ORIGINAL_INSTALLER_NAME" "SIGNED_INSTALLER_NAME"



Let’s run it with real arguments, like my company name (TEAM_NAME) and file names, except my TEAM_ID, which I’ve redacted as “ABCABCABCD”:



productsign --sign "Developer ID Installer: microIT Infrastructure, LLC (ABCABCABCD)" "AppNotaryAndDistrib.pkg" "AppNotaryAndDistrib_1.0_Installer.pkg"



Here’s the output from running the command:



productsign: using timestamp authority for signature
productsign: signing product with identity "Developer ID Installer: microIT Infrastructure, LLC (ABCABCABCD)" from keychain /Users/andrewjaffee/Library/Keychains/login.keychain-db
productsign: adding certificate "Developer ID Certification Authority"
productsign: adding certificate "Apple Root CA"
productsign: Wrote signed product archive to AppNotaryAndDistrib_1.0_Installer.pkg



Notice the last line in the output: You’ll find a new file, the signed installer, AppNotaryAndDistrib_1.0_Installer.pkg in the folder where you ran productsign. We can’t use this installer yet because it hasn’t been notarized. Are you ready for some pain, er, ah, fun?



Installer notarization



Because of the previous discussion, you know why we need to notarize our installer, but you probably don’t know how. It’s a doozy. Apple certainly didn’t make this easy. It’s all command line-based and very verbose. IMPORTANT: You’ll need your Apple ID and your installer’s “bundle ID,” i.e., us.microit.pkg.AppNotaryAndDistrib as we discussed above. If you use two-factor authentication with your Apple ID, you’ll need to use app-specific passwords. If you don’t want to send your Apple ID and password as clear text, you can use Keychain placeholders.



Open a Terminal window and follow along as I enter commands and review output. I’ll use placeholders for many of the commands’ arguments so as to redact my private information. We’ll start with uploading my installer to Apple for notarization:



xcrun altool --notarize-app --primary-bundle-id "us.microit.pkg.AppNotaryAndDistrib" --username "email@domain.com" --password "PASSWORD" --file AppNotaryAndDistrib_1.0_Installer.pkg



Terminal will hang a little while while your installer is uploaded but will come back shortly with the following output:



No errors uploading 'AppNotaryAndDistrib_1.0_Installer.pkg'.
RequestUUID = cadc5ae2-768a-4cee-8719-f977c422b1c6



Keep that RequestUUID because you’ll use it to check and track the notarization status of your installer. You can wait for an email that will go to your Apple ID, but let’s stick with the Terminal workflow. In a few minutes, you’ll run this command:



xcrun altool --notarization-history 0 -u "email@domain.com" -p "PASSWORD"



It will return immediately with a log of your notarization results — a list of all your submissions and their respective statuses. Look for the line item that has the RequestUUID I asked you to remember. It should be at the top of the list:



Notarization History - page 0

Date                      RequestUUID                          Status  Status Code Status Message
------------------------- ------------------------------------ ------- ----------- ----------------
2020-05-24 19:34:46 +0000 cadc5ae2-768a-4cee-8719-f977c422b1c6 success 0           Package Approved
2020-05-22 05:20:00 +0000 a7b855f8-986c-4df0-a938-24876c588b27 success 0           Package Approved

Next page value: 1590124800000



Yes, the first line item matches my RequestUUID. There it is: “Package Approved.” The second line item is from my app’s notarization that we performed with Xcode earlier in this tutorial.



Your installer is… almost ready. Note that if Apple hasn’t finished notarizing your installer, it will tell you that your request is pending. You can keep submitting the last command to determine if notarization succeeded or failed. What if notarization fails? Can you find out why? Well, yes kinda sorta.



You can get a much more detailed JSON report on notarization status. Let’s get started. There are two steps. First, enter this command in Terminal using the installer’s RequestUUID:



xcrun altool --notarization-info cadc5ae2-768a-4cee-8719-f977c422b1c6 -u "email@domain.com" -p "PASSWORD"



You’ll receive quite a bit of information:



No errors getting notarization info.

          Date: 2020-05-24 19:34:46 +0000
          Hash: 3a5ecc35c373ad872718c8c2c7a4efc21ac5ac3b2739c5e4bef995e910fcf851
    LogFileURL: https://osxapps-ssl.itunes.apple.com/itunes-assets/Enigma123/v4/d2/94/27/d2942733-d44b-5533-fae9-8bbf78d840ba/developer_log.json?accessKey=1590622884_2683968192308681510_zBw4%2BSVyZ%2Fwcy1nlvnkT%2Bo7LVAefv5uDiMG6cz80lAdMrL4mIBCUnhX37utPeGclAZ66U90RdNvhggbBlRF3tuVDJN13uOU3rrSTkLngKRiMDDW3bYcaiSZ2tMqzYBMWykmp%2Fcrs435%2ByIIWmW9E798Ql3Bd1yLBo%2FFDwxeBn8c%3D
   RequestUUID: cadc5ae2-768a-4cee-8719-f977c422b1c6
        Status: success
   Status Code: 0
Status Message: Package Approved



Focus on the Status, Status Code, and Status Message fields for now. As we already know, my installer notarization succeeded (Package Approved). If those three fields contain anything other than success, 0, and Package Approved, respectively, you can try to find out why your notarization attempt failed by visiting the LogFileURL in your favorite browser. Don’t get your hopes up too high. Apple hasn’t done the greatest job with its reporting on the results of automated inspections of installers. Still, this is all you can get, and sometimes an obvious mistake it brought to light.



Next up is the second and most important step in getting detailed notarization information. In our case, going to that LogFileURL will be somewhat entertaining, but it’s instructive for us to look at the JSON contents that is returned so we can examine its structure. I visited LogFileURL in Safari and here’s what I got:



{
  "logFormatVersion": 1,
  "jobId": "cadc5ae2-768a-4cee-8719-f977c422b1c6",
  "status": "Accepted",
  "statusSummary": "Ready for distribution",
  "statusCode": 0,
  "archiveFilename": "AppNotaryAndDistrib_1.0_Installer.pkg",
  "uploadDate": "2020-05-24T19:34:46Z",
  "sha256": "3a5ecc35c373ad872718c8c2c7a4efc21ac5ac3b2739c5e4bef995e910fcf851",
  "ticketContents": [
    {
      "path": "AppNotaryAndDistrib_1.0_Installer.pkg",
      "digestAlgorithm": "SHA-1",
      "cdhash": "72e859f50fddcd045091a2bb4ccd8d0bba94633b"
    }
  ],
  "issues": [
    {
      "severity": "warning",
      "code": null,
      "path": "AppNotaryAndDistrib_1.0_Installer.pkg",
      "message": "This archive is corrupt, and cannot be unpacked for analysis.",
      "docUrl": null,
      "architecture": null
    }
  ]
}



What you’re looking at is Apple’s attempt to inventory the contents of your submission and scan it for malicious content. I called it “entertaining” because, while status is “Accepted” and statusSummary is “Ready for distribution,” issues is “This archive is corrupt, and cannot be unpacked for analysis,” but notice it’s just a warning. The installer is not corrupt because I’ve tested it several times and it works great. I believe that Apple feels that it “cannot be unpacked for analysis” because my installer is signed with a valid certificate. I don’t want anyone tampering with my installer. DOH! Finally, note the ticketContents field. This has to do with “stapling” and we’ll discuss that in just a moment.



Installer stapling



Now that your installer is notarized, you distribute it to your millions of customers, right? When your customers download and run your installer, Apple knows via an Internet connection through Gatekeeper to allow your installer to proceed. But what if, for a variety of reasons, a customer’s Internet connection drops just as they’re running your installer? If Apple can’t be reached, Gatekeeper won’t allow installation. For just such occasions, Apple allows you to “staple” a “ticket” to your installer so that it runs, net connection or not:



xcrun stapler staple "AppNotaryAndDistrib_1.0_Installer.pkg"



Here’s to what the stapler tells us:



Processing: /Users/andrewjaffee/Documents/AppNotaryAndDistrib_1.0_Installer.pkg
Processing: /Users/andrewjaffee/Documents/AppNotaryAndDistrib_1.0_Installer.pkg
The staple and validate action worked!



We’ve got an installer — finally. Remember earlier that I test-dragged my sample app into /Applications to kinda install it? I’ll delete that now and then run my new installer. Looks what happens:







When I look in [/Applications], my AppNotaryAndDistrib.app has been installed. When I double-click on the app icon, it runs and works perfectly. I don’t get any warning prompts about “malicious” software.



You can post an installer like this one on your own website, advertise, and sell it, with the whole process being under your control. This option affords you the most control and the highest profits. You can also sell it through a third party, but that generally eats into your profits. The key takeaway here in that it’s your app under your control.



Mission accomplished.



Conclusion



Is notarization all about Apple protecting its customers from potentially malicious software, or is it really an attempt to force all OS X app development into the Mac App Store so the giant, trillion-dollar conglomerate can gouge you for enormous fees? My gut feeling is the truth is a mix of the two possibilities, probably 60/40 as Apple already has 100% control over the iOS ecosystem.



There’s no question that hacking, identity theft, purposeful and purposeless malicious software-based attacks are a huge and growing problem. Protecting people from such attacks is a noble cause and all developers should keep their users’ safety in mind when writing code. On the other hand, a free market and the open source phenomena have brought great wealth and knowhow to a world desperately in need of both.



I hope we can find a happy medium. I hope Apple keeps the macOS ecosystem open to third party apps. Be sure to come back for Part II and Part III of this series of tutorials!





Using App Groups for communication between macOS/iOS apps from the Same Vendor
Andrew Jaffee — Fri, 10 Apr 2020 00:30:00 GMT



Apple’s “app group” technology allows a collection of macOS (or iOS) apps from the same development team, developer, vendor, etc., to all communicate with each other, coordinate functionality, share resources, and minimize redundancies. Apple says this capability “allows the apps within the group to share Mach and POSIX semaphores and to use certain other IPC [interprocess communication] mechanisms among the group’s members.”



A word of caution, though: I’ve experienced inconsistent and erratic behavior with macOS app groups, especially on OS X 10.15, Catalina. As explained below, you may have to experiment with the app group ID format. Nonetheless, this tutorial will help those developers who submit macOS apps through the Mac App Store and those who distribute their apps outside of the Mac App Store by using 3rd Party Mac Developer Application and Developer ID certificates — including signing and notarization.



Today, I’ll walk you through the configuration and encoding of an app group whose members communicate through a shared instance of UserDefaults, more commonly known as user preferences. One app allows me (and my users) to pick a view background color — like a theme color — and write it to my shared UserDefaults. The other app can read that same shared preference and update its view’s background color to the currently saved value. This process is dynamic. As I change the theme color in one app, the other app can update its view’s background color immediately. 



We’ll build these apps and app group together in this tutorial. You can download the sample apps here. Here’s a video of the two apps coordinating together:







Probably one of the most intriguing aspects of app groups is that their commonly shared container, a mini folder and file system, transcends sandboxing. To highlight this attribute of app groups, one of my sample apps is sandboxed while the other is not.



App groups are a great feature, but unfortunately they’re not well-documented and therefore generally not well understood. For example, Apple has a section in it’s macOS developer documentation called “Adding an App to an App Group” which strongly implies that all you have to do is add an entitlement to your app’s project. In another developer document, Apple states “You control the groups that your app belongs to by manipulating its entitlements.” No mention is made of a very crucial step.



For awhile, adding an app group identifier to an Xcode project’s entitlements was sufficient in macOS to create and join an app group. Only iOS required that developers have an account with Apple and that they register the app group ID on the Apple Developer portal. That requirement now applies to macOS app groups, too, or does it? We’ll talk about this in-depth below.



If you have a number of related apps, especially ones you sell as part of an App Store bundle, then app groups might be for you. Keep in mind that apps can be members of more than one app group, too.



Let’s walk though all the required steps to create two macOS apps that demonstrate app groups — and note that almost all the content herein applies to iOS app groups.



Remember that you’ll have to provide your own Apple Developer account’s Team ID for creating your own app group ID and for using both of my sample apps.



Registering your app group’s ID



The first thing to do when creating an app group is to register an app group ID. Note that each of your apps can belong to, or not belong to, multiple app groups. Have a copy of your Apple Developer account’s Team ID ready, like copied into your clipboard. In the screenshots shown below, you’ll substitute your own Team ID where I’ve redacted my own. Let’s get started:



Login to your Apple Developer account;
Select Certificates, IDs & Profiles from the left sidebar or the center of the screen;
You’ll land on the Certificates screen by default, but select Identifiers from the left sidebar;
Click the dropdown labelled App IDs, like so:








Select the App Groups option from the dropdown;
Now that you’re on the Identifiers for App Groups page, click the plus-sign-inside-the-circle button;
On the Register a New Identifier page that comes up, the App Groups radio button will be auto-selected, like this:







Click the big, blue Continue button on the upper right-hand side of the same page;
You’ll land on the Register an App Group page where you’ll get ready to fill in the Description and Identifier fields;
Type in a meaningful Description and type/paste your Team ID into the Identifier field;
Notice that “group.” is prepended to the Identifier, and that I added some meaningful text, following Apple’s suggestion, like this:







Click the big, blue Continue button;
You can review your new app group ID, are given the chance to click Back to make changes, but we’ll select the Register button; and,
Now back on the Identifiers for App Groups page, you’ll see that you’ve created a new app group.



What if app group ID registration causes problems?



Remember that I called app group ID registration a “crucial step” above? Some people may experience problems with an app group ID of the form group.TEAM_ID.com.domain.MyAppSuite. If you find that you can’t sign your app or that your shared container is not created, then remove the group. prefix from your app group’s ID. So instead of an app group ID of the form group.TEAM_ID.com.domain.MyAppSuite, you’ll use one like this: TEAM_ID.com.domain.MyAppSuite.



The app group’s shared container



By definition, an app group is a collection of two or more apps. Whichever app that is a member of the app group, and runs before any of the other member apps run, creates what’s called the group’s “shared container.” It does this once unless someone deletes the container, in which case macOS recreates the container when it is next referenced by one of the group’s member apps. That container is a mini folder/file system like those that macOS provides for sandboxed apps. It’s a bit like the folder system that macOS builds for each user on a Mac or MacBook. Every shared container is stored in the macOS file system in a folder that has the same name as the app group ID, like group.TEAM_ID.com.domain.MyAppSuite. That folder is always stored in the macOS file system in ~/Library/Group Containers/. So the full container path is ~/Library/Group Containers/group.TEAM_ID.com.domain.MyAppSuite.



The app group has its own user preferences data store, accessible via a special instance of UserDefaults. These preferences are stored in a .plist file just like they are for all macOS apps. In this tutorial, those preferences are stored in the file at this path:



`~/Library/Group Containers/group.YOUR_TEAM_ID.com.domain.MyAppSuite/Library/Preferences/group.YOUR_TEAM_ID.com.domain.MyAppSuite.plist`



All apps in the app group have read and write access to the shared container, including access to the shared preferences.



A Word about my Sample Code



My code is semantically clear and well commented — but simple. You shouldn’t have any trouble reading it and understanding it. Remember that my code and this accompanying article are pedantic in nature. We’re talking about app groups, not about using MVC, robust error handling, testing, etc.



“FirstApp” – Creating an app that is part of an app group



Let’s walk through building my app group’s first app, ingeniously named “FirstApp.” It reads from and writes to the shared container. My FirstApp writes a color to the shared container’s preferences so that my “SecondApp” can read that preference, and thus we have interprocess communication.



Open up Xcode (I’m using 11.2.1) and create a new application based on the macOS App template.



Follow these steps in TARGETS -> Signing & Capabilities:



Tick the Automatically manage signing checkbox and then set the Team and Bundle Identifier appropriately;
Make sure to that you have the App Sandbox and Hardened Runtime capabilities;
Click the + button next to Capability and add the App Groups capability by dragging it in from the Library, like this:







Add your app group ID to the App Groups slot (it’s actually an array element in the .entitlements file).



Remember that your app group ID should look like this:



group.YOUR_TEAM_ID.com.domain.MyAppSuite



Note that I specifically sandboxed this app to show you that an app group app can read the shared container, which is outside of this app’s sandbox.



Everything you need to see is in the ViewController.swift file. Let’s briefly walk through the most important code in FirstApp — a few selected snippets.



Let’s examine how I write user-selected color values from my app’s NSComboBox to the app group’s shared preferences. The interprocess communication comes into play when my SecondApp, described below, reads that color preference. Notice that I’m getting a special type of reference to UserDefaults by calling its init(suiteName:) initializer, where the full definition is init?(suiteName suitename: String?), and note the optional return value. So here’s how I access user preferences and set a key/value for my app group by initializing UserDefaults with my app group’s ID:



...
/** 3a) Write user preference to shared container. */
func setPreferenceValue(_ value: Any?, forKey key: String, in appGroup: String) {

    // 3b) If we can access preferences to our app group...
    if let groupUserDefaults = UserDefaults(suiteName: appGroup) {

        // 3c) Write the value for the given key
        // to our shared container.
        groupUserDefaults.set(value, forKey: key)
        print("Wrote to shared user defaults.")

    }

} // end func setPreferenceValue
...



If you’re going to do something with your app group like store common files or maintain a shared cache, you’ll need to be able to get a valid macOS file system path to read from, and possibly write to, files/folders in the shared container. To get a URL to the root folder of your shared container, you use the containerURL(forSecurityApplicationGroupIdentifier:) instance method of FileManager, passing it your app group ID. Notice that instead of testing to see if a file exists first before reading from it, I proactively read from it using NSData and then check for a return value:



...
/** 4a) If you're going to manage and access common resources
 or assets in the shared container, remember that "It’s far better to
 attempt an operation (such as loading a file or creating a directory),
 check for errors, and handle those errors gracefully than it is to try
 to figure out ahead of time whether the operation will succeed."

 - returns: True if plist exists; false if it doesn't exist
*/
func sharedPreferencesPlistExists() -> Bool {

    var containerExists = false

    let sharedFileManager = FileManager.default

    /* 4b) "In macOS, a URL of the expected form is always returned, even if the app group is invalid, so be sure to test that you can access the underlying directory before attempting to use it." */
    let sharedContainerFolderURL = sharedFileManager.containerURL(forSecurityApplicationGroupIdentifier: appGroupID)
    // 4c) Now we build a standard path ("Library/Preferences/")
    // to the preferences data store file (plist). Note
    // the format of the plist's name.
    let sharedContainerPrefsPlistURL = (sharedContainerFolderURL?.appendingPathComponent("Library/Preferences/group.YOUR_TEAM_ID.com.domain.MyAppSuite.plist"))!
    // 4d) Try to read data from the preferences
    // plist file.
    let sharedContainerPrefsPlistData = NSData(contentsOf: sharedContainerPrefsPlistURL)
    // 4e) If the file exists...
    if let fileData = sharedContainerPrefsPlistData {

        // 4f) if the plist file has contents (bytes)...
        if fileData.length > 0 {

            // 4g) We know that the plist is valid.
            print(".plist file size: \(fileData.length)")
            containerExists = true

        }

    }

    return containerExists

} // func sharedContainerExists()
...



Upon clicking the Check for .plist button in FirstApp, the console shows:



.plist file size: 90
Shared plist created.



“SecondApp” – Creating another app so we have an app group



To restate what I would hope is now the obvious, “an app group is a collection of two or more apps.” SecondApp is, well, the other app that makes up my little app group. SecondApp reads a preference from the shared container. That preference for color is written by FirstApp. SecondApp sets its view controller’s NSView background color to the shared container’s preference and thus we have interprocess communication.



Open up Xcode (I’m using 11.2.1) and create a new application based on the macOS App template.



Follow these steps in TARGETS -> Signing & Capabilities:



Tick the Automatically manage signing checkbox and then set the Team and Bundle Identifier appropriately;
In this case, make sure to remove the App Sandbox capability;
Make sure the app has the Hardened Runtime capability;
Click the + button next to Capability and add the App Groups capability by dragging it in from the Library, like this:
[DragToAddAppGroupCapability.gif]
Add your app group ID to the App Groups slot (it’s actually an array element in the .entitlements file).



Remember that your app group ID should look like this:



group.YOUR_TEAM_ID.com.domain.MyAppSuite



Everything you need to see is in the ViewController.swift file. Let’s briefly walk through the most important code in SecondApp — just one selected snippet. Again, I’m getting a special type of reference to UserDefaults by calling its init(suiteName:) initializer with my app group’s ID as an argument. This is how I read the user preference for color that was set in FirstApp. I then change my main window’s view background color to the preferred color. Here’s the code:



...
func setViewBackgroundColor() {

    // 1) Get a reference to the shared user defaults for the
    // app group we created.
    if let groupUserDefaults = UserDefaults(suiteName: appGroupID) {

        // 2) Read the value for the "BackgroundColor" key stored
        // in our app group shared container's preferences
        // (user defaults).
        if let backgroundColor = (groupUserDefaults.object(forKey: "BackgroundColor")) as? String {

            // 3) Set the background color of our NSView to
            // the value we read from the our shared container's
            // preferences.
            self.view.wantsLayer = true

            self.view.needsDisplay = true

            if backgroundColor == "Red" {
                self.view.layer?.backgroundColor = NSColor.red.cgColor
            }
            else if backgroundColor == "Green" {
                self.view.layer?.backgroundColor = NSColor.green.cgColor
            }
            else if backgroundColor == "Blue" {
                self.view.layer?.backgroundColor = NSColor.blue.cgColor
            }
            else {
                self.view.layer?.backgroundColor = NSColor.gray.cgColor
            }

            print("Read background color, \(backgroundColor), from shared user defaults.")

        } // end if let backgroundColor =...

    } // end if let groupUserDefaults =...

} // end func setViewBackgroundColor()
...



Note that I specifically didn’t sandbox this app to show you that macOS apps don’t necessarily need to be sandboxed (especially those distributed via 3rd party signing) and that non-sandboxed apps can access their app group’s shared container.



Installing and distributing your macOS apps



Remember that if you want to install and/or distribute macOS apps like the ones I discussed here, you have two choices. You can go the 3rd party route and sign and notarize your apps outside of the Mac App Store or you can submit your apps for review by staying within the Mac App Store. macOS apps are more flexible in terms of distribution than iOS apps.



Conclusion



I hope you see the benefits that can be gained by use of app groups, whether it be in iOS or macOS. You can control and update your apps more easily by centralizing shared resources. You can eliminate redundancies. And you can get really advanced by using technologies like shared memory (as long as you remember to keep things thread safe). I could go on and on about the benefits of app groups, but I hope you’ll see that, for a relatively small price, you can get a high return on investment.





How to Use Git Pull Requests to Improve Code Quality and Developer Participation
Andrew Jaffee — Tue, 16 Apr 2019 00:01:23 GMT


Today, we’ll talk about a feature of several well-known Git tools that I prefer to call a “merge request,” but tends often to be referred to as a “pull request,” for example, on sites like GitHub and Bitbucket. Using Git-based merge requests tends to promote cooperation, participation, and collaboration among software team members while they’re developing code on mid-sized to large projects. By requiring each software feature or fix to be encapsulated into a formal and easily-identifiable “entity,” for lack of a better term, pull requests also lend a much-needed sense of structured flow to Git which is, from my perspective, inherently informal in its flow.
As with most aspects of software development, there is no one-size-fits-all model. While merge requests may work wonders on some teams, they may cause confusion with other groups of developers. Pull requests are overkill on very small projects.
Since I work in a full range of software development contexts, from large projects with hundreds of members to small projects with as few as 2 to 5 members, and since full-fledged adoption of this nascent technology is still gaining ground, in this article, just as in my client base, I’ll refer to merge requests throughout this article as “pull requests,” “PRs,” “merge requests”, and “MRs.” This will help readers become adaptive, capable of understanding software terminology regardless of where they’re working.
I myself only saw the start of widespread use of merge requests by my clients several years ago. Technically, they’re not that new, but practically, pull requests are still in the process of being adopted across the Git community.
Editor’s note: If you have no idea how to work with Git in Xcode, you can check out this tutorial.
An Overview of Git Pull Request (or Merge Request)
Merge requests provide us with two direct benefits:

Encapsulating software features or fixes into readily-identifiable containers
Promoting cooperation, participation, and collaboration by team members while they’re developing software code features and fixes.

When I say “container,” I mean that Git value-added service providers like GitHub, Bitbucket, and GitLab have all clearly defined what constitutes a merge request. They’ve also enabled development teams to apply unique and meaningful identifiers to each merge request. Communication tools that encourage team member collaboration are built into each merge request.
Generally, a merge request is made up of a distinct code branch that was created (split off) from whatever branch your team has identified as your project’s penultimate (best, correct, and truthful) publicly-releasable branch — many will immediately think master. The MR contains a pointer to the penultimate (master) branch. The service provider makes it easy for you to identify and compare code in your feature/fix branch with the penultimate branch. You are provided the ability to merge your feature/fix branch into the penultimate branch.
In fact, you should be provided with sophisticated merge tools. The merge request provides a central meeting place where team members can communicate specifically about the feature/fix branch. Commits/pushes to the feature/fix branch are tracked by the merge request.
Team members can easily see differences between the penultimate branch and the feature/fix branch. All team member discussions about the feature/fix branch are recorded in the merge request — and discussions associated with each distinct commit/push are shown as distinctly related to each distinct commit/push. Discussions and corresponding commits/pushes are stored in chronological order.
Hooks are provided so that each commit/push can be run through a continuous integration (CI) and continuous delivery and deployment (CD) pipeline. Hooks are provided so that other third party tools can be integrated with merge requests, for example, content management systems that allow meta data about source code, like design documentation, expected timelines, and feature/fix priorities, to be associated with the MR’s feature/fix Git branch.
Note: Because of the open source and intrinsically distributed nature of the Git source control management system, there is no one “official” definition and implementation of the Git merge request/pull request. If you are a key decision maker, I would urge you to shop around before committing to one particular vendor/service provider. For example, one of my clients had a continuous integration and continuous delivery/deployment integration that was a total nightmare.
Warnings and Recommended Reading
Let me break this to you gently: If don’t understand Git, get to know it before plunging into this article. Maybe that’s too harsh. Generally, I expect you to have at least intermediate working knowlege and proficiency in the use of source control management systems, especially Git. Specifically, this tutorial is meant for at least intermediate to expert Git users.
Here’s some recommended reading no matter how much of a Git expert you are. And remember, there really isn’t anyone who understands everything about Git, myself included.

“Learn Git with Bitbucket Cloud”, Bitbucket
“Gitflow Workflow”, Bitbucket
“A successful Git branching model”, Vincent Driessen
“Introduction to GitLab Flow”, GitLab

Best Practices
If you’re going to start using merge requests to add structure to your Git flow, start with a gentle introductory trial period. Pick just a few seasoned developers, especially ones whom understand Git and your Git tool of choice (i.e., GitHub). Assign them one feature or fix and see how it goes.
Whether starting with merge requests or whether they’re already part of your Git flow, try to keep the requirements for features and fixes simple and focused on as few issues as possible. For example, assignments shouldn’t be overly broad, like “add a settings screen with functionality.” Stay focused, like “allow the user to control location services in the preferences bundle; just use a UISwitch to enable or disable location tracking.”
With the Git flow model I personally prefer to use in mid- to large-sized projects, every feature and fix gets implemented in a separate branch. That branch is tracked, discussed, considered for merging, refined, and finally merged or rejected using a merge request.
Conventions
To keep things simple in this article, I myself will play all lead and development roles in the sample merge request that we’ll walk through. There will be the “team lead (me)” and the “developer (me).”
You know that in most real-life projects, there would be multiple development team members and multiple Git/GitHub user accounts. But here, when playing certain roles or changing roles, I’ll write things like “the developer (me) is about to commit and push a new feature branch to the remote” or “the team lead (me) is going to review and comment on the most recent merge request.”
A Simple Environment
In most mid- to large-sized projects, I encourage a Git branching model as described by Atlassian in this article. But my article here is didactic in nature. I don’t want to try to introduce and explain merge requests using a complex and heavy branching configuration to which I just linked. This has one master, one develop, and many feature, defect, and (tagged) release branches. I want you to easily read and understand my presentation. So we’ll discuss a project model in which there is only one master branch and possibly several feature/fix branches, and we’ll call this “master-feature.”
In this article, we’ll use the Git configuration provided by GitHub if you create a new default repository for your project — in other words, a Git configuration that starts with one default branch, master.
You should easily be able to extrapolate from my simplified master-feature configuration to the more complex master-develop-feature/defect-release-tag configuration. In fact, in some small projects, a master-feature/defect configuration may be all you need.
There’s an old idiom called “Occam’s Razor” which specifies that the simplest solution is generally the best one.
A Real-world Merge Request Scenario
To show you how a merge request works, I’ll create an Xcode project written using Swift with some basic functionality. Then I’ll implement a new feature in that project by creating a merge request and taking it through an entire, typical MR lifecycle.
As team lead (me), I’ll specify a new project requirement and assign implementation of that requirement to developer me. Then developer (me) will create a new Git feature branch, write some new code in that branch, and create a pull request using that branch. Developer (me) will assign my new merge request to team lead (me) for review. Team leader and developer will collaborate on refining the new feature branch code using the pull request as a means for communication. When team lead (me) is satisfied with refinements made to the feature branch by developer (me), team lead will the merge the refined feature branch into master for release. Both developer and team lead will work together — collaborate — using GitHub’s pull request support.
Generally, a “successful” pull request means that all participants have bought into the story behind a feature, have tuned or at least discussed the code for implementing that feature, and that the feature’s code is merged into the master branch for public release.
But “success” can also mean that the collective wisdom of the pull request’s participants have discovered that a proposed new feature or a fix doesn’t make sense for this project; that the feature/fix has fundamental design flaws; that the feature/fix would only make sense in the next version of the app, etc.
The sample project can be found on GitHub. The history of the pull request we’ll walk through in this article is available for you to inspect, like here and here.
Following along
You’ll learn more if you recreate all the steps I demonstrate in this article. You can do it yourself like I did, playing the roles of developer and team lead, or you can have even more fun and use an existing team configuration on GitHub — or set up a new team — so you and your compatriots can fill the various, different team roles that usually work together on a merge request (developers, team leads, reviewers, Scrum Masters, etc.).
However you do it, I encourage you to at minimum interact with the GitHub interface as I do here (like this).
Creating the New Repo
You should all be familiar with how to create a Git/GitHub repo for an Xcode project. If you’re not, please read this article.
By following these steps, you should have one default branch named master from which you release code to your customers.
First Draft Code
I created a simple Swift project with basic logic and user interface to provide the basis for a weather temperature checking app. It allows you to click on a button and get the current temperature in Fahrenheit (°F). I’ve mocked up a service for getting the current temperature. There are plenty of free APIs out there if you want to take this further and provide real weather info.
Here’s the first draft core code for the app:
import UIKit

class ViewController: UIViewController {

    @IBOutlet weak var temperatureLabel: UILabel!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        
        // Initialize - we haven't checked temperature yet.
        temperatureLabel.text = "-- F"
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }

    // Get temperature, format for presentation, and
    // display on screen.
    @IBAction func checkTempButtonTapped(_ sender: Any) {
        
        let temperature = getTemperature()
        temperatureLabel.text = String(temperature) + " F"
        
    }
    
    // Mock up a weather/temperature service.
    func getTemperature() -> Int {
        return Int(arc4random_uniform(99))
    }
    
}

In the course of managing this project, and since this was the first code written, team lead (me) reviewed this first version of our current temperature viewing app and found that the user interface/user experience (UI/UX) was not very exciting:

So, as team lead, I asked one of my developers to improve the UX with some animation.
Create a new feature branch
Developer’s first step is to create what’s called a “feature branch.” By putting new code into a separate branch, a development boutique can continue forward with app fixes, improvements, experimentation, etc., all without risking the code in the master branch. master is reserved only for app code in a state ready to be released to the public.
Many of you Git users know this already: To add a new feature or fix a defect, you pull from the latest develop or master remote to the corresponding local, and you branch off that latest local, giving the branch an appropriate name. Then you start working on the defect or feature independent of both the local and remote develop or master branches.
$ git branch -a
* master
  remotes/origin/master

$ git branch -r
  origin/master

$ git checkout -b FEATURE-add-animation
Switched to a new branch 'FEATURE-add-animation'

$ git push -u origin FEATURE-add-animation

Total 0 (delta 0), reused 0 (delta 0)
remote: 
remote: Create a pull request for 'FEATURE-add-animation' on GitHub by visiting:
remote:      https://github.com/iosbrain/MergeRequestDemo/pull/new/FEATURE-add-animation
remote: 
To https://github.com/iosbrain/MergeRequestDemo.git
 * [new branch]      FEATURE-add-animation -> FEATURE-add-animation
Branch 'FEATURE-add-animation' set up to track remote branch 'FEATURE-add-animation' from 'origin'.

Notice that I immediately pushed my new local feature branch to origin to create a remote version that tracks the new local. Some may argue that this is an unnecessary step because I haven’t made any changes to my new feature branch yet. Those people may be right but, for the purposes of this article, I wanted you to be able to see that other team members can now see my new feature branch on the GitHub web interface.
Local and Remote Versions of the Feature Branch
Here’s GitHub showing the new feature branch:

Here’s GitHub showing all project branches:

Here’s GitHub showing detail on all project branches:

Here are some Git commands for inspecting all project branches from Terminal, seeing the current branch, and for switching branches:
$ git branch -a

* FEATURE-add-animation
  master
  remotes/origin/FEATURE-add-animation
  remotes/origin/master
  
$ git branch -l

* FEATURE-add-animation
  master
  
$ git checkout master

Switched to branch 'master'
Your branch is up to date with 'origin/master'.

$ git checkout FEATURE-add-animation

Switched to branch 'FEATURE-add-animation'
Your branch is up to date with 'origin/FEATURE-add-animation'.

$ git branch -r
  origin/FEATURE-add-animation
  origin/master

First Version of the New Feature
Developer (me) was assigned the task of spicing up the temperature app’s UX. I added the following code to branch FEATURE-add-animation:
...
    // Get temperature, format for presentation, and
    // display on screen.
    @IBAction func checkTempButtonTapped(_ sender: Any) {
        
        temperatureLabel.alpha = 0.0
        
        UIView.animate(withDuration: 2.0) {
            
            self.temperatureLabel.alpha = 1.0
            let temperature = self.getTemperature()
            self.temperatureLabel.text = String(temperature) + " F"
        }
        
    }
...

As the developer, I then committed my new code and pushed it to the remote FEATURE-add-animation branch:
$ git add MergeRequestDemo/ViewController.swift

$ git commit -m "Added some animation."

[FEATURE-add-animation 2b34e33] Added some animation.
 1 file changed, 8 insertions(+), 2 deletions(-)

$ git push origin FEATURE-add-animation

Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 462 bytes | 462.00 KiB/s, done.
Total 4 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To https://github.com/iosbrain/MergeRequestDemo.git
   40333c3..2b34e33  FEATURE-add-animation -> FEATURE-add-animation

Now everyone on the project can see this change. If other team members go to the project’s main page on GitHub, they can view and click on the branches tab:

Then they’ll see that developer me has updated FEATURE-add-animation:

Notice that GitHub emphasizes that developer me has added new code to FEATURE-add-animation by visually presenting the fact that my feature branch is now “1 commit ahead of master.”
What to do with the New Feature Branch
What does a team without a well-defined Git flow do now? Does developer email team lead to ask that the feature branch be approved and merged into master? What if there were a way to highlight the fact that branch FEATURE-add-animation should be discussed by some or all team members to elicit technical input and creative input, and ensure that the new branch’s code adheres to standards, etc?
There is a way to get other team members involved. We can do so by having developer me create a merge request, or as it’s called on GitHub, a pull request.
Creating a Merge Request
Developer should announce to team lead (and others on the team) that I’ve taken a stab at encoding animation in the app. I do this by using a feature supported by value-added Git software suites like GitHub, GitLab, or Bitbucket. From GitHub:
Create a pull request to propose and collaborate on changes to a repository. These changes are proposed in a branch, which ensures that the master branch only contains finished and approved work.
Pull requests can only be opened if there are differences between your branch and the upstream branch. You can specify which branch you’d like to merge your changes into when you create your pull request. …
Let’s go to GitHub and walk through this process. I like to start this process on the branch overview page, similar to the flow we used above, like so:

Developer (me) will push the “New pull request” button next to my feature branch, as shown in the previous image. Since this is a new merge request, the first thing I do is select my feature branch and set it to be eventually merged into master. After all, master is the branch from which my hypothetical team does its releases. Note that GitHub’s documentation states:
When thinking about branches, remember that the base branch is where changes should be applied, the head branch contains what you would like to be applied.
Besides making sure I’ve selected the proper base and head branches, I can edit the title for my MR (which has been pre-filled with my last commit message) and add detailed commentary if I want:

Before hitting the green “Create pull request” button, I should consider to whom I’ll assign this MR for review and possible further coding. Remember that the purpose of MRs is “to propose and collaborate on changes to a repository”. Developer is going to select team lead as an “Assignee.” In terms of overall Git flow, generally I like to let the team lead decide if she/he wants to just merge the new feature as is, send it back to developer for changes, ask developer questions, ask others for input, reassign the branch to another developer, etc.:

Now press that “Create pull request” button.
Responding to Merge Requests
Because merge/pull requests have become so important to the workflow of numerous software development shops, they are made obvious on sites like GitHub. In fact, the “Pull requests” tab is the first tab you’ll probably notice when navigating to the GitHub site:

If you’re working on an active GitHub project, you’re going to be loading the remote repo’s home page frequently, and it’s hard to miss the “Pull requests” tab. Clicking on it regularly is a best practice for you to see what’s going on with your project:

Clicking “Pull requests” shows me an overview of the project’s MRs:

What a list of Merge Requests can Tell me about a Project
Clicking the “Pull Requests” button or tab on GitHub will show me all MRs assigned to me for review, ones where I should respond to comments, ones I’ve been asked to review, or ones I’ve been assigned to work on, among other things. Also shown are essentials like how many MRs of mine are currently in process (“Open”) and a history of previous MRs (“Closed”). The closed MRs can often be very helpful in remembering features or defects I’ve worked on — and I can even look at code I wrote, and diffs, and discussions elaborating on the decision-making required to encode, for example, a story, and that discussion comprises a project history, so that I can remember why I coded a certain feature a certain way for whatever reasons. That history may also show me a something like a key algorithm that is demonstrative of the app’s core purpose.
But history goes even deeper. I can look at MRs assigned to specific developers and determine essential metrics on say, which developers turned stories into features the fastest, which developers delivered the highest quality code, which developers required the most help and took longest to encode features/fixes, and even which developers (or other team leads) provided the highest quality feedback over time.
Inspecting your Pull Requests
Here, I have only one pull request, but in a typical project, I’d have several or more likely, many assigned to me:

I click on my MR to look at its details. When working with clients whose Git flows are based around the merge request model, I check my MRs frequently — whether on GitHub, GitLab, Bitbucket, etc. On GitHub and most all other similar sites, I can get a lot of good information by examining an MR assigned to me:

Immediately obvious to me is the fact that this MR is still “Open,” I can see a chronological history of events, and perhaps most importantly, the phrase “iosbrain wants to merge 1 commit into master from FEATURE-add-animation” tells me a lot. Who out there knows how important this statement should be to any team lead or developer? This is all great info. Let me mention a few things that you can look into on your own. Scroll down the page a bit and you’ll see two things I’d like to highlight:

Notice the phrase highlighted at the top of the image. That’s telling developer me that I can commit and push from FEATURE-add-animation as many times as necessary to address the concerns of team lead me or other team members.
Now focus on the section of the image that I highlighted mentioning the fact that “Continuous integration has not been set up.” You’ll probably end up in a Git flow where CI/CD has been set up. Then you’ll find out whether your current branch’s commits/pushes made it through continuous integration. CI/CD is beyond the scope of this simple tutorial, but you should read up on the topic.
Notice that the MR itself has a menu bar. Let’s click the “Files changed (1)” tab:

As you might expect, that tab shows, well, changes to source files, but most importantly, diffs so team members can see the changes made by developer me to the code:

It doesn’t get much better than this. By using MRs, we are dividing and conquering a project into manageable, logical, and focused pieces of code, source control flow, standard operating procedures, etc.
Discussing the Code
In this section, we’ll cover one of the most important features afforded by merge requests: The ability to tap into your development team’s collective knowledge and get feedback about code written in the branch attached to the pull request.
I’m team leader right now. Because I’m working by myself in my own GitHub account, I can only ask for feedback from myself, but that doesn’t help you readers out there.
If this were a particularly complex merge request and I needed or wanted advice from other people on my team, I want to click on the “Conversation” tab and concentrate on the column on the right-hand side of the screen:


If this were a more sophisticated feature, I could ask for input from other developers, other team leads — perhaps someone on the creative side, like a UI/UX specialist, or someone in management. I can assign reviewers and kick off a formal review process. I strongly encourage you to look over the links I just provided on formal reviews. This is a means of getting feedback on the merge request from almost anyone with access to your GitHub project.
Say I click the “Files changed (1)” tab again. By looking at the code and asking the developer me for a demo, I call tell that the animation is OK, but not good enough for me:

One way to communicate to the developer, or other team members, is to leave comments in the pull request’s code (and diff) view. I can place comments on each line of code. Team lead is going to tell developer what I think about her/his solution and ask for changes:

You see how I was able to start a comment on a specific line number in the relevant code branch. I can get the attention of the developer by using the @ key-character, which autocompletes to a matching team member — in this case, developer me. Here’s the full comment that team leader me left for developer me:

If all your team’s GitHub notification settings are configured properly, developer, team lead, and other team members should receive a copy of this comment. The developer and team leader and others can go back and forth trading comments as long as they need to, and an audit trail of the conversation is archived in the MR.
As general practice, after team lead is satisfied with a round of commentary, I would now set the “Assignees” back to developer (me), thus sending the code back to the programmer to make the changes I elucidated in my comments.
Note: I’m going to remove myself as the “Assignee” now just so I can show you how team lead me would assign this merge request back to developer me.
Select developer (me) as one of the “Assignees” (on a team, I would probably use auto-search and autocomplete):

I emphasize again that the developer can make code changes and commit/push them to FEATURE-add-animation, the team lead can review those changes and ask for more changes, this cyclical process can go on as long as necessary, and that at some point the developer will write code that meets the team lead’s expectations.
Remember that we can go to the GitHub “Files changed (N)” tab and compare the master and FEATURE-add-animation branches to see how working code has progressed so far.
The purpose of a merge request is to get more people involved in the development process so that they can spot potential problems (like logic errors or usability problems), ensure that project protocols are followed (like code style/formatting rules), and once in awhile, someone comes up with feedback that is truly inspirational and changes the whole course of the project.
Final Version of the Feature
Developer saw team lead’s comments on the merge request. First, I make sure I’m in my FEATURE-add-animation branch and then I make the following code changes as per team lead’s comments:
...
    @IBAction func checkTempButtonTapped(_ sender: Any) {
        
        let temperature = getTemperature()
        let temperatureString = String(temperature) + " F"
        
        UIView.animate(withDuration: 2.0, animations: {
            self.temperatureLabel.alpha = 0.0
        }) { (success) in
            UIView.animate(withDuration: 2.0, animations: {
                self.temperatureLabel.alpha = 1.0
                self.temperatureLabel.text = temperatureString
            })
        }
        
    } // end func checkTempButtonTapped
...

Developer inspects my final animation:

I then commit and push my latest changes into FEATURE-add-animation.
$ git status
On branch FEATURE-add-animation
Your branch is up to date with 'origin/FEATURE-add-animation'.

Changes not staged for commit:
  (use "git add ..." to update what will be committed)
  (use "git checkout -- ..." to discard changes in working directory)

    modified:   MergeRequestDemo/ViewController.swift

no changes added to commit (use "git add" and/or "git commit -a")

After testing my code (and functional and UI testing), it’s ready to commit and push my code.
$ git add MergeRequestDemo/ViewController.swift

$ git commit -m "Added fade out animation of old temperature. Then animated in new temperature."

[FEATURE-add-animation dca55ac] Added fade out animation of old temperature. Then animated in new temperature.
 1 file changed, 10 insertions(+), 7 deletions(-)
 
$ git push origin FEATURE-add-animation
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 545 bytes | 545.00 KiB/s, done.
Total 4 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To https://github.com/iosbrain/MergeRequestDemo.git
   2b34e33..dca55ac  FEATURE-add-animation -> FEATURE-add-animation

Since developer has pushed the latest code, I’ll want to set the “Assignees” on the pull request back to the team lead. We’ll see later that my latest changes are tracked by GitHub via the pull request.
Reviewing code one final time
Team lead will want to review the last commit by developer, check for any comments I added to the MR as developer and team lead may want to ask developer some questions (like “How did testing go?” — or… “Where’s your unit test!” 😜). Team lead could also grab the FEATURE-add-animation branch and run the code myself. So could other team members.
Team lead (me) will be notified by GitHub that developer (me) made changes to the code in the MR. I will use the MR interface to review the new code. I already showed you how to navigate the MR screens on GitHub. We’ll look at a couple of those screens now.
The main “Conversations” screen for this particular merge request will show a chronological summary of what’s happened during the lifetime of the request:

Most of this is self-explanatory. Notice I’ve highlighted some sections of the screen and numbered them “#1” and “#2.” Team lead clicks on #1 first. We’ll discuss that in a moment, but let me just plant this seed in your head: When I scroll further down the page, I see this:

See that big green “Merge pull request” button that I’ve marked “#3?” We’ll also discuss that soon.
Discussion of #1, #2, and #3 — then merging
When I get notified about a pull request like this, team lead clicks on the link in #1 first. The screen section marked #1 represents the last action performed on this MR (developer me’s last commit/push). GitHub takes me to the following screen:

I can see the changes that developer (me) made to satisfy team lead’s last comments on this MR. Those comments are shown in the middle of the screen. Let’s assume that team lead is satisfied with the code and that I’ve asked developer to show the app running with FEATURE-add-animation branch code. Now we’re getting to the point of resolving a merge request, but wait…
Let’s not forget my annotation labelled #2. If team lead was not satisfied at this point, I could ask developer for more changes via another comment. Developer could go off and write more code and then commit/push. Then team lead could review the new code and… You now see how this could go on for awhile. Complex merge requests often take serious time. Anyway, back to where we were in the last paragraph…
The first thing I want to do is type in a final comment and click the “Resolve conversation” button. Typing a comment is optional, but good practice. Note that in a larger pull request, there can be multiple conversations that I’d need to resolve. Here’s what team lead me did:

I now go to the “Conversation” tab and scroll down to what I showed you in the previous section: the image annotated with the #3. Let’s say the team is ready to move the code in this MR into production. So I click that big green “Merge pull request” button. If there were merge conflicts, of course team lead me would resolve them before merging, but this screen says:
This branch has no conflicts with the base branch

Merging can be performed automatically.
To confirm the merge, GitHub shows me this:

Finishing up
The master branch now contains the code that was requested to be written by team lead me with my directive to developer me to spice up our team’s temperature app with animation. It’s up to the team and/or project standard operating procedures as to whether to save or delete the feature branch (FEATURE-add-animation), including the remote and possibly many local copies. I usually keep feature or defect branches around for awhile, but clean them up eventually. The code contained in such branches can be useful. You’ll understand when you start using merge requests.
Now anyone who pulls master or creates a new feature or defect branch will be getting the latest code with the desired level of animation:

Conclusion
Before merge requests, Git flows across the software industry tended to vary widely. They still do vary, and variety is good, because there is no “perfect” flow that fits all projects and organizations.
But by creating a formal flow by which, for example, developers can pick Scrum-based stories or defect reports and start working on them and tracking them each with a specific merge request, we’ve come a long way in reining in the chaos that more informal Git flows can engender.
If you’re working on a mid- to large-sized project that has no formal Git flow, I would suggest you look at merge requests.
Suggested reading
Here are some great articles you can read to help you get up to speed on merge requests:
https://docs.gitlab.com/ee/user/project/merge_requests/

https://www.atlassian.com/git/tutorials/making-a-pull-request

https://help.github.com/en/articles/about-pull-requests

https://help.github.com/en/articles/creating-a-pull-request

https://help.github.com/en/articles/viewing-deployment-activity-for-your-repository

https://help.github.com/en/articles/merging-a-pull-request

https://help.github.com/en/articles/about-required-status-checks

https://help.github.com/en/articles/closing-issues-using-keywords

https://help.github.com/en/articles/requesting-a-pull-request-review

https://help.github.com/en/articles/about-pull-request-reviews





How to Use Xcode Instrument to Optimize Your Swift Code
Andrew Jaffee — Tue, 30 Oct 2018 11:20:57 GMT


I still run across curmudgeons who flat out reject techniques like object-oriented programming (especially inheritance and polymorphism), protocols and protocol-oriented programming (especially composition), generics, and closures. On a conscious level, the curmudgeons usually reject these technique because of their supposed “massive” performance cost. On a subconscious level, the curmudgeons don’t understand these technologies. So do we give up all hope or do we accept the fact that compiler designers have come up with brilliant optimizations that ameliorate the use of such high-level technologies? We should believe in Swift’s compiler designers. Do we realize that there are great tools like Xcode Instruments that help us find awkward implementations of these techniques and give us the opportunity to come up with our own optimizations? Yes.
There are costs to these high-level features, but I would argue that in most cases, language compiler optimizations, operating systems enhancements, and faster hardware (like solid state drives and multi-core processors), make up for the costs. Sure, once in a while you’ll have a use case where advanced code features don’t pay off, i.e., code is badly written or not used for the intended purpose.
Most of the time, these advanced features save software development boutiques enormous amounts of time and resources. Advanced language features usually let us do more by writing less and very expressive code. Time is saved because team members can easily read each other’s semantically clear code. Since the code is readable and logically organized, it can be extended, reused, debugged, and maintained easily.
But by goodness, nobody’s perfect, not even me ;-). Software keeps getting more and more complex. Users keep demanding more, better, and faster features. Problems will occur. Some apps are so slow that people just delete them.
Do we find out why our apps are so slow by using just print statements and breakpoints? I hope not, but I’ve seen more than a fair share of Stone Age “optimization” techniques. No. We turn to the darn good tools that already come bundled free with Xcode.
Using Xcode Instruments to Identify Performance Problems
The Xcode Instruments’ Time Profiler template is the best template to start with when looking for app performance problems and/or determining how to improve performance. According to Apple, the Time Profiler template “performs low-overhead time-based sampling of processes running on the system’s CPUs.”
We’re going to use the Time Profiler to analyze the performance of my sample app’s code. Please download it from GitHub. In simplest of terms, Time Profiler collects information about your app while it’s running, determines how long each of your functions takes to run, and also figures out the percentage of CPU cycles each of your functions is using. It gathers the same data about iOS SDK functions. The percentage of CPU cycles from 0% to 100% at each sample point is shown over time on a graph called the “timeline” or “track.” There are multiple tracks. The top track aggregates all the data from all individual thread and CPU core tracks. The Time Profiler is a very powerful tool as it shows your app’s performance in real time, thus reflecting surges or lulls in CPU usage. We’ll walk through an example.
Your Profiling Environment
Before we begin, realize that, when profiling your code, especially when comparing two different approaches to the same problem, it’s imperative that you compare apples and apples, not apples and bananas. In other words, if you’re profiling an algorithm and trying to optimize it, you want to use the same device (or simulated device) with the same configuration.
When I compared the performance of functions showEmployee() and show() from my sample app in the demo below, I ran and profiled each method on the same iPhone 8, with the same configuration. When preparing my iPhone 8 for profiling, I first shut down all running apps. Since the code I was studying didn’t involve any type of connectivity, I shut down WiFi, Bluetooth, and cellular. Of course, if you’re profiling networking code, like communications with a REST API, you’ll need to have WiFi or cellular.
The key takeaway here is that you want to minimize, preferably eliminate, the number of (random) variables that may skew Time Profiler analysis and results. Imagine if you’re profiling an algorithm and your iPhone starts up Background App Refresh… Your analysis may be tainted — artificially skewed so that you believe your algorithm is slower than it really should be. Imagine if you profile one algorithm when nothing is running in the background on your iPhone, profile a similar algorithm while your iPhone performs a background refresh, and then compare the two results (data sets). Is this a meaningful comparison?
Using Instruments’ Time Profiler Template
Let’s walk through the profiling of my “Optimizing Swift Code” sample project. Open the project in Xcode. Click and hold the Build and then run the current scheme button until you see the down arrow. Click the down arrow and then select the Profile option from the context menu, like so:

The Choose a profiling template for: dialog will open. Select the Time Profiler template and click the Choose button:

The Time Profiler template window will open, ready to sample and render performance data of my “Optimizing Swift Code” app. I’ll refer to the following image as the “map:”

I’ve numbered my annotations to correspond with the general sequence of the workflow you use to analyze app performance. I’ll also refer to these annotations in the following discussion.
To begin profiling, press the record toggle button — what I call the “1 – Start/Stop” (map) button:

When you feel you’ve sampled enough data, press the “2 – Pause” button or “1 – Start/Stop” toggle (see map). Now it’s time to examine the profile (sample data collected). Since I’m running code in the background via GCD, I can scroll down to see activity per thread and per core:

Analyzing Your Profile
Now it’s time to analyze the recorded profile data. You generally start by clicking into an area of activity on the track/timeline or by highlighting a “slice” of the timeline. Remember that you can not only look at the top/aggregate track, but also inspect each thread or core:

When you click on a single time/data sample or highlight a slice, the corresponding code executing at that time of that selection is shown in what I annotated on my map as the “4 – Heaviest Stack Trace,” “5.1 – Stack trace of method names (tree),” and “5.2 – Measures of CPU used.” You all should know that functions are pushed on and popped off the stack, that functions calling other functions builds a stack trace, and that “Heaviest Stack Trace” means high CPU usage (cycles).

IMPORTANT NOTE: If you’ve found that there’s some bottleneck in your app, but you don’t know where exactly it resides in your code, look for:

– functions in the “Heaviest Stack Trace” pane; and/or,

– thick, high, and blue activity on the top track, or possibly in thread and core tracks.

I’m interested in two regions on the timeline. Why? because they show non-trivial CPU activity:

After I’ve selected a slice of the timeline, here “Region 1,” I first look at the “4 – Heaviest Stack Trace” pane (see map) for method names I recognize with a person icon next to them. The person icon indicates my code; other icons represent iOS calls. The “4 – Heaviest Stack Trace” pane shows me code with high CPU usage.
In this case, I also expected to see certain functions at startup; code that I wrote. I know my own code. I clicked on one of my method names in “4 – Heaviest Stack Trace” so that its stack trace and symbols (function/class/struct names) would be shown in the “5.1 – Stack trace of method names (tree)” and “5.2 – Measures of CPU used” pane (see map):

Notice all the detail. And notice that I can expand a symbol (function) name to see everything being called by it. If you go into my “Optimizing Swift Code” project, you can see how the Organization.createEmployees() method is called at app startup. Look in project file Organization.swift and you’ll find this code:
import Foundation

class Organization {
    
    var employees: [Employee] = []
    
    func createEmployees() {
        
        for count in 1...count {
            
            let employeeID = "employee" + String(count)
            let age = Int(arc4random_uniform(47)) + 18
            
            let employee = Employee(firstName: "first"+String(count), lastName: "last"+String(count), age: age, streetAddress: String(count)+" Main St", zip: "90210", employeeID: employeeID)
            
            employees.append(employee)
            
            print("Employee \(count) created.")
            
        } // end while
                
    } // end func createEmployees()
    
} // end class Organization

But… I don’t have to switch to Xcode to look at my code.
If I double-click on the symbol Organization.createEmployees() in the “5.1 – Stack trace of method names (tree)” and “5.2 – Measures of CPU used” pane, I jump right to the source code:

You see that Instruments provides annotations (metrics) on performance (like the yellow arrow marked “47x”), but suppose you want serious detail, like assembly code. Click on the Show side-by-side source/disassembly view button:

Look at all that information. You can even see ARC memory management in action, like retain and release statements. Note that ARC has overhead, so when using classes (reference types), you may have to carefully architect your code — and possibly optimize it.
Now that you have an idea of how the Instruments’ Time Profiler template works, let’s look at optimizing some Swift code.
Optimizing Swift Code
Those busy Swift compiler engineers have done a great job of making Swift fast and light-weight. Back in Swift 2.0, there were more opportunities for developers using the language to optimize their code. With the release of Swift 4.2, the compiler is pretty darn optimized — but that doesn’t prevent people from writing bad code. Still, developers need to legitimately optimize code, especially code in which there are complex relationships, mountains of data, and/or extensive calculations.
Dynamic Dispatch
Let’s look at an example involving dynamic dispatch. I urge you to pause at some point while reading this article to take a look at an excellent Apple Developer blog post entitled “Increasing Performance by Reducing Dynamic Dispatch”. You should understand dynamic dispatch by now, even the Swifties, but especially if you used to develop in Objective-C.
My sample code is not Earth-shatteringly innovative, it’s not supposed to be. I’m using a simple example so you can understand the language concepts and optimization tools.
Remember “Region 2” in my Time Profiler trace? Here’s a reminder:

Let’s look at what Instruments showed me when I selected a slice of this part of the timeline:

Hmmm… I see ViewController.startButtonTapped(_:), which is close, but I’m not seeing what I’m interested in. (That’s because this is a simple example, I’m running code in the background using GCD, and therefore iOS is using as many threads/cores as necessary to keep my app responsive.)
I’m comparing the performance of two methods, showEmployee() and show(). See file ViewController.swift in my “Optimizing Swift Code” sample project:
    @IBAction func startButtonTapped(_ sender: Any) {
        
        while true {
            
            DispatchQueue.global(qos: DispatchQoS.QoSClass.default).async {
                
                for count in 0...count-1 { // 0...999999
                    
                        //let employeeInfo = self.organization.employees[count].showEmployee()
                        let employeeInfo = self.organization.employees[count].show()
                    
                        DispatchQueue.main.async {

                            self.newEmployeesTextView.text += employeeInfo
                            print("\(employeeInfo)\n")
                            
                        }
                    
                } // end for count in 0...count-1
                
            } // end DispatchQueue.global
            
        } // end while true

    } // end func startButtonTapped

Remember “6 – Find symbols” in my map? I ran multiple profiling sessions, several to investigate showEmployee() and several for show(). Hey, call me a stickler for details, but I don’t trust one data sample. I’ve got two math minors with an emphasis on statistics, so yes, I profiled multiple times to make sure my claims were substantiated. I’ll present two representative samples from my research (and yes, I switched out of dark mode because my eyes were getting tired).
Here’s what I found out about the performance of Employee.show():

Here’s what I found out about the performance of Employee.showEmployee():

What I found was that Employee.showEmployee() is conservatively about 2.5 times faster than Employee.show(). Yes, I know… Is saving less than a millisecond really an optimization? In this app, no. If you’re working on some app that repeats a call millions of times, maybe optimization by taking out dynamic dispatch would be worth your effort.
So why is Employee.showEmployee() faster? Let’s look into the code. First, look in file People.swift:
import Foundation

class Person {
    
    /*
     final var firstName: String
     final var lastName: String
     final var age: Int
     final var streetAddress: String
     final var zip: String
    */
    var firstName: String
    var lastName: String
    var age: Int
    var streetAddress: String
    var zip: String
    
    init(firstName: String,
         lastName: String,
         age: Int,
         streetAddress: String,
         zip: String) {
        
        self.firstName = firstName
        self.lastName = lastName
        self.age = age
        self.streetAddress = streetAddress
        self.zip = zip
        
    }
    
    func show() -> String {
        let line = """
        First name: \(firstName)
        Last name: \(lastName)
        Age: \(age)
        Street Address: \(streetAddress)
        Zip Code: \(zip)
        """
        
        return line
    }
    
} // end class Person

Notice method show() above. It is overriden in file Employees.swift, shown here:
import Foundation

class Employee: Person {
    
    var employeeID: String
    var retirementAge: Int = 60
    
    init(firstName: String,
         lastName: String,
         age: Int,
         streetAddress: String,
         zip: String,
         employeeID: String) {
        
        self.employeeID = employeeID
        super.init(firstName: firstName, lastName: lastName, age: age, streetAddress: streetAddress, zip: zip)
    }
    
    func isRetirementReady() -> Bool {
        if age >= retirementAge {
            return true
        }
        else {
            return false
        }
    }
    
    override func show() -> String {
        var line = super.show()
        line += "Employee ID: \(employeeID)\n"
        line += "Retirement Age: \(retirementAge)"
        return line
    }
    
    final func showEmployee() -> String {
        let line = """
        First name: \(firstName)
        Last name: \(lastName)
        Age: \(age)
        Street Address: \(streetAddress)
        Zip Code: \(zip)
        Employee ID: \(employeeID)
        Zip Code: \(zip)
        """
        
        return line

    }
    
}  // end class Employee

Notice that I’ve indulged in some overkill here to make a point. Not only have I completely rewritten the show() methods in the form of showEmployee(), but I’ve also marked showEmployee() as final which “allows the compiler to safely elide dynamic dispatch indirection.”
Whole Module Optimization
Remember earlier that I said that the Swift compiler is getting really smart? As I understand it, the optimizations that I’ll discuss from here onwards are already turned on by default. Even so, I believe it’s instructive and helpful for you to understand what the Swift compiler is doing with your code.
Look at the default Xcode 10 Build Settings under Swift Compiler – Code Generation:

Notice that Compilation Mode is set to Incremental for Debug and that Optimization Level is set to No Optimization for Debug. These settings make for fast build times. It should be obvious why performing no optimizations is faster. Incremental building means only recompiling files that have changed since the last build, accounting for updated dependencies. Finally, the Swift compiler “can compile many files in parallel on multiple cores in your machine.”
Compilation Mode is set to Whole Module for Release. Optimization Level is set to Optimize for Speed for Release. That makes for fast apps that you publicly distribute.
I made it a point to break my code into as many logical modules as possible in my “Optimizing Swift Code” sample project:

Profiling this and many other projects for customers, I’ve seen Whole Module Optimization speed up my public releases. In fact, the changes I made to enhance performance in the previous section were done in Debug. When I removed the final keyword in Release, my profiling seemed to confirm that the Swift compiler inferred it as an optimization.

NOTE: You should still consider applying the `final` keyword to both class properties and methods when performance is critical. You can always use Instruments to determine if your “optimizations” are indeed optimizations.

There’s one language feature where Whole Module Optimization has an additive effect on another one. We’ll discuss this in the next section.
Generics
Think about a generic function like the one included with my sample app. You’ll find it in Generics.swift:
func exists(item:T, inArray:[T]) -> Bool {

    var index:Int = 0
    var found = false
    
    while (index < inArray.count && found == false)
    {
        if item == inArray[index]
        {
            found = true
        }
        else
        {
            index = index + 1
        }
    }
    
    if found
    {
        return true
    }
    else
    {
        return false
    }
    
} // func exists

The compiler looks at this function and realizes that “it must be able to handle any type T” that conforms to Equatable. Think about the complexities involved in generics. You’re writing code that ideally should be able to handle any type.
Swift already supports an optimization called generic specialization. It turns out that Whole Module Optimization also optimizes generics. Why?
I know this is a relatively old video, but you should watch the whole thing to find out.
I proved to myself that Whole Module Optimization sped up calls in my sample project to my exists generic function. I profiled the project with Whole Module Optimization on and then profiled it with the setting turned off. This is how you learn about powerful tools.
Simple Optimizations
Say you’re designing a data-intensive app and you need to pick the fastest data structures to use in your code. Go to a site like this one, look at the Big-O complexity chart, review the data structures, and look at the time requirements of their operations. Then pick the data structures that balance your requirements with speed.
ARC Memory Management
ARC memory management has overhead, but I’ve read multiple scientific and commercial journal articles that do not conclude that reference types and reference semantics are slower than value types and value semantics.
In my own work, I’ve never been able to prove that, in general, one was faster than the other, as long as sound best practices were used in development across the board.
While writing this article, I actually coded an entire Swift project that performs the same task by 1) entirely using reference types and semantics and 2) entirely using value types and semantics. After multiple sessions with the Time Profiler, I couldn’t find any significant difference between the two.
Nevertheless, I’ve seen scenarios in which ARC did degrade performance when misused, for example, creating too many references, or using large numbers of reference types when value types could be used instead. One has to strike a balance. For example, if we replace a bunch of references with values, what happens when we have to constantly change and copy those values?
Conclusion
I encourage you to play with my project’s Swift code and its Swift Compiler – Code Generation settings — and then practice with the Time Profiler to analyze and possibly optimize the code. If not my code, use your own code. But practice, practice, and practice with the Time Profiler.
You need to be able to find bottlenecks in your code and then be able to optimize them. You’ll feel a bit overwhelmed if you’ve never used Instruments before. I’ve been using its templates for years and still find it a bit overwhelming. But not using Instruments is a travesty. It offers so many ways to solve problems more easily than using brute force.
By brute force, I mean only fixing bugs and making optimizations by using print statements and maybe some breakpoints.
Please don’t give up on tools like object-oriented programming, protocols and protocol-oriented programming, generics, and closures just because you’ve had a few bad experiences or because you heard they have “high overhead.” When used right, these tools can actually reduce the amount of code you write and speed up your apps. They can certainly help with code maintainability, readability, and reusability.
You have excellent tools with Xcode. Use them.





Dividing and Conquering Your Xcode Projects with Targets
Andrew Jaffee — Thu, 25 Oct 2018 10:15:20 GMT


In this tutorial, I’ll show you how to leverage Xcode targets to control the massive complexity involved in building iOS (and macOS, watchOS, and tvOS) apps. A lot of time can be saved when developers realize that not everything they’re required to do has to be done by writing software language code, like Swift. Integrated development environments (IDEs) like Xcode offer very powerful tools, like targets, that allow developers to decouple nitty-gritty tasks that used to be done in code (or manually) out into project configuration settings. I’ve found that, because of the sheer number of project settings, developers often take one look at say, Xcode’s long, long list of Build Settings, and want to curl up and pass out. When finished reading this tutorial, you’ll see that you can neatly organize code into one project that’s capable of producing binaries for iOS, macOS, watchOS, and tvOS.
If developers take the time to harness the power of Xcode’s features, they can spend most of their time doing what they should be doing: designing, writing, and organizing their code using tools like architectural design patterns (MVVM), tactical design patterns (factory method, facade, adapter), object-oriented techniques, protocol-oriented techniques, generics, delegation — all good, solid development concepts.
Developers should always be on the lookout for opportunities to logically organize and group related code and, conversely, logically separate unrelated code. Xcode targets can let you take related code, put it into one project, yet simultaneously target that code at each of Apple’s platforms: iOS, macOS, watchOS, and tvOS.
When it comes to the more mundane tasks, like changing an app’s name, version number, help bundle, app icon, or copyright text, programmers should be able to turn to Xcode’s tools. Developers shouldn’t be dealing with such tasks using hacks, pyramid-of-doom if statements, and hardcoding values and/or logic. Let’s decouple our coding from these usually boring but necessary responsibilities. Targets help here.
The protocol I’ll discuss herein is a mixture of using Xcode “targets” and “schemes.” I’m sure all sorts of people have all sorts of ways of doing things differently, but I’ve found that this works best for me. I’m not claiming this is the only way to do things.
I know I could’ve (possibly) made things even more generalized by using workspaces, but this is a tutorial. You need to grasp the basics of Xcode’s targets and schemes before building a better, newer, grander solution. There’s such a thing as being too generalized to be useful, too…
Introduction to Xcode Targets
When you create a new project in Xcode, one single target is created for you. For example, I created an Xcode project for iOS, based on the Single View App template, and named it “Xcode Targets.” You can download it from GitHub. Let’s get a quick overview of how project configuration settings/options are stored.
According to the Xcode docs,
By selecting the project name in the project navigator, you open the project editor.
Let’s do that and here’s what we’ll see:

As we forge ahead through this tutorial, keep two concepts from the Xcode docs in mind. First, consider that:
Build settings defined at the target level override any values assigned to those build settings at the project level. Therefore, target-level configurations take precedence over any project-level configurations.
Second, recognize that:
A target contains instructions–in the form of build settings and build phases–for building a product. A target inherits the project’s build settings. Although most developers seldom need to change these settings, you can override any of the project’s build settings by specifying different settings at the target level.
You’ll see that I generally disagree with the statement, “Although most developers seldom need to change these settings.” We’ll be changing settings. That’s a major concern in this tutorial.
A note about “configurations”
Apple notes that:
When you create a project, Xcode provides two standard project-level build configurations: debug and release. … These two build configurations are probably sufficient for your product development needs. Most developers never need to change the values of the vast majority of build settings.
I would add that you can change debug and release settings in each of your targets, not just at the project level. Perhaps because of the length of time that I’ve developed Apple apps, and the complexity of most apps with which I’ve worked, I find myself and coworkers often need to change the values of Build Settings. I also find it very confusing and difficult to manage when almost every build setting at the project and target level have a Debug and Release option. See the following image — and remember that these are just a few of the available options:

So when faced with debug/release, debug/release, debug/release, debug/release…, I see the opportunity for developers to start unwittingly — and easily — commingling debug and release options, or just plain setting conflicting options. As we’ll soon see, I’d rather keep all my release settings in one target and my debug settings in another.
Separating release settings from debug settings
Once I’ve created a project as described above, the first thing I do is to rename the default target as shown here:

Let me just briefly mention schemes. There are variety ways to approach organizing project settings, and I want to keep this tutorial simple. Let me just quote the Xcode documentation again:
When you open an existing project (or create a new one), Xcode automatically creates a scheme for each target. The default scheme is named after your project…
You can read up on schemes using the links I’ve provided. Since a default scheme was generated when I created the project, I’m going to rename it with the same name as my default target:

Notice that I’ve left the Autocreate schemes checkbox ticked.
Now let’s set “Xcode Targets – Release” scheme’s Build Configuration to Release to match it’s name. Go to the Set the active scheme control, just where we started in the last video, Edit Scheme…, and change Debug to Release as follows:

Of course, now we want to create a new target (and scheme) for debugging. Here’s how we create and rename a new target:

The Autocreate schemes checkbox had its intended effect, creating a new scheme — except it didn’t catch my renaming of my new target to “Xcode Targets – Debug.” Make sure to change the newly auto-created scheme from “Xcode Targets – Release copy” to “Xcode Targets – Debug” just like how I did it in the gif above. Set “Xcode Targets – Debug” scheme’s Build Configuration to Debug. You may find that it is already set as Debug, but check it anyway.
To switch between debug and release configurations, all you have to do is switch/set the active scheme. Very importantly, make sure you confine all your Release configurations in Build Settings to the “Xcode Targets – Release” target and all your Debug configurations in Build Settings to the “Xcode Targets – Debug” target. We’ll see how to do this below.
A note about Info.plist
When you Duplicate (create) a new target, Xcode creates a new Info.plist. It gives the new target a name you probably don’t want and puts the file where you probably don’t want:

I like to use the $(SRCROOT) macro in my Xcode projects to standardize and organize my file locations. To keep things “Xcodey,” I set my Build Settings for my “Xcode Targets – Release” target’s Info.plist like so:

For my “Xcode Targets – Debug” target, I put my Info.plist here:
$(SRCROOT)/Xcode Targets/Debug/Info-Debug.plist

I highly recommend that you clean up your Project Navigator setup after making these changes. (I control-clicked the “Xcode Targets” folder in the Project Navigator and used the Add Files to “Xcode Targets”… to context menu command.) Look at the sample project and you’ll understand.
Release versus debug dependencies
I’ve supported quite a few iOS and macOS Xcode apps that consume C++ libraries. In order to provide optimized production code, I only include release versions of libraries when distributing apps to the public. When developing and debugging, I want debug versions of libraries with all symbols linked into my apps so I can set breakpoints and step through code.
For production, I switch to my “Xcode Targets – Release” target and drag release versions of libraries into Build Phases -> Link Binary With Libraries like this:

For debugging and development:

Remember that if I’m calling code from linked libraries, I’ll need the paths to the header files (.h, .hpp). I usually specify those in Build Settings -> Search Paths -> User Header Search Paths:

If I am responsible for the library code and need to maintain it in Xcode, I can use the same separation of concerns structure outlined in this tutorial in my library projects. We’ll see an example below.
Suppose I have release and debug versions of iOS frameworks. For release, I simply click on my “Xcode Targets – Release” target and drag the release framework version into General -> Embedded Binaries. For debug, I simply click on my “Xcode Targets – Debug” target and similarly drag the debug framework version into my target.
Release and debug dependencies are cleanly separated using my targets protocol. We’ll talk more about dependencies later.
Compilation conditions
Those of us who used and/or are still using Objective-C are accustomed to leveraging symbols like DEBUG defined in Xcode under Build Settings -> Apple LLVM 9.0 – Preprocessing -> Preprocessor Macros. If you want similar behavior in Swift, you need to use what Apple calls conditional compilation:
A conditional compilation block allows code to be conditionally compiled depending on the value of one or more compilation conditions.
You can use any of the symbols listed in this link, but I’ll talk about using custom symbols here. Swift still respects DEBUG, but if you want to use it, or the language’s built-in symbols, or custom symbols, you have to define them in your Build Settings -> Swift Compiler – Custom Flags -> Active Compilation Conditions now.
Let’s say I’m logging (LOG) in release to create an audit trail (i.e., I’m tracking logins). Check what’s in my “Xcode Targets – Release” target:

Let’s say I’m not worried about auditing during development. Check what’s in my “Xcode Targets – Debug” target:

I’ve supported quite a few iOS and macOS Xcode projects that consume C++ code that runs on multiple platforms, including Unix/Linux flavors, Microsoft Windows, and macOS. Sometimes things get tricky and, for example, I run into code that will only compile and run on Windows, but not on Mac, and vice versa. I try to minimize such situations, but sometimes things just need to get done. When necessary, I use preprocessor macros or, as Apple now says in Swift, compilation conditions, like WIN, MAC, LOG, and DEBUG.
When calling into my portable C++ code, something like MAC would be defined in both release and debug versions so that I can selectively compile, or not compile, portable or non-portable core code that can only build and run, or not build and run, successfully under macOS (or Windows). Remember that I can use logical operators like ! (not) with my compilation conditions.
I generally use DEBUG to report on and sometimes act upon error conditions. I generally use LOG when my code needs an audit trail (like when processing sensitive data).
If, for example, I have to deal with core code specific to Mac, and debugging and logging, I would use the following generalized though runnable ViewController.swift file:
class ViewController: UIViewController {
    
    var loginAttempts: Int = 0
    
    @IBAction func loginButtonPressed(_ sender: Any) {
        
#if LOG
        print("Login button pressed")
        loginAttempts += 1
        if loginAttempts > 3 {
            print("HACK ATTEMPTED?")
            // CALL 911!
        }
#endif

    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        
#if WIN
        print("Use Windows code...")
#elseif MAC
        print("Use Mac code...")
#endif
        
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
        
#if DEBUG
        print("ViewController::didReceiveMemoryWarning")
#endif
    }

} // end class ViewController

Let’s say I build and distribute my app using the “Xcode Targets – Release” target. Here’s the console output from the previous code snippet:
Use Mac code...
Login button pressed
Login button pressed
Login button pressed
Login button pressed
HACK ATTEMPTED?

The main takeaway here is that you can define as many or as few compilation conditions as you like and specify differing combinations of those conditions in different targets. While I generally frown upon conditionally compiling code, there are times when nothing else works in complex, realworld scenarios. I’m more comfortable with using compilation conditions for situations like turning logging (i.e. print statements) off and on.
Different app flavors/branding
What if you’ve licensed your code to partners/resellers who want their own branding, like custom logos/icons and specific product names, to be displayed by an app? In the iOS App Store, Apple generally frowns on a bunch of identical apps that only differ in their main icons… at least they said they do ;-). But you definitely can have multiple versions of the same app(s) differing in the sense of up-selling from free to intermediate to advanced features and functionality. Branding or “flavors” of iOS apps is much more flexible in an Apple Developer Enterprise Program environment. In macOS development, Apple allows you to build, brand, and distribute apps without going through the Mac App Store, and thus you’re afforded much more flexibility.
Do differing icons, graphics, text, and tiered features warrant multiple Xcode projects? Generally, no. Why don’t we just use targets? I’ve supported apps that have 10 different flavors.
To show you how you can leverage targets to handle branding, I created an Xcode project for macOS, based on the Cocoa App template, and named it “Xcode Manage Config.” You can download it from GitHub.
My project shows you how you can abstract out and customize an app’s:

Help bundle
Name
Version number
Icon
Copyright text

All are done without hacking (i.e. without using if statements and hardcoding values). Reviewing the code and commentary in my sample project’s ViewController.swift file should give you a good idea of how I abstracted all details for the 5 tasks I just listed out of code and into targets:
import Cocoa

let reverseDomain = "us.microit."

class ViewController: NSViewController {
    
    @IBOutlet weak var logoImage: NSImageView!
    @IBOutlet weak var productName: NSTextField!
    @IBOutlet weak var copyright: NSTextField!
    @IBOutlet weak var version: NSTextField!
    
    var helpPath: String = ""
    
    override func viewDidLoad() {
        
        super.viewDidLoad()

        // Do any additional setup after loading the view.

        // Get the product name by stripping out the
        // reverse domain name.
        let bundleIdentifier = Bundle.main.bundleIdentifier?.replacingOccurrences(of: reverseDomain, with: "")
        
        // Display the product name.
        productName.stringValue = bundleIdentifier!
        
        // Build app icon set name using concatenation.
        let appIconSetName:String = bundleIdentifier! + "AppIcon"
        // Get and display the product logo.
        logoImage.image = NSImage(named: NSImage.Name(rawValue: appIconSetName))
        
        // Get the copyright statement.
        let copyrightString = Bundle.main.object(forInfoDictionaryKey: "NSHumanReadableCopyright")
        // Display the product copyright.
        copyright.stringValue = copyrightString! as! String
        
        // Get the product version.
        let versionString = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString")
        // Display the version.
        version.stringValue = "Version: " + (versionString! as! String)
        
        // Build and save the path to help files.
        helpPath = Bundle.main.path(forResource: "index", ofType: "html", inDirectory: bundleIdentifier!)!
        
    } // end func viewDidLoad()
    
    @IBAction func invokeHelp(_ sender: Any) {
        // Open help in default browser.
        NSWorkspace.shared.openFile(helpPath)
    }
    
    override var representedObject: Any? {
        didSet {
        // Update the view, if already loaded.
        }
    }

} // end class ViewController

Let’s build and run the code to see how targets can differentiate two licensors of the same software but with different branding. Let’s build and run the “Acme – Release” target:

Now let’s build and run the “Emca – Release” target:

Notice that nothing was hardcoded… well, except my reverse domain name, and that hasn’t been changed since 1999. It could easily be abstracted into a plist. Please forgive my one, minor transgression. Notice that the official app icons for each target are recognized by macOS:

What if we click on the “Help” button in either target’s app? This is help customized to the “Acme – Release” target, running in Safari:

The “Emca – Release” target’s help is differentiated:

The help bundle

A help bundle is often just a directory containing HTML files/resources. I dragged help folders named “Emca” and “Acme” into the Project Navigator. I was prompted by Xcode both times. I’ll just show you the prompt for the “Acme” folder. Notice I only set the “Acme” folder to be a member of the “Acme – Release” target:

If you click on the “Emca” folder in Xcode’s Project Navigator, you’ll see its Target Membership is only ticked for the “Emca – Release” target:

I’ve seen multi-megabyte help bundles, so if you insist on including the actual help resources in your project, make sure you’re not including stuff that you don’t need, like don’t include Acme’s help in Emca and vice versa. On a side note, believe it or not, I’ve heard many customers insist that they get the actual help included in-situ in their products.
If you plan building, signing, and creating a signed installer for one or both of the “Xcode Manage Config” project’s targets, you need to take a few extra steps. For one thing, remember to go to Build Phases -> Copy Bundle Resources and add the “Acme” folder for copying in the “Acme – Release” target, and similarly add the “Emca” folder for copying in the “Emca – Release” target. Again, two products; two different targets.
The app name and version number

The app name and version number are distinct per target. You set them by selecting the target and then going to General -> Identity. I’ll just show you how I set the values for the “Emca – Release” target:

The app icon

Here, you can see that I’ve already set the app icon for “Acme – Release” and am about to create a new app icon set for “Emca – Release” — this is in the Asset Catalog which is shared by all targets:

Notice that in my code above, I get the code-independent Bundle Identifier and append “AppIcon” to it to get the app icon set appropriate to the current target.
The copyright text

I arranged the Info.plist files for the two targets in this project as I had discussed above in the first sample project. As you’d expect, there’s an Info-Acme.plist for the “Acme – Release” target and an Info-Emca.plist for the “Emca – Release” target. Changing the copyright text is code independent. You highlight the plist file in each target, click into the Copyright (human-readable) string value, and make your edits like so:

We just went through a whole slew of examples of how you can leverage targets for keeping your app code and resources centralized and giving you the flexibility to make changes, like generating multiple flavors of the same app, without using hacks like hardcoding, writing scripts, or writing pyramid-of-doom if statements.
Different dependencies for different app platforms
Over the years, I’ve designed, encoded, used, and accumulated a lot of good, solid C++ code. This code is meant for solving a wide range of problems, or modelling a major gamut of everyday scenarios, for example, messaging, statistical tests, data manipulation, etc. Over the years, I’ve learned to first look for existing code that I can reuse before spending hundreds of hours reinventing the wheel… again (and again).
Tip: Remember that you can divide and conquer your Swift code too by breaking it into modules like frameworks.
What does this have to do with targets? I’m going to show you how you can reuse existing code in one Xcode project that has targets for macOS and iOS (and tvOS and watchOS if you put a little thought into it). So one project can allow you to build binaries and reuse them in four different Apple app types.
I could show you how to do this with frameworks, and that’s the direction to which you’ll want to head, but to keep this didactic, short, and simple, I’m just going to build libraries. You can download a library-based project I created named “Xcode Cocoa Library” from GitHub if you want to follow along.
Create a new Xcode project using these settings:

Click Next and configure thusly:

Click Next and save in a location of your choosing. In the Project Navigator, find the file Xcode_Cocoa_Library.m and rename it to Xcode_Cocoa_Library.mm to be sure that C++ and Objective-C++ are supported.
As we did earlier, Duplicate the “Xcode Cocoa Library” target, renaming the new target and associated scheme as “Xcode iOS Library.” At this point, your project should look like so:

Highlight the “Xcode Cocoa Library” target, go to Build Settings, and look at the Architectures section. You’ll note that the library is configured to be run under macOS on an Intel-based machine:

Notice the target builds successfully.
Highlight the “Xcode iOS Library” target, go to Build Settings, and look at the Architectures section. Change the Base SDK to the latest version of iOS, like so:

You should notice that the library is configured to be run under iOS on an ARM-based machine. Build the “Xcode iOS Library” target. Notice the target builds successfully.
Let’s add some code to the project just to be sure we can write C++ and Objective-C++. (Note that many times I’ve added rock-solid existing C++ .h and .cpp files, blended in some Objective-C and Objective-C++, and was able to reuse mountains of code in my macOS, watchOS, and iOS apps.)
Here’s file Xcode_Cocoa_Library.h:
#import 
#include 

@interface Xcode_Cocoa_Library : NSObject

- (void)helloWorld;

@end

class Parent {
public:
    virtual void soundOff() {
        std::cout << "This is the parent class" << std::endl;
    }
};

class Child: public Parent {
public:
    virtual void soundOff() {
        std::cout << "This is the child class" << std::endl;
    }
};

Here’s file Xcode_Cocoa_Library.mm:
#import "Xcode_Cocoa_Library.h"

@implementation Xcode_Cocoa_Library

- (void)helloWorld {
    
    Child child;
    child.soundOff();
    
    NSLog(@"Hello, world!");
    
}

@end

Build both targets with the new code added. Here’s the result (success):

These library names would be red if they failed to build.
I’m not going to show you how to consume this library in a Swift-based project, as it’s beyond the scope of this tutorial. Rest assured that I’ve incorporated such libraries (and static libs and frameworks) many times into Swift-based projects (generally using a wrapper, a bridging header, and of course, including the libraries’ header files).
The point I’m making here is that you can reuse code and organize it, without using hacks, build for multiple platforms, and get great maintainability and extensibility. How? By using targets.
Truly universal app code
Take a look at this image from the “Xcode Cocoa Library” project discussed in the last section:

I could create two new targets, one for tvOS and one for watchOS. If I organize code properly, keeping abstraction in mind, I can build, maintain, and extend functionality for macOS, iOS, tvOS, and watchOS all in one project.
Conclusion
In reality, I currently have libraries that allow me to reuse much of my over-the-years-accumulated C, C++, Objective-C, Objective-C++, and Swift code in macOS, iOS, tvOS, and watchOS apps. The reason I mention all these languages is that Xcode’s targets and schemes have enabled me to reuse a lot of code I’ve written in the past — and I’ve been able to reuse my legacy code on multiple Apple platforms, namely iOS, macOS, watchOS, and a bit of tvOS.
I’ve only been able to do that by planning, doing requirements analysis, designing first before coding, concentrating on abstraction — looking before leaping. I’ve been able to abstract so much code by implementing concepts and techniques like best practices for building classes, using architectural design patterns like MVVM, using tactical design patterns (here, here, and here), and, of course, using object-oriented and protocol-oriented programming techniques.
I’m waxing theoretical. You’ve got great tools available to you, like Xcode and its targets and schemes. Don’t be a just-get-it-done developer. Invest some time into reading up on the documentation provided with Xcode. Look at some third party books and videos. Join special interest groups and social media groups. Take the information you glean from your studying and put it to practice in your everyday work. Don’t be a stick in the mud. Try new things and constantly push the envelope.
If you take the time, you’ll find that tools like Xcode provide features beyond your wildest dreams.





Best Practices for Building Swift Classes
Andrew Jaffee — Fri, 28 Sep 2018 17:10:06 GMT


In this tutorial, I’m going to give you some best practices that will help you safely and effectively use classes (reference types) and reference semantics in Swift. Protocol-oriented programming (POP) and value semantics are all the rage now, but a promising new technology doesn’t mean you should throw all your classes away. Why not add some simple constructs to your classes like copy initializers, default initializers, designated initializers, deinitializers, and conformance to the Equatable protocol? To get real about my sample code, I’ll adopt these constructs in some classes that you can use for drawing in your iOS app interfaces.
I’ll walk through the process of creating several protocols, creating classes that adopt those protocols, implement inheritance in these classes, and use instances of the classes (objects), all to illustrate my best practices — and to show some of the extra steps you may have to go through when working with classes.
Using Protocols as much as possible
Defining and using protocols makes your intent crystal clear when defining new classes. When you and other developers look at the signature for your classes, you get meaningful information immediately (like “this class supports a copy constructor”). I also like to confine the requirements of my protocols to one purpose. Since I break my protocols up into focused sets of requirements, my classes can adopt as many or as few protocols as required.
POP, OOP, and POOP?
Remember one very important point: Most code in the iOS (and OS X) SDKs comes in the form of class hierarchies. I believe many of the core frameworks we use are still written in Objective-C (and some C++ and C), like Foundation and UIKit.
Think about creating a new Xcode project based on the iOS Single View App template. Where do many developers get started in this new type of project? Right, in file ViewController.swift. And what do we all see when opening that file? We see  ViewController which is a subclass of UIViewController.
What does Apple have to say about ViewController? Here we go:

  …You rarely create instances of the UIViewController class directly. Instead, you subclass UIViewController and add the methods and properties needed to manage the view controller’s view hierarchy. …
  Every app contains at least one custom subclass of UIViewController. More often, apps contain many custom view controllers. Custom view controllers define the overall behaviors of your app, including the app’s appearance and how it responds to user interactions.

Yeah, yeah, yeah… Apple is pushing protocol-oriented programming (POP), value types (structs and enums), and value semantics. Got it. Heard it loud and clear. But classes (reference types), with their reference semantics and object-oriented programming (OOP) capabilities, will be around for awhile.
There’s always some new programming fad. The only thing I’m concerned about is whether POP is really useful or just another marketing ploy. So far, it has proven useful in my production code, but not all of the time.
The Thing about Classes
Reference types (classes) and reference semantics can be boon or bane, depending on how you use them. But that’s true of all prominently-used technologies. There are advantages and disadvantages. To paraphrase Shakespeare, “To copy or not to copy: that is the question.” My answer to the question is to first understand the problem at hand, trust my intuition, and use copying — value semantics — when necessary, and to not use copying — reference semantics — when necessary.
Even with Apple’s supposed move towards POP, one of the Apple engineers at WWDC 2015 pointed out that “So, for example, a Window. What would it mean to copy a Window?” It wouldn’t mean anything except confusion. Indeed, what would a copy of a UIViewController subclass instance mean and what would you do with it? Entities like UIViewController and NSWindow should remain as classes.
Suppose you used the facade design pattern to create a simple interface and wrapper for a very complex database system that must be used by all customers who’ve bought your app. The most straightforward way to sensibly use this database would be to pass a reference to it around your app. Why in G-d’s name would you write a value type (struct) version of this database and give a copy of the database infrastructure and all its data to each instance of your app? You’d have a disaster.
Obviously, classes still have a place in the software development world. And please don’t think that making a class a member property of a struct is the answer to your prayers. That member property will exhibit reference semantics.
The problem with classes
You all probably know what I’m going to talk about. Here it is from an old Swift blog post:

Copying a reference… implicitly creates a shared instance. After a copy, two variables then refer to a single instance of the data, so modifying data in the second variable also affects the original.”

Here’s an example of the potential perils of reference semantics: I’ll create a class instance, then declare a reference it, then declare another reference to it, set the latter reference equal to the former reference, end up with two references to the same object/instance, change a member property on the latter reference, and see that change reflected in the one instance:
class Coordinate
{
    var x: Float
    var y: Float
    
    init( x: Float, y: Float ) {
        self.x = x
        self.y = y
    }
}

var coordinate = Coordinate(x: 2.0, y: 4.0)
print("coordinate:  (\(coordinate.x), \(coordinate.y))")
// coordinate:  (2.0, 4.0)

// Unintended mutation?
var coordinate1 = coordinate
coordinate1.y = 0.0

print("coordinate:  (\(coordinate.x), \(coordinate.y))")
// coordinate:  (2.0, 0.0)

print("coordinate1: (\(coordinate1.x), \(coordinate1.y))")
// coordinate1: (2.0, 0.0)

coordinate === coordinate1
// true

Output to console from the previous code snippet:
coordinate:  (2.0, 4.0)
coordinate:  (2.0, 0.0)
coordinate1: (2.0, 0.0)

Since objects coordinate and coordinate1 both are references to the object created by the statement Coordinate(x: 2.0, y: 4.0), changes to either reference changes both objects. The statement var coordinate1 = coordinate is an example of copying a reference.
Note my use of the logical === operator:
coordinate === coordinate1
// true

From the Swift docs, === “Returns a Boolean value indicating whether two references point to the same object instance.” Obviously, in this case, coordinate and coordinate1 refer to the same instance. Remember that “Equality is Separate From Identity” and “The identity of a class instance is not part of an instance’s value.”
In even the smallest of apps, I’ve seen errors occur because of “unintended sharing,” unintended mutation — whatever you want to call creating multiple references to the same object and changing a property in one of those references. This behavior can be especially difficult to debug in multi-threaded code involving reference types. But guess what? You can write bad code using value types.
Changes to the first instance of some struct and subsequent changes to copies could still be “unintended.” Any what if you end up with a bunch of copies of a struct? Is it semantically clear as to what your code is doing? Even Apple admits it: “The problem is that immutability has some disadvantages.”
We can get into a discussion of making our classes safe by using Apple’s version of “defensive copying.” where we make all our classes adopt the NSCopying (and perhaps NSObject) protocol(s), and then make sure all our classes implement copy(with:) (mainly just copy()), and remember to call copy() constantly, on every assignment. And calling copy()  requires a cast:
let objectCopy = object.copy() as! ObjectType

Be aware that defensive copying is all over Cocoa and Objective-C. There are still many developers who have to support entire legacy iOS and OS X codebases. And there are many of us who must interact with legacy iOS and OS X codebases. We’re not going to take the NSCopying tack in this tutorial. While I will show you some code for defensive copying, I will also show you many other techniques to make your use of classes safe.
Getting Started with a Playground
Let’s create a new Xcode playground. In Xcode, go to File -> New > -> Playground… and click iOS and the Single View template icon. Click the Next button, select a location for your new playground’s bundle, give your playground a name, and click the Create button. Or you can download my sample Xcode playground from GitHub.
Make some room in your playground where my comment “PUT SOME SPACES HERE” is located (shown below) for the class-based code I’m going to write during this tutorial, like so:
//: A UIKit based Playground for presenting user interface
  
import UIKit
import PlaygroundSupport

//
// PUT SOME SPACES HERE
//

class MyViewController : UIViewController {
...

Now replace the “PUT SOME SPACES HERE” comments with the protocol named Copyable and class called Line, as shown below:
//: A UIKit based Playground for presenting user interface
  
import UIKit
import PlaygroundSupport

protocol Copyable: class {
    
    func copy() -> Self
    
}

class Line {
    
    var beginPoint: CGPoint
    var endPoint: CGPoint
    
    init( beginPoint: CGPoint, endPoint: CGPoint ) {
        
        self.beginPoint = CGPoint( x: beginPoint.x, y: beginPoint.y )
        self.endPoint = CGPoint( x: endPoint.x, y: endPoint.y )
        
    }
    
} // end class Line

class MyViewController : UIViewController {
...

You should be able to tell that objects of this class can be used to represent geometric, straight lines by defining beginning points and endpoints. I’ve used the CGPoint class to represent my beginning points and endpoints so that this class is very compatible with drawing/graphics. Currently, the Line class only has a designated initializer.
Best Practices for Classes
Based on the evidence I’ve seen from the evolution of the Swift language, my own experiences with Swift, and observing the experiences of others developing with Swift, classes aren’t going away. OOP features, made possible by use of classes, like inheritance, virtual methods, and polymorphism aren’t going away because they’re just too darn useful.
Let me show you some techniques I use to mitigate “unintended sharing” in classes — and also other approaches you can use just to write better and semantically clear class-based code. A lot of what I’m sharing with you here comes from my years of experience writing C++ code.
Copy constructor (copy initializer)
You may have noticed the Copyable protocol in the initial code I added to our playground. Unintended mutation is one of the biggest critiques of reference semantics, so we’re going to start by mitigating class mutation. Notice my use of Self with a capitalized “S” as opposed to self with a lowercase “s” in my Copyable protocol. This is no accident. From the Swift docs: “Self refers to the eventual type that conforms to the protocol.” If you’re unclear as to what differentiates Self from self, I suggest you study up on the subject.
Why not recognize the “problem” of “unintended sharing” outright and make a semantic statement about it with a protocol that will require conforming classes to implement a “copy constructor?” To climb out of my C++ past, I’ll use Swift terminology and say “copy initializer.” A copy initializer allows us to create an instance of a class using another instance of a class. A new object is created containing the same member properties as another object of the same type. Let me be clear: A fully independent copy of an object is made. Though the new object contains the same data as the original, a new instance (object) is created. The new object is not a reference to the original object. It is a copy and the semantics of the copy initializer makes your intent clear.
Making a copy of a class instance can give you a form of immutability — a baseline to which you can compare future changes to that instance, and/or a way to restore the instance’s state if something goes wrong later.
Notice that Swift almost seems to frown on making a copy of a reference type, i.e., a copy of an instance of a class, or, as some would rather put it, getting a copy of an object. I’m not talking about getting another reference to a class, I’m talking about getting an entire, separate copy of a class instance. This frowning on class copying is not an accident. Swift’s language architects want the syntax and semantics of the language to be crystal clear. They want developers to be confident that reference types and value types will both have 1) distinct and obvious meanings and that both types will 2) behave consistently. But still, why not be able to safely make a copy of a class instance? I’ll show you how in this tutorial by borrowing the copy constructor concept from C++. In Swift, we’d call this a “copy initializer.”
Swift is downright difficult about allowing copying of class instances:

  It is not possible to overload the default assignment operator (=).

In C++, I would override the assignment operator to allow my class to make deep copies of its instances (i.e., their properties’ values) and thus help prevent unwanted changes. I’d also create a copy constructor. I can even turn off assignment in C++ by making my assignment operator private. Swift isn’t C++, but does support one of the ideas I’ve floated, but only if you build a custom version.
Let’s make my Line class adopt my Copyable protocol. Copyable requires a conforming class to implement a copy initializer:
protocol Copyable: class {
    
    func copy() -> Self
    
}

class Line : Copyable {

    var beginPoint: CGPoint
    var endPoint: CGPoint
    
    init( beginPoint: CGPoint, endPoint: CGPoint ) {
        
        self.beginPoint = CGPoint( x: beginPoint.x, y: beginPoint.y )
        self.endPoint = CGPoint( x: endPoint.x, y: endPoint.y )
        
    }
    
    func copy() -> Self {
        
        return type(of: self).init( beginPoint: self.beginPoint,
                                    endPoint: self.endPoint )

    }

} // end class Line

I want copy() to instantiate a new instance of my Line class with its current member property values and return that instance. It will do that, but only until I clear up the “Constructing an object of class type ‘Self’ with a metatype value must use a ‘required’ initializer” error message as shown in this image:

Remember that Line subclasses will inherit copy() and the method’s implementation is mandated by the Copyable protocol. copy() calls the designated initializer. Note that in the image above, the first character, i, of this init is underlined, telling me that it needs to be marked as required because, according to the official Swift documentation:

  Write the required modifier before the definition of a class initializer to indicate that every subclass of the class must implement that initializer … You must also write the required modifier before every subclass implementation of a required initializer, to indicate that the initializer requirement applies to further subclasses in the chain. You do not write the override modifier when overriding a required designated initializer…

I marked the designated initializer as required and the code now compiles:
protocol Copyable: class {
    
    func copy() -> Self
    
}

class Line : Copyable {
    
    var beginPoint: CGPoint
    var endPoint: CGPoint
    
    required init( beginPoint: CGPoint, endPoint: CGPoint ) {
        
        self.beginPoint = CGPoint( x: beginPoint.x, y: beginPoint.y )
        self.endPoint = CGPoint( x: endPoint.x, y: endPoint.y )
        
    }
    
    func copy() -> Self {
        
        return type(of: self).init( beginPoint: self.beginPoint,
                                    endPoint: self.endPoint )
        
    }
    
} // end class Line

I wrote some test code. I’ve taken the output shown in the right pane corresponding to each line of code and made it into a comment:
let line1 = Line(beginPoint: CGPoint(x: 20, y: 20), endPoint: CGPoint(x: 20, y: 200))
let lineCopy = line1.copy()
let line2 = line1
line2.beginPoint.x = 80
// line2.beginPoint = {x 80 y 20}
line1.beginPoint
// line1.beginPoint = {x 80 y 20}
lineCopy.beginPoint
// lineCopy.beginPoint = {x 20 y 20}

I initialized an instance of Line and got a reference to it, line1. I got another reference to the Line instance, line2, made and change to one of its properties and, of course, the change is visible in all references.
I used the copy initializer to get an independent copy of my Line instance. That copy is in fact a unique instance. Changing the copy, lineCopy, has no effect on the original instance as referenced by line1 and line2.
To further prove my copy initializer, I compared line1 and line2 with “the triple-equals identical-to operator (===)”. I also compared lineCopy with line1 (and didn’t bother with line2, because it’s identical to line1):
line1 === line2
// true
lineCopy === line1
// false

Is the copy initializer an initializer?

The copy() method you just saw is technically not an initializer, but you see that while it’s not called init, it does call init. It’s a method that makes a separate, independent copy of a class instance. It doesn’t copy a reference, it copies the current contents of an instance’s properties and returns a fresh instance of classes that conform to Copyable.
Here’s a protocol that indeed requires a by-the-book copy initializer:
protocol Copyable: class
{
    init(copy: Self)
}

While this would be my preferred methodology of requiring and creating copy initializers, I’ve found that it can cause, in my eyes, unwanted and undue complexities when using inheritance. I’m still working on it and will let you know if I get things functioning up to my standards of readability and maintainability.
Inheriting the copy initializer

Created a descendant with a copy initializer can be little tricky, so let’s go ahead and do it to flesh out the concepts required. Let’s extend my Line to include some properties that make it easier to draw the line to screen in an iOS app. I’ll call the descendant DrawableLine. While the following code looks pretty clean, it does have some issues — issues that when resolved will lead to a better understanding of the topics in this tutorial, and for classes in general:
class DrawableLine: Line
{
    
    var color: UIColor
    var width: CGFloat
    
    init( beginPoint: CGPoint, endPoint: CGPoint, color: UIColor, width: CGFloat )
    {
        self.color = color
        self.width = width
        super.init(beginPoint: beginPoint, endPoint: endPoint)
    }
    
    func copy() -> Self
    {
        return type(of: self).init( beginPoint: beginPoint,
                                    endPoint: endPoint,
                                    color: color,
                                    width: width )
    }

} // end class DrawableLine

I need to deal with three problems as described by the Swift compiler: “‘required’ initializer ‘init(beginPoint:endPoint:)’ must be provided by subclass of ‘Line’,” “Overriding declaration requires an ‘override’ keyword,” and “Constructing an object of class type ‘Self’ with a metatype value must use a ‘required’ initializer.” Here’s an image showing the error messages:

I’ll make the required changes and explain them with inline code commentary. Here’s the working Line descendant, DrawableLine:
class DrawableLine: Line
{
    
    var color: UIColor
    var width: CGFloat
    
    // We must implement this init tangentially because of Copyable.
    // The "'required' initializer 'init(beginPoint:endPoint:)' must
    // be provided by subclass of 'Line'" error is then resolved.
    // Think of this as a convenience constructor -- shorthand
    // for rapid prototyping.
    required init( beginPoint: CGPoint, endPoint: CGPoint ) {
        self.color = UIColor.black
        self.width = 1.0
        super.init( beginPoint: beginPoint, endPoint: endPoint )
    }
    
    // Prefxing this init with the "required" keyword resolves the
    // "Constructing an object of class type 'Self' with
    // a metatype value must use a 'required' initializer" error.
    required init( beginPoint: CGPoint, endPoint: CGPoint, color: UIColor, width: CGFloat )
    {
        self.color = color
        self.width = width
        super.init( beginPoint: beginPoint, endPoint: endPoint )
    }
    
    // Prefixing the method with the "override" keyword resolves the
    // "Overriding declaration requires an 'override' keyword" error.
    // We must provide a copy of DrawableLine, not Line.
    override func copy() -> Self
    {
        return type(of: self).init( beginPoint: beginPoint,
                                    endPoint: endPoint,
                                    color: color,
                                    width: width )
    }
    
} // end class DrawableLine

Having to implement the required init(beginPoint:endPoint:) in DrawableLine is a small price to pay for the fact that we can keep creating valid copy initializers for each new subclass of Line we dream up in the future. (And it’s a heck of a lot better than the side effects I’m still wrestling with when using init(copy: Self) and inheritance.)
Regarding the required keyword, remember that when a class adopts a protocol, it must conform to that protocol… AND remember that a class can have… what are they called? Descendents. I once again refer you to the section entitled “Required Initializers” in the Swift documentation.
Let me test the DrawableLine copy initializer to make sure that changes to a copy of an instance do not affect that instance. Notice that, just for giggles, I used the initializer upon which I commented that it was a “convenience constructor — shorthand for rapid prototyping.”
let thinBlackLine = DrawableLine(beginPoint: CGPoint(x: 187.5, y: 40.0), endPoint: CGPoint(x: 187.5, y: 300.0))
let thinLineCopy = thinBlackLine.copy()
thinLineCopy.color = UIColor.red
thinBlackLine.color
// UIColor.black
thinBlackLine === thinLineCopy
// false

Drawing my line in a playground

Let’s draw my thinBlackLine to the simulator in the playground. Delete all the boilerplate code at the bottom of the playground starting with this line:
class MyViewController : UIViewController {...

Replace it with the following:
class LineDrawingView: UIView
{
    override func draw(_ rect: CGRect)
    {
        let currGraphicsContext = UIGraphicsGetCurrentContext()
        currGraphicsContext?.setLineWidth(thinBlackLine.width)
        currGraphicsContext?.setStrokeColor(thinBlackLine.color.cgColor)
        // "Begins a new subpath [e.g., line] at the specified point."
        currGraphicsContext?.move(to: thinBlackLine.beginPoint)
        // "Appends a straight line segment from the current point to the specified point."
        currGraphicsContext?.addLine(to: thinBlackLine.endPoint)
        // "Paints a line along the current path."
        currGraphicsContext?.strokePath()
        UIGraphicsEndImageContext()
    }
}

class MyViewController : UIViewController {
    override func loadView() {
        let view = LineDrawingView()
        view.backgroundColor = .white
        self.view = view
    }
}
// Present the view controller in the Live View window
PlaygroundPage.current.liveView = MyViewController()

If you need help drawing in a playground, click here. Run the playground and you’ll see my line in the “Live View” pane:

Designated initializers
Notice that I used designated initializers in my code samples so far because I’ve got “Class Inheritance and Initialization” on my mind. I suggest you always craft designated initializers unless there are very extenuating circumstances.
When writing classes, I almost always consider the possibility that I might use inheritance to extend those classes at a later time. First, consider that:

  Initialization is the process of preparing an instance of a class, structure, or enumeration for use. This process involves setting an initial value for each stored property on that instance and performing any other setup or initialization that is required before the new instance is ready for use.

Some developers skip creating initializers by marking all class member properties as optional. While sometimes it’s necessary to use optional member properties, I try to avoid them as much as possible. Most of the time I find that I can design my classes with non-optional member properties. Swift’s designers knew that having a designated initializer increases a class’s readability, supportability, and potential for future extensibility. It gives you and other developers a lot of insight into your class’s purpose and your intent in writing that class. From the Swift docs:

  Designated initializers are the primary initializers for a class. A designated initializer fully initializes all properties introduced by that class and calls an appropriate superclass initializer to continue the initialization process up the superclass chain.
  Classes tend to have very few designated initializers, and it is quite common for a class to have only one. Designated initializers are “funnel” points through which initialization takes place, and through which the initialization process continues up the superclass chain.
  Every class must have at least one designated initializer. In some cases, this requirement is satisfied by inheriting one or more designated initializers from a superclass…

Default initializers
My next best practice for defining classes comes in the form of another simple protocol:
protocol DefaultInitializable {
    
    init()
    
}

Obviously DefaultInitializable requires adopting classes to implement an init() method, what you should recognize as a default initializer.
Suppose your class contains all optional properties but with no explicit default values. Suppose also you have no default initializer. In other words, all your class’s properties will be nil right after the Swift-provided default initializer is called. Your new class instance (object) could potentially crash your app. I guarantee that no matter what, somebody at some time is going to initialize one of your classes like this:
class Line {
    
    var beginPoint: CGPoint?
    var endPoint: CGPoint?
    
}

let line = Line() // Line
line.beginPoint // nil
line.endPoint // nil

Remember what Swift does in such cases:

  Swift provides a default initializer for any structure or class that provides default values for all of its properties and does not provide at least one initializer itself. The default initializer simply creates a new instance with all of its properties set to their default values. …

A strictly optional property with no default value “automatically receives a default value of nil, even though this value is not written in the code.”
So what happens when the developer that uses the previous code snippet passes  line, line.beginPoint, or line.endPoint to some complex custom code that doesn’t check for nil? The code crashes.
That’s why DefaultInitializable requires you implement a default initializer (init()). I want you to think through and make semantically clear, in code, the default values your class’s properties start out with when that class first becomes an object.
We’ll look at an example of DefaultInitializable in the next section. I want to show you how you can compose together as many or as few protocols as needed when defining a class.
ARC memory management
When dealing with classes, memory management is handled by ARC and there’s always the possibility for memory leaks. I’m not proposing a magic cure for leaks, but I’m providing you with an aid to track down leaks — or at least know how your instances are behaving memory-wise. Here’s a protocol and extension that I hope you’ll find as useful as I do:
protocol Allocatable: class {
    
    // Give a name to your instance.
    var tag: String { get }
    // Call in initializers.
    func onAllocate()
    // Call in deinitializers.
    func onDeallocate()
    
}

extension Allocatable {
    
    func onAllocate() {
        print("Instance \(tag) of type \(typeIs()) allocated.")
    }
    
    func typeIs() -> String {
        return String(describing: type(of: self))
    }
    
    func onDeallocate() {
        print("Instance \(tag) of type \(typeIs()) deallocated.")
    }
    
} // end extension Allocatable

The tag variable gives you the opportunity to identify individual instances of your classes. I can’t magically conjure up a default initializer for your classes, nor can I require a call to deinit in a protocol. So you have to configure your classes to cooperate with my Allocatable protocol.
Here’s code where I made a parent class adopt both my DefaultInitializable and Allocatable protocols, including some helpful general inline commentary — and comments indicating a few errors I cleaned up as we discussed previously:
protocol Allocatable: class {
    
    // Give a name to your instance.
    var tag: String { get }
    // Call this in initializers.
    func onAllocate()
    // Call this in deinitializers.
    func onDeallocate()
    
}

extension Allocatable {
    
    func onAllocate() {
        print("Instance \(tag) of type \(typeIs()) allocated.")
    }
    
    func typeIs() -> String {
        return String(describing: type(of: self))
    }
    
    func onDeallocate() {
        print("Instance \(tag) of type \(typeIs()) deallocated.")
    }
    
} // end extension Allocatable

class Line: Allocatable, DefaultInitializable {
    
    var beginPoint: CGPoint
    var endPoint: CGPoint
    let tag: String
    
    // "Initializer requirement 'init()' can only be satisfied
    // by a 'required' initializer in non-final class 'Line'"
    // resolved with "required" prefix
    required init() {
        // Defines a straight vertical line in the upper, center
        // of an iPhone 8
        beginPoint = CGPoint( x: 187.5, y: 40.0 )
        endPoint = CGPoint( x: 187.5, y: 300.0 )
        tag = "Untagged"
        
        onAllocate()
    }
    
    init( beginPoint:CGPoint, endPoint:CGPoint, tag: String ) {
        
        self.beginPoint = CGPoint( x: beginPoint.x, y: beginPoint.y )
        self.endPoint = CGPoint( x: endPoint.x, y: endPoint.y )
        self.tag = tag
        
        onAllocate()
    }
    
    deinit {
        onDeallocate()
    }
    
} // end class Line

class DrawableLine: Line {
    
    var color: UIColor
    var width: CGFloat
    
    // "'required' modifier must be present on all overrides of a
    // required initializer" resolved with "required" prefix
    //
    // "Overriding declaration requires an 'override' keyword"
    // resolved when I marked parent init() as "required"
    required init() {
        color = UIColor.black
        width = 1.0
        
        super.init()
    }
    
    required init( beginPoint:CGPoint,
                   endPoint:CGPoint,
                   color: UIColor,
                   width: CGFloat,
                   tag: String ) {
        
        self.color = color
        self.width = width
        
        super.init( beginPoint: beginPoint, endPoint: endPoint, tag: tag )
    }
    
} // end class DrawableLine

The next code snippet shows you how my DefaultInitializable protocol encouraged safe usage of class instances created only using their default initializers (look at line and drawableLine3). It also shows you how the designated initializer allowed me to create two fully-configured lines, drawableLine1 and drawableLine2:
let line = Line()
let drawableLine1 = DrawableLine(beginPoint: CGPoint(x: 40.0, y: 40.0), endPoint: CGPoint(x: 40.0, y: 300.0), color: UIColor.red, width: 8.0, tag: "Line 1")
let drawableLine2 = DrawableLine(beginPoint: CGPoint(x: 40.0, y: 300.0), endPoint: CGPoint(x: 300.0, y: 300.0), color: UIColor.red, width: 8.0, tag: "Line 2")
let drawableLine3 = DrawableLine()

Then I wrote code to render those lines in a CGContext…
class LineDrawingView: UIView
{
    override func draw(_ rect: CGRect)
    {
        let currGraphicsContext = UIGraphicsGetCurrentContext()
        
        currGraphicsContext?.setLineWidth(drawableLine1.width)
        currGraphicsContext?.setStrokeColor(drawableLine1.color.cgColor)
        // "Begins a new subpath [e.g., line] at the specified point."
        currGraphicsContext?.move(to: drawableLine1.beginPoint)
        // "Appends a straight line segment from the current point to the specified point."
        currGraphicsContext?.addLine(to: drawableLine1.endPoint)
        // "Paints a line along the current path."
        currGraphicsContext?.strokePath()
        
        currGraphicsContext?.setLineWidth(drawableLine2.width)
        currGraphicsContext?.setStrokeColor(drawableLine2.color.cgColor)
        // "Begins a new subpath [e.g., line] at the specified point."
        currGraphicsContext?.move(to: drawableLine2.beginPoint)
        // "Appends a straight line segment from the current point to the specified point."
        currGraphicsContext?.addLine(to: drawableLine2.endPoint)
        // "Paints a line along the current path."
        currGraphicsContext?.strokePath()

        currGraphicsContext?.setLineWidth(drawableLine3.width)
        currGraphicsContext?.setStrokeColor(drawableLine3.color.cgColor)
        // "Begins a new subpath [e.g., line] at the specified point."
        currGraphicsContext?.move(to: drawableLine3.beginPoint)
        // "Appends a straight line segment from the current point to the specified point."
        currGraphicsContext?.addLine(to: drawableLine3.endPoint)
        // "Paints a line along the current path."
        currGraphicsContext?.strokePath()

        UIGraphicsEndImageContext()
    }
}

class MyViewController : UIViewController {
    override func loadView() {
        let view = LineDrawingView()
        view.backgroundColor = .white
        self.view = view
    }
}
// Present the view controller in the Live View window
PlaygroundPage.current.liveView = MyViewController()

… and displayed those lines in the Simulator:

The following sample code will show you how, using local scope in a playground, my Allocatable protocol allows you to track ARC memory allocation and deallocation:
do {
    let line = Line()
    let drawableLine1 = DrawableLine(beginPoint: CGPoint(x: 40.0, y: 40.0), endPoint: CGPoint(x: 40.0, y: 300.0), color: UIColor.red, width: 8.0, tag: "Line 1")
    let drawableLine2 = DrawableLine(beginPoint: CGPoint(x: 40.0, y: 300.0), endPoint: CGPoint(x: 300.0, y: 300.0), color: UIColor.red, width: 8.0, tag: "Line 2")
    let drawableLine3 = DrawableLine()
}

Here is the playground output to console:
Instance Untagged of type Line allocated.
Instance Line 1 of type DrawableLine allocated.
Instance Line 2 of type DrawableLine allocated.
Instance Untagged of type DrawableLine allocated.
Instance Untagged of type DrawableLine deallocated.
Instance Line 2 of type DrawableLine deallocated.
Instance Line 1 of type DrawableLine deallocated.
Instance Untagged of type Line deallocated.

Conformance to Equatable
You should always be able to determine if the properties of one instance of a class are the same as, or different than, those of another instance, especially because of the possibility of unintended mutation.
First of all, remember that you can always definitively determine if several different references of the same type refer to the same instance (object) using the “identical-to operator,” more commonly known as ===.
But suppose you’ve used your copy initializer to save a baseline of the values of you used to create the original object. Suppose later you want to see how far the original object’s values have strayed from their baseline values.
Or consider that you’ve got many different instances of classes and you need the ability to compare their property values for some business requirement (e.g., to find a last name match in a group of object’s representing persons). Equatable is an essential protocol (tool) to have. If you don’t remember Equatable, see my explanation here and Apple’s here.
So I added Equatable conformance to my Line class (which already conforms to Allocatable and DefaultInitializable). I kept it simple when determining whether Line instances were equal (and note that Equatable provides !=). I used the Pythagorean Theorem (see here and here) to determine and compare the length of two lines. Here’s the new Line code, which is inherited by DrawableLine:
class Line: Allocatable, DefaultInitializable, Equatable {
    
    var beginPoint: CGPoint
    var endPoint: CGPoint
    let tag: String
    
    // "Initializer requirement 'init()' can only be satisfied
    // by a 'required' initializer in non-final class 'Line'"
    // resolved with "required" prefix
    required init() {
        // Defines a straight vertical line in the upper, center
        // of an iPhone 8
        beginPoint = CGPoint( x: 187.5, y: 40.0 )
        endPoint = CGPoint( x: 187.5, y: 300.0 )
        tag = "Untagged"
        
        onAllocate()
    }
    
    init( beginPoint:CGPoint, endPoint:CGPoint, tag: String ) {
        
        self.beginPoint = CGPoint( x: beginPoint.x, y: beginPoint.y )
        self.endPoint = CGPoint( x: endPoint.x, y: endPoint.y )
        self.tag = tag
        
        onAllocate()
    }
    
    // The line length formula is based on the Pythagorean theorem.
    func length () -> CGFloat
    {
        let length = sqrt( pow(endPoint.x - beginPoint.x, 2) + pow(endPoint.y - beginPoint.y, 2) )
        return length
    }
    
    static func == ( lhs: Line, rhs: Line ) -> Bool {
        return (lhs.length() == rhs.length())
    }

    deinit {
        onDeallocate()
    }
    
} // end class Line

Here’s some code to test my Equatable implementation, including the playground’s evaluation of each statement in the right-hand pane which I copied into comments next to each line below:
drawableLine1 == drawableLine3 // true
drawableLine1 != drawableLine3 // false
drawableLine1 == drawableLine2 // true

Look at the image above and the values I used in initializers in a previous code snippet above to compare and validate line lengths and results.
Conclusion
No matter what paradigm you’re using, you need to have a set of best practices. Anybody can take a good tool and screw it all up. Successful developers get to know a technology like OOP through study and practice, practice, practice — writing lots of code. They’re willing to learn from their mistakes and admit when they’re wrong. They’re also willing to listen to mentors and/or the collective wisdom of their peers and adopt best practices.
I’ve presented you with some best practices for classes using constructs like copy initializers, default initializers, designated initializers, deinitializers, and conformance to the Equatable protocol. This is not an exhaustive list, for example, I could’ve covered failable initializers (init?()), but can’t cover everything in one article. I hope they help you. At least try them out. You can find an enormous amount of advice on OOP out there, even for a relatively new language like Swift.
Get out out there and experiment, practice, study, and be your best!





Protocol-oriented Data Structures in Swift: A Generic Doubly Linked List
Andrew Jaffee — Mon, 24 Sep 2018 00:12:31 GMT


Let’s talk about creating a list on steroids, i.e., a generic doubly linked list in Swift. For our purposes here, a list is a software receptacle that contains related data that we’re interested in inspecting, organizing, manipulating, etc. A doubly linked list stores a list of “nodes.” Each node contains data, knows about the preceding node in the list, and knows about the following node in the list.
We’ll talk about adding nodes to the list, removing nodes from the list, displaying information stored in nodes in the list, and traversing the list. I’ve used the term generic because you’ll see that I can store store pretty much every built-in or custom Swift type in my linked list, like Double, UINavigationController, Int, CGFloat, UIView, CGAffineTransform… You can even store a collection of instances of a custom class or struct in my list (see section “Storing custom types” below). Most importantly, I’ll show you how to move towards generic programming, also known as generics, parametric polymorphism, templates, or parameterized types, where, when possible, we can write code that applies to many types, and thus reduces code redundancy.
To achieve these lofty goals, I’ve concentrated my functionality into protocols and classes, taking advantage of both protocol-oriented programming principles (POP) and object-oriented programming principles (OOP). Click here for an introduction to POP. Since I’ve discussed POP so much already on AppCoda, I’m not going to keep making my case for it’s benefits yet again. Please check out my previous articles if you need a refresher.
The possibilities
I’ve written all the code shown in this tutorial in an Xcode playground available on GitHub. Please download this playground so you can follow along.
As a teaser, to get your interest up, let me show you for real how my generic doubly linked list can store and let you manipulate any Swift type — and even allow you to take advantage of OOP polymorphism. Watch as I create a linked list of class type UIControl, add instances of class types like UITextField, UIStepper, and UIButton, take advantage of the fact that all the latter types are descendents of UIControl, and manipulate those controls. Here’s a snippet of code from my playground:
do {

    // Instantiate various UIControls.
    let textField : UITextField = UITextField()
    let slider : UISlider = UISlider()
    let segmented : UISegmentedControl = UISegmentedControl()
    let stepper: UIStepper = UIStepper()
    let button: UIButton = UIButton()

    // Create a linked list of type UIControl.
    var uiControlList = LinkedList()
    
    // Append and insert various UIControl descendents as
    // nodes to linked list, giving each a meaningful tag.
    uiControlList.append(Node(with: textField, named: "text field"))
    uiControlList.append(Node(with: slider, named: "slider"))
    uiControlList.append(Node(with: segmented, named: "segmented"))
    uiControlList.insert(Node(with: button, named: "button"), after: "slider")
    uiControlList.append(Node(with: stepper, named: "stepper"))
    
    // Manipulate UIControl descendents using subscript.
    uiControlList["slider"]?.payload?.isEnabled = true
    uiControlList["stepper"]?.payload?.frame // "Show Result"
    uiControlList["text field"]?.payload?.textInputMode
    uiControlList["segmented"]?.payload?.setNeedsDisplay()
    
    // Print tags of all nodes in linked list
    // in their current ordering from "head" to
    // "tail."
    uiControlList.showAll()
    
}

Notice that I emphasized the word class in the previous discussion to highlight the fact that each Node in my uiControlList instance holds a reference to a UIControl, and therefore I can manipulate — mutate — each control in the list.
Here’s a screenshot showing how I inspected an instance of UIStepper using my playground’s “Show Result” button. Remember that I created an instance of UIStepper, added it to a Node in my linked list, and then accessed its frame property:

Since I’m using classes, ARC memory management is involved, and I included some code for memory management in my linked list protocol extension. Notice that my console output includes information from print statements I encoded to show the allocation and deallocation of memory for Node class instances stored in my list. I defined local scope to force explicit allocation and deallocation. Remember that when developing with classes, you do need to be mindful of memory management. Any time you use reference types (e.g., classes, closures), there is the possibility for memory leaks which can lead to apps crashing. My code is not leaking:
Allocating linked list
Allocating node tagged: [text field]
Appending [text field] to head
Allocating node tagged: [slider]
Appending [slider] to tail
Allocating node tagged: [segmented]
Appending [segmented] to tail
Allocating node tagged: [button]
Inserting [button]
Allocating node tagged: [stepper]
Appending [stepper] to tail

-------------------------
Printing list:

[text field]
[slider]
[button]
[segmented]
[stepper]
-------------------------

Deallocating node tagged: [segmented]
Deallocating node tagged: [button]
Deallocating node tagged: [slider]
Deallocating node tagged: [text field]
Deallocating node tagged: [stepper]
Deallocating linked list

We’ll see later on how we can make our code more type specific/safe, take advantage of OOP inheritance, and define a class UIControlList: LinkedList.
Storing custom types
Suppose you create a value type called Point in which you wish to use to store screen coordinates. Yes, you can store those in my linked list. Here’s the code:
struct Point {
    
    let x: Int
    let y: Int
    
}

do {
    
    var pointList = LinkedList()

    let point1 = Point(x: 1, y: 1)
    let point2 = Point(x: 2, y: 2)
    let point3 = Point(x: 3, y: 3)

    let node1 = Node(with: point1, named: "point1")
    let node2 = Node(with: point2, named: "point2")
    let node3 = Node(with: point3, named: "point3")
    
    pointList.append(node1)
    pointList.insert(node2, after: "point1")
    pointList.append(node3)
    
    pointList.showAllInReverse()
    
    pointList.delete(node1)
    
}

Here’s the console output from running the previous code snippet in my playground:
Allocating linked list
Allocating node tagged: [point1]
Allocating node tagged: [point2]
Allocating node tagged: [point3]
Appending [point1] to head
Appending [point2] to tail
Appending [point3] to tail

-------------------------
Printing list in reverse:

[point3]
[point2]
[point1]
-------------------------

Delete head [Optional("point1")] with followers
Deallocating node tagged: [point1]
Deallocating node tagged: [point2]
Deallocating node tagged: [point3]
Deallocating linked list

Notice that despite the fact that I only deleted one of the three original nodes that I added to pointList, all memory allocated for the nodes referencing the Point instances is freed.
Keep this in mind if using my LinkedList with value types, like my Point struct in LinkedList:
The most basic distinguishing feature of a value type is that copying — the effect of assignment, initialization, and argument passing — creates an independent instance with its own unique copy of its data…
Data structures
Successful programmers know about data structures. I’ve found that some developers take them for granted and, while they can use data structures, they don’t know much about those same structures. Examples include array, stack, queue, and heap. I showed you how to develop POP, fully-functional and generic stack and queue data structures here on AppCoda. Most applications would be useless without data. If you don’t know at least the basic internals of some of the most common data structures, you’re going to have trouble developing innovative code and, probably of most import, you won’t be a decent troubleshooter.
Theory: The linked list data structure
A doubly linked list (DLL) is an unsorted collection of related data — even a collection of other data structures. Some prefer to call a DLL a “sequence” of data elements. This data structure stores a list of “nodes.” Each node stores data (or a reference to data), a reference to the preceding node in the list, and a reference to the following node in the list. Since nodes are not sorted in any particular order and can be handled independently, doubly linked lists are very useful when managing large/many pieces of data.
Some examples of usage of linked lists include memory management of the heap, web browser history that allows you to navigate forward and backwards, and in implementations of queues and stacks.
A DLL is an ideal data structure to use when you don’t know how many pieces of data you want to store and you don’t care what order in which they’re stored (or ordering is less of a concern to you). Since order is irrelevant, adding (appending) and removing nodes can be as cheap as O(1) because of the list’s dynamic structure.
Inserting a node into the middle of the list can be as cheap as O(1) if you have a reference to a immediate neighbor node. The same goes for deleting from the middle of the list.
If you don’t know where a node is located in the DLL, then deleting it requires finding it first, which could be as expensive as O(n). The same goes for inserting a node at a particular position in the list.
A picture of a DLL with 4 nodes will help you to understand my previous paragraphs on theory. This image should give you an idea of why a DLL is often call a “sequence:”

The blue arrows should prove to you that this list is indeed linked as we can get from one node to the next both forwards and backwards, hence the term “doubly linked.”
There’s a lesson about performance buried in the previous paragraphs: If you want to try to keep your DLL operations at O(1), then keep a node around after inserting it so you’ll have its next and previous references (“pointers”). Similarly, if you’ve paid O(n) to find a node, keep a reference to it so you know about its neighbors.
The head.previous always points to nil. The tail.next always points to nil.
FYI: You can understand — visualize — a “simple” or “singly” linked list as the same structure in the preceding diagram without the previous property and thusly without its corresponding previous blue arrow.
The old debate
I’m not going to fall into the “arrays are better and faster than linked lists” or conversely, the “linked lists are faster and better than arrays” arguments. But I will discuss some of the background behind these arguments. I’ve been around computer science for 30 years and seen old assumptions cast aside by improvements and optimizations to memory management.
There’ve been many times when I encountered the design requirement to store hundreds of thousand up to millions of related items in memory. So the question of whether to use an array, maybe a dictionary, or a linked list was of paramount importance because of performance requirements and/or resource limitations.
It used to be a given that array elements were stored contiguously in memory and that array size had to be stated up front, before the array was used. I’m talking about back in the days of C language programming. It was also a given that inserting a new element into the middle of an array was a relatively expensive process, of O(n) complexity.
But now looking at the Swift Array documentation, I’ve found that sometimes array elements are stored contiguously in memory and sometimes not, depending on the circumstances. The documentation also implies that an operation like insertion or deletion may cost less than O(n) because of a smart array resizing strategy.
I’m still thinking about this. If you want to join the nightmare, follow this link, this one, or this one.
Note: Yes, CPUs are getting faster and faster, we’ve got hardware and software caching, languages are getting optimizing continuously… The debate about array versus linked list will probably continue. Who cares. At some point, you’re likely to encounter a linked list in your work. This tutorial is an opportunity for you to learn how linked lists, and how data structures in general, work.
Doubly linked list implementation in Swift
Let’s build a DLL together in Swift. Remember that a DLL is a collection/sequence of nodes, so we’ll start by formally defining a Node. Then we’ll build an actual list using nodes, and go through each common linked list operation.
Note: There are a lot of DLL implementations out there, many with lots and lots of features. My purpose is not to go crazy here, but to simply introduce you to the concept of linked lists, and show you some extra magic with generics, POP, and OOP. I won’t be showing you every possibility out there. So no deleteAfter, deleteBefore, deleteAtIndex, insertBefore, insertAtIndex, blah, blah, blah…
The node
As you’ve probably gleaned already from my previous diagram and discussion, the node is at the heart of a DLL. Let’s visualize my Node type:

Remember that protocols offer reusability in that many other types can adopt them. I’ve created the following NodeProtocol because not only does my DLL depend on nodes, but so do many other data structures:
protocol NodeProtocol: class {

    associatedtype AnyType
    
    var tag: String? { get }
    var payload: AnyType? { get set }
    var next: Self? { get set }
    var previous: Self? { get set }
    
    init(with payload: AnyType, named tag: String)
}

We’ll discuss the class restriction on NodeProtocol very soon, but please bear with me. Remember that I’m making this DLL generic. From the Swift documentation on generics:
When defining a protocol, it’s sometimes useful to declare one or more associated types as part of the protocol’s definition. An associated type gives a placeholder name to a type that is used as part of the protocol. The actual type to use for that associated type isn’t specified until the protocol is adopted. Associated types are specified with the associatedtype keyword.
Here’s my generic node type Node:
final class Node: NodeProtocol {

    var tag: String?
    var payload: AnyType?
    var next: Node?
    var previous: Node?
    
    init(with payload: AnyType, named tag: String) {
    
        // Stores a reference when using classes;
        // stores a copy when using value types.
        self.payload = payload
        self.tag = tag
        
        print("Allocating node tagged: [\(tag)]")
        
    }
    
    deinit {
        print("Deallocating node tagged: [\(tag!)]")
    }
}

The AnyType between the angle brackets, as in Node, is a placeholder for some Swift built-in type or some custom type we define and fill in when actually declaring an instance of Node. This  notation, plus the fact that Node has adopted NodeProtocol with an associatedtype, means we’ll be able to create Node instance’s whose payload is literally any type. It also means that the next and previous properties will be references to Node instances proximate to other Node instances in our DLL.
The tag property is an identifier I always use when building DLLs. It makes it easy for me to find and reference Node instances in my DLLs using meaningful names.
The init method includes a print showing Node memory allocation. The deinit method similarly uses print to show Node memory deallocation.
Why we need reference semantics
Let’s talk about why NodeProtocol is marked as class. The whole concept of a node in a DLL is antithetical to a value type. How could we build a list of Node instances if the their next and previous properties were values that contained only data? It wouldn’t even make sense.
In order for us to build a list of linked Node instances, we use reference semantics and reference types, i.e., classes. The next and previous properties of each Node object/instance must be references to other Node objects/instances.
Making the payload property of a Node into a reference (pointer) affords you flexibility and possibly some efficiency, especially if your list contains large payload items and/or a large number of payload items. You can create objects anywhere and add them as references to the linked list. Your list doesn’t actually store copies of data inside the list. It simply stores references to instances you’ve already created and are manipulating. If using classes, once there’s a reference to whatever type a payload instance points to, the underlying object is kept alive and not deallocated since the reference count to it was increased by one when making it part of a Node.
Here’s a visual representation of my DLL storing UIControl instances, as we saw example code for at the beginning of this tutorial:

Remember that I showed you Apple’s definition of a value type at the start of this tutorial in the section entitled “The possibilities.” I want you to think about this carefully: The behavior of the Node type’s payload property is going to exhibit value semantics with value types and reference semantics with reference types. That might sound obvious, but please consider carefully.
Why my Node class is final
If I don’t mark my Node class as final, I get the following error messages:
Protocol 'NodeProtocol' requirement 'next' cannot be satisfied by a non-final class ('Node') because it uses 'Self' in a non-parameter, non-result type position

Protocol 'NodeProtocol' requirement 'previous' cannot be satisfied by a non-final class ('Node') because it uses 'Self' in a non-parameter, non-result type position

As best as I can understand it, the problem stems from the fact that I’m imposing a Self requirement in a protocol, where Self is used as a type in a declaration, which is then adopted by a class. In this specific case, I cannot impose a Self requirement via a protocol on classes that are not declared as final. Say I created a non-final class that conformed to a protocol with Self as a type requirement — call it ClassParent. If I could create a descendent of the non-final class, call it ClassChild, it would always interpret Self as its parent class, ClassParent, which would be completely incorrect, and would violate the parent’s Self requirement stemming from its protocol conformance.
In this case, Self literally means only the conforming class. Parenthetically, my type Node type already can provide linked list node functionality for any type, so what exactly would I gain by overriding the purpose of next and previous? What would subclassing my Node type mean, which already is generic, and where next and previous are defined in the NodeProtocol as instances of Self?
This is getting almost metaphysical, and is beyond the scope of this tutorial. If you want to pursue this topic, I’ve found some links you can study that provide explanations and workarounds for the “non-final class” class error here, here, and here.
Protocol-oriented linked list
To make my DLL portable, I defined almost all its functionality in a protocol and protocol extension. Let’s have a look and then talk about it. Note that we won’t look at the protocol extension’s contents until later:
protocol LinkedListProtocol {
    
    associatedtype AnyType
    
    var head: Node? { get set }
    var tail: Node? { get set }
    mutating func append(_ newNode: Node)
    mutating func insert(_ newNode: Node, after nodeWithTag: String)
    mutating func delete(_ node: Node)
    func showAll()
    func showAllInReverse()
    subscript(tag: String) -> Node? { get }
    func prepareForDealloc()
    
}

extension LinkedListProtocol {
    
    // THERE'S A BUNCH OF CODE HERE.
    
...

} // end extension LinkedListProtocol

class LinkedList : LinkedListProtocol {
    
    var head: Node?
    var tail: Node?
    
    init() {
        head = nil
        tail = head
        print("Allocating linked list")
    }
    
    deinit {
        prepareForDealloc()
        head = nil
        tail = nil
        print("Deallocating linked list")
    }
    
} // end class LinkedList

Again, the  notation, as in LinkedList, plus the fact that LinkedList has adopted LinkedListProtocol with an associatedtype, means we’ll be able to create LinkedList instance’s that can store sequences of any type. Remember how I instantiated an instance of LinkedList at the beginning of this tutorial?
Notice that even though a DLL is unsorted, it still is a sequence of Node instances. That’s important to understand because, when we don’t know where we are in the list, we’ve got to be able to “travel” across the sequence of nodes in order to find a node.
Use case for explaining code
I wrote several rounds of code that exercises my DLL functionality in the protocol, protocol extension, and class we just reviewed. Note that all functionality for my DLL is expressed in the LinkedListProtocol extension. The following code will help us to discuss the extension’s methods:
do {
    
    print("in local scope")
    // declare a linked list of type UIView
    // and initialize it
    var linkedList = LinkedList()
    
    // create some nodes to be added to my list,
    // initializing each with a UIVIew and tag/name
    let node1 = Node(with: 1.0, named: "Double 1.0")
    let node2 = Node(with: 2.0, named: "Double 2.0")
    let node2_2 = Node(with: 2.2, named: "Double 2.2")
    let node3 = Node(with: 3.0, named: "Double 3.0")
    let node4 = Node(with: 4.0, named: "Double 4.0")
    let node5 = Node(with: 5.0, named: "Double 5.0")

    // add the nodes to my linked list
    linkedList.append(node1)
    linkedList.append(node2)
    linkedList.append(node3)
    linkedList.insert(node2_2, after: "Double 2.0")
    linkedList.append(node4)
    linkedList.append(node5)
    
    // test the subscript
    linkedList["Double 3.0"]?.tag
    // "Double 3.0"
    
    // print the list to console
    linkedList.showAll()
    
    // print the list to console in reverse
    linkedList.showAllInReverse()

    // delete nodes in random order
    linkedList.delete(node3)
    linkedList.delete(node1)
    linkedList.delete(node2_2)
    linkedList.delete(node4)
    linkedList.delete(node5)
    linkedList.delete(node2)
    
    // show empty list
    linkedList.showAll()
    
}

Here’s the playground console output corresponding to the code I just showed you:
in local scope
Allocating linked list
Allocating node tagged: [Double 1.0]
Allocating node tagged: [Double 2.0]
Allocating node tagged: [Double 2.2]
Allocating node tagged: [Double 3.0]
Allocating node tagged: [Double 4.0]
Allocating node tagged: [Double 5.0]
Appending [Double 1.0] to head
Appending [Double 2.0] to tail
Appending [Double 3.0] to tail
Inserting [Double 2.2]
Appending [Double 4.0] to tail
Appending [Double 5.0] to tail

-------------------------
Printing list:

[Double 1.0]
[Double 2.0]
[Double 2.2]
[Double 3.0]
[Double 4.0]
[Double 5.0]
-------------------------


-------------------------
Printing list in reverse:

[Double 5.0]
[Double 4.0]
[Double 3.0]
[Double 2.2]
[Double 2.0]
[Double 1.0]
-------------------------

Delete internal node: [Optional("Double 3.0")]
Delete head [Optional("Double 1.0")] with followers
Delete internal node: [Optional("Double 2.2")]
Delete internal node: [Optional("Double 4.0")]
Delete tail [Optional("Double 5.0")] with predecessors
Delete head [Optional("Double 2.0")]

-------------------------
Printing list:

-------------------------

Deallocating node tagged: [Double 5.0]
Deallocating node tagged: [Double 4.0]
Deallocating node tagged: [Double 3.0]
Deallocating node tagged: [Double 2.2]
Deallocating node tagged: [Double 2.0]
Deallocating node tagged: [Double 1.0]
Deallocating linked list

When using a DLL, always…
Remember to always think about a Node instance’s next and previous references when adding/deleting that node to/from the list and when traversing the list. What do we always say? “The head.previous always points to nil. The tail.next always points to nil.” Refer to my diagram of the DLL up above as many times as you need.
Initializing the DLL
Initially, a newly-instantiated LinkedList object has a head and tail that are both nil:
    init() {
        head = nil
        tail = head
        print("Allocating linked list")
    }

Adding — appending — a Node
The first time we add a Node to the DLL, it becomes the head. At this point, the head is the same as the tail. After appending the first Node, we subsequently add Node instances to the tail. This just makes common sense and is the prevailing convention. Appending is always cheap. It’s O(1):
...
extension LinkedListProtocol {
    
    mutating func append(_ newNode: Node) {
        
        if let tailNode = tail {
            
            print("Appending [\(newNode.tag!)] to tail")
            tailNode.next = newNode
            newNode.previous = tailNode
            
        }
        else {
            
            print("Appending [\(newNode.tag!)] to head")
            head = newNode
            
        } // end else
        
        tail = newNode
        
    } // end func append
...

Deleting a Node
I’ve only written code for deleting nodes if you already have a reference to a Node instance, which makes my delete method cheap at O(1). I could’ve gone on forever writing specialized methods like deleteAfter, deleteBefore, deleteAtIndex, etc., but I didn’t because the purpose here is to learn how a linked list works in general. Note that my code makes sure there are no strong references vis-a-vis next and previous properties of Node instances when that instance is removed from the list.
Here’s the deletion code and then we’ll discuss:
...
    mutating func delete(_ node: Node) {
        
        // Remove the head?
        if node.previous == nil {
            
            if let nodeAfterDeleted = node.next {
                
                print("Delete head [\(node.tag)] with followers")
                nodeAfterDeleted.previous = nil
                head?.next = nil
                head = nil
                head = nodeAfterDeleted
                
                node.next = nil
                node.previous = nil
                
            }
            else
            {
                
                print("Delete head [\(node.tag)]")
                head = nil
                tail = nil
                
                node.next = nil
                node.previous = nil
                
            }
            
        } // end remove head
            
        // Remove the tail?
        else if node.next == nil {
            
            if let deletedPreviousNode = node.previous {
                
                print("Delete tail [\(node.tag)] with predecessors")
                deletedPreviousNode.next = nil
                tail?.previous = nil
                tail = nil
                node.next = nil
                tail = deletedPreviousNode
                
                node.next = nil
                node.previous = nil
                
            }
            else {
                
                print("Delete tail [\(node.tag)]")
                head = nil
                tail = nil
                
                node.next = nil
                node.previous = nil
                
            }
            
        } // end remove tail
            
        // Remove node BETWEEN head and tail?
        else {
            
            if let deletedPreviousNode = node.previous,
                let deletedNextNode = node.next {
                
                node.next = nil
                node.previous = nil
                print("Delete internal node: [\(node.tag)]")
                
                deletedPreviousNode.next = deletedNextNode
                deletedNextNode.previous = deletedPreviousNode
                
            }
            
        } // end remove in-between node
        
    } // end func delete
...

Deleting the head

The head.previous always points to nil. Remember that and everything in the section entitled “When using a DLL, always…” and you’ll understand.
Deleting the tail

The tail.next always points to nil. Remember that and everything in the section entitled “When using a DLL, always…” and you’ll understand.
Deleting a node in the “middle” of the list

Say we want to delete some Node instance that is somewhere in the “middle” of our DLL. In other words, it has neighbors and is not the head or tail. Here’s the Node instance to delete:

Let’s save references to the Node instances that precede and follow the Node to be deleted. These are obtained from the previous and next properties of the Node to be deleted:

Let’s assign nil to the about-to-be-deleted node’s next and previous properties so they won’t hold strong references to neighboring Node instances and thus won’t interfere with their eventual ARC deallocation:

Finally, let’s take the deleted Node out of the sequence completely. We make its formerly preceding Node instance’s next property point to its formerly following Node. We make its formerly following Node instance’s previous property point to its formerly preceding Node. Here it is:

Inserting a Node
I’ve limited my DLL insertion functionality, not to be confused with appending, to inserting a Node immediately after a known and preexisting Node. First we use the traversal logic, covered in the next section, to find the Node with a given tag. This means my insertion cost can be up to O(n). We know that we’ll insert the new Node after the Node we found with tag. I’ll cover the case of inserting a new Node in the “middle” of the list and leave the single edge case, that of inserting right after head, for you to glean from all the other explanations and info shown herein.
This all boils down to 1) configuring the next and previous references of the new Node, 2) configuring the next reference of the new node’s preceding neighbor, and 3) configuring the previous reference of the new node’s following neighbor, like so:
This just shows the new node:

Here are steps 1, 2, and 3:



Finally, we have:

Here’s the insertion code:
...
    mutating func insert(_ newNode: Node, after nodeWithTag: String) {
        
        if head == nil {
            return
        }
            
        else {
            
            var currentNode = head
            
            while currentNode != nil {
                
                if nodeWithTag == currentNode?.tag {
                    
                    // If the current node with matching tag is
                    // NOT the tail...
                    if currentNode?.next != nil {
                        
                        // ... then insert new node "after"
                        // the current node.
                        let newNextNode = currentNode?.next
                        currentNode?.next = newNode
                        newNextNode?.previous = newNode
                        newNode.previous = currentNode
                        newNode.next = newNextNode
                        currentNode = nil
                        print("Inserting [\(newNode.tag!)]")
                        
                    }
                    else { // Append to list with single head
                           // (which means tail = head).
                        
                        append(newNode)
                        currentNode = nil
                        
                    }
                    
                } // end if nodeWithTag == currentNode?.tag
                    
                else {
                    currentNode = currentNode?.next
                }
                
            } // end while
            
        } // end else
        
    } // end func insert
...

Traversing the list
We can traverse the list, going from the beginning to end, by following the trail mapped out by each Node instance’s next property, starting at the first Node in the list, known as the head. We use the tag property of each Node to identify it — i.e., traverse until we find a tag that matches a String that we used to create (initialize) a Node. We can similarly traverse (and search) our list, going from the end to beginning (in “reverse”), by following the trail mapped out by each Node instance’s previous property, starting at the last Node in the list, known as the tail.
Since traversal means potentially going through every node in the list, that means it is pricey at O(n). Study question: Since you’ve got both forward and reverse traversal, can you think of a way to optimize?
After reading the previous prose and looking at the blue arrows in my diagram of a DLL above, you should get the following code:
...
    func showAll() {
        
        print("\n-------------------------")
        print("Printing list:\n")
        
        var nextNode: Node?
        
        if let head = head {
            
            nextNode = head
            
            repeat {
                
                if let tag = nextNode?.tag {
                    print("[\(tag)]")
                }
                    
                nextNode = nextNode?.next
                
            } while (nextNode != nil)
            
        } // end if let head = head
        
        print("-------------------------\n")
        
    } // end func showAll()
    
    func showAllInReverse()
    {
        
        print("\n-------------------------")
        print("Printing list in reverse:\n")
        
        var previousNode: Node?
        
        if let tail = tail {
            
            previousNode = tail
            
            repeat {
                
                if let tag = previousNode?.tag {
                    print("[\(tag)]")
                }
                
                previousNode = previousNode?.previous
                
            } while (previousNode != nil)
        }
        print("-------------------------\n")
        
    } // end func showAllInReverse()
...

List subscript
I’ve implemented a Swift subscript using the same logic discussed in the previous section entitled “Traversing the list”. Here, I’ve used the tag value of node, a String, as the subscript:
...
    subscript(tag: String) -> Node? {
        
        if head == nil {
            return nil
        }
            
        else {
            
            var currentNode = head
            
            while currentNode != nil {
                
                if tag == currentNode?.tag {
                    return currentNode
                }
                else {
                    currentNode = currentNode?.next
                }
                
            } // end while
            
            return nil
            
        } // end else
        
    } // end subscript
...

ARC memory deallocation for DLL
I hope you noticed my call to LinkedListProtocol extension method prepareForDealloc() in my LinkedList class’s deinit method:
...
    deinit {
        prepareForDealloc()
        head = nil
        tail = nil
        print("Deallocating linked list")
    }
...

ARC will only deallocate a class instance from memory if its reference count is zero. As long as there is 1 (one) or more reference(s) to that instance, its memory cannot be deallocated. Since so many references are being used in my DLL code, I wanted to prevent memory leaks.
My prepareForDealloc() method makes sure no Node instances in the DLL hold strong references to each other by starting at the tail, traversing the list in reverse, and setting each Node instance’s next and previous properties to nil:
...
    // Unlink all nodes so there are no
    // strong references to prevent
    // deallocation.
    func prepareForDealloc() {
        
        var currentNode: Node?
        
        if var tail = tail {
            
            currentNode = tail
            
            repeat {
                
                if let tag = currentNode?.tag {
                    //print("\(tag)")
                }
                
                tail = currentNode!
                currentNode = currentNode?.previous
                tail.previous = nil
                tail.next = nil
                
            } while (currentNode != nil) // nil is head
            
        } // end if var tail = tail
        
    } // end func showAllInReverse(
    
} // end extension LinkedListProtocol
...

Inheriting from my LinkedList class
I wanted to show you that you can specialize my LinkedList class by inheriting from it. In other words, you can create a subclass of LinkedList which is tied to any Swift built-in or custom type. You can use or override existing LinkedListProtocol extension functionality. Most importantly, you can add features that are specific to the type to which you bind the LinkedList subclass.
I rewrote the code shown at the beginning of this tutorial. Instead of simply declaring an instance of the LinkedList class typed for UIControl, which is still pretty powerful, I declared a class inheriting from LinkedList. Let’s look at the subclass first:
class UIControlList: LinkedList {
    
    func shouldEnable(_ yesOrNo: Bool) {

        if head == nil {
            return
        }
            
        else {
            
            var currentNode = head
            
            while currentNode != nil {
                
                currentNode?.payload?.isEnabled = yesOrNo
                currentNode = currentNode?.next
                
            }
            
        } // end else

    } // end func shouldEnable()
    
    func showAll() {
        
        print("\n-------------------------")
        print("Printing list:\n")
        
        var nextNode: Node?
        
        if let head = head {
            
            nextNode = head
            
            repeat {
                
                if let tag = nextNode?.tag {
                    print("[\(tag)]'s status is \(nextNode?.payload?.isEnabled)")
                }
                
                nextNode = nextNode?.next
                
            } while (nextNode != nil)
            
        } // end if let head = head
        
        print("-------------------------\n")
        
    } // end func showAll()
    
} // end class UIControlList

Here’s code that instantiates and uses the new UIControlList subclass:
do {
    
    // Instantiate various UIControls.
    let textField : UITextField = UITextField()
    let slider : UISlider = UISlider()
    let segmented : UISegmentedControl = UISegmentedControl()
    let stepper: UIStepper = UIStepper()
    let button: UIButton = UIButton()
    
    // Create a linked list of type UIControl.
    var uiControlList = UIControlList()
    
    // Append and insert various UIControl descendents as
    // nodes to linked list, giving each a meaningful tag.
    uiControlList.append(Node(with: textField, named: "text field"))
    uiControlList.append(Node(with: slider, named: "slider"))
    uiControlList.append(Node(with: segmented, named: "segmented"))
    uiControlList.insert(Node(with: button, named: "button"), after: "slider")
    uiControlList.append(Node(with: stepper, named: "stepper"))
    
    // Manipulate UIControl descendents using subscript.
    uiControlList["slider"]?.payload?.isEnabled = true
    uiControlList["stepper"]?.payload?.frame // "Show Result"
    uiControlList["text field"]?.payload?.textInputMode
    uiControlList["segmented"]?.payload?.setNeedsDisplay()
    
    // Use feature available to all UIControls.
    uiControlList.shouldEnable(true)
    
    // Print tags of all nodes in linked list
    // in their current ordering from "head" to
    // "tail."
    uiControlList.showAll()
    
}

Here’s playground console output from the immediately previous code snippet:
Allocating linked list
Allocating node tagged: [text field]
Appending [text field] to head
Allocating node tagged: [slider]
Appending [slider] to tail
Allocating node tagged: [segmented]
Appending [segmented] to tail
Allocating node tagged: [button]
Inserting [button]
Allocating node tagged: [stepper]
Appending [stepper] to tail

-------------------------
Printing list:

[text field]'s status is Optional(true)
[slider]'s status is Optional(true)
[button]'s status is Optional(true)
[segmented]'s status is Optional(true)
[stepper]'s status is Optional(true)
-------------------------

Deallocating node tagged: [segmented]
Deallocating node tagged: [button]
Deallocating node tagged: [slider]
Deallocating node tagged: [text field]
Deallocating node tagged: [stepper]
Deallocating linked list

Conclusion
The code in this tutorial should prove that you don’t have to be a 100%-only POP or a 100%-only OOP developer. The two technologies not only can coexist, but they complement each other. It behooves you to be a flexible and open minded developer. I’m so old 🙁 that I remember when OOP first debuted. There was so much resistance, but after several years went by, pretty much everyone jumped on the OOP bandwagon and, before we knew it, pretty much everything was in a class and/or class library. Recently, POP debuted and I feel like I’m reliving the past. Some developers want to drop everything and rewrite all their code using protocols. Others want argue that POP is worthless. After using POP for several years, my gut instinct tells me that POP is here to stay and is very useful, but in no way does it totally devalue OOP. Both technologies have their advantages and disadvantages.
My advice is that you should be flexible and open-minded to new ideas with the caveat that there will always be flash-in-the-pan fads that come and go quickly. With experience, learning, and schooling, you’ll learn to be able to tell the difference between fads and truly novel innovations.
The advent and adoption of OOP was a truly seminal event in programming history. So was the advent of POP. You should become fluent in both and use both.





Design Patterns in Swift #3: Facade and Adapter
Andrew Jaffee — Tue, 04 Sep 2018 17:16:51 GMT


This tutorial is the third installment in our series on design patterns. I started

this series with a tutorial examining two examples of patterns in the “creational” category: factory method and singleton. I then discussed two examples of patterns in the “behavioral” category: observer and memento.
In this tutorial, I’ll explain two examples of patterns in the “structural” category: facade and adapter. I urge you to review my first two posts mentioned above so you can familiarize yourself with the concept of software design patterns. Beyond a brief reminder today of what constitutes a design pattern, I’m not going to regurgitate all the definitions again. All the information you need to get up to speed is in my first two tutorials, here and here.
Let’s briefly review some general definitions of design patterns here and in the next few sections. There are 23 classic software development design patterns probably first identified, collected, and explained all in one place by the “Gang of Four” (“GoF”), Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides in their seminal book, “Design Patterns: Elements of Reusable Object-Oriented Software.”. Remember that today we’ll focus on two of these patterns, facade and adapter, which fall into what the GoF calls the “structural” category.
Protocol-oriented code with value semantics
You’ll still find that many tutorials about design patterns contain sample code based on object-oriented programming (OOP) principles, reference semantics, and reference types (classes). I am endeavoring to create a series of tutorials on design patterns that are mostly based in protocol-oriented programming principles (POP), value semantics, and value types (structs). If you’ve reviewed the first two articles in this series, I hope you followed my advice and familiarized yourselves with POP versus OOP and reference semantics versus value semantics. If not, I strongly encourage you to get up to speed on these topics. This tutorial is solely based in POP and value semantics.
Design Patterns
Design patterns are an extremely important tool with which developers can manage complexity. It’s best to conceptualize them as generally templated techniques, each tailored to solving a corresponding, recurring, and readily identifiable problem. Look at them as a list of best practices you would use for coding scenarios that you see over and over again. To make this definition tangible, think of how many times you’ve either used code or written code that conforms to the observer design pattern.
In observer, the subject instance, usually a single critical resource, broadcasts notifications about a change in its state to many observer instances that depend on that resource. Interested observers must tell the subject instance that they’re interested in receiving notifications, in other words, they must subscribe to get notifications. Encoding iOS push notifications, where users must opt into receiving messages, is a great example of observer.
Design pattern categories
The GoF organized their 23 design patterns into three categories, “creational,” “behavioral,” and “structural.” This tutorial discusses two patterns in the structural category. Consider the word “structure,”

  “something arranged in a definite pattern of organization” and “the aggregate of elements of an entity in their relationships to each other.”
– https://www.merriam-webster.com/dictionary/structure
Structural design patterns are meant to help you to clearly define the purpose of a segment of code and clearly specify how other code interacts with that segment. Most patterns in this category enable you to simplify the use of your code. We can usually simplify use of code by creating an easily readable interface to that code. Since pieces/segments of code don’t exist in a vacuum, providing a good interface to a code segment should obviously and cleanly define the possible relationships that can be built between that segment and other segments.
The facade design pattern

  The word “facade” is defined as “any face of a building given special architectural treatment” and “a false, superficial, or artificial appearance or effect.”
– https://www.merriam-webster.com/dictionary/facade
In most cases, we use the facade pattern to create one simple interface to a group of other, possibly many, and usually complex, interfaces. You have probably already created what are commonly called “wrappers” where you built a simple interface to a complex codebase with the purpose of simplifying the use of that codebase.
Use case for facade design pattern app
My facade example playground, available on GitHub, showcases how this pattern can create one simple interface to the sandboxed file system available to each iOS app. The iOS file system is a huge OS subsystem, allowing you to create, read, delete, move, rename, and copy files and directories; allowing you to get (and sometimes set) meta data about files and directories, e.g., list the files in a directory; allowing you to check the status of files/directories, e.g., determine if a file is writable; and, providing you with the names of predefined directories in which Apple prefers that you work. Note that you can do much more than what I just listed.
Since the iOS file system is such a grand topic with many different features and functions, it is an ideal candidate for using the facade design pattern to simplify its usage. A facade interface allows you to leave out functionality you don’t need and that may clutter your code. Conversely, a facade interface allows you to specify only the functionality you need for a particular app, or in my case, to limit functionality to what I have found to be only the features I have used over time, and thus make my facade reusable, extensible, and maintainable for many of my apps.
I used protocol-oriented programming and value semantics for dividing and conquering major features of the iOS file system into reusable and extensible units: protocols and protocol extensions.
I then composed four protocols into one struct that represents a sandboxed iOS directory available to all iOS apps (see also here). Since you’re likely to run across the topics of POP and value semantics more and more, note that the terms composed and composition are synonymous herein.
Note that I left Swift error handling and more generic error checking out of the code shown below solely for didactic purposes, i.e., so you can more easily concentrate only on understanding use of the facade pattern.
Sample code for the facade design pattern
Let’s walk through my code. Make sure you follow along with my code in the playground hosted on GitHub. Here’s a list of predefined directories in which Apple prefers you do much of your iOS app’s work:
enum AppDirectories : String {
    case Documents = "Documents"
    case Inbox = "Inbox"
    case Library = "Library"
    case Temp = "tmp"
}

By constraining my file manipulation code to these known directories, I control complexity, simplify, and stay within the bounds of the Human Interface Guidelines.
Before looking at my core code for file manipulation, let’s first look at my facade design pattern-based interface as that’s the topic of this tutorial. I created the iOSAppFileSystemDirectory struct as a simple and readable interface to common file system features available for each of the directories specified in my AppDirectories enum. Yes, I could get involved with things like the creation of symbolic links or the use of fine grained manipulation of individual files using the FileHandle class, but I almost never use these features, and most importantly, I’m deliberately keeping things simple.
I’ve created a facade composed of four protocols (I know you see three immediately below, but one of the protocols inherits from another):
struct iOSAppFileSystemDirectory : AppFileManipulation, AppFileStatusChecking, AppFileSystemMetaData {
    
    let workingDirectory: AppDirectories

    init(using directory: AppDirectories) {
        self.workingDirectory = directory
    }

    func writeFile(containing text: String, withName name: String) -> Bool {
        return writeFile(containing: text, to: workingDirectory, withName: name)
    }
    
    func readFile(withName name: String) -> String {
        return readFile(at: workingDirectory, withName: name)
    }
    
    func deleteFile(withName name: String) -> Bool {
        return deleteFile(at: workingDirectory, withName: name)
    }
    
    func showAttributes(forFile named: String) -> Void {
        let fullPath = buildFullPath(forFileName: named, inDirectory: workingDirectory)
        let fileAttributes = attributes(ofFile: fullPath)
        for attribute in fileAttributes {
            print(attribute)
        }
    }
    
    func list() {
        list(directory: getURL(for: workingDirectory))
    }
    
} // end struct iOSAppFileSystemDirectory

Here’s some code that tests my iOSAppFileSystemDirectory struct:
var iOSDocumentsDirectory = iOSAppFileSystemDirectory(using: .Documents)

iOSDocumentsDirectory.writeFile(containing: "New file created.", withName: "myFile3.txt")
iOSDocumentsDirectory.list()
iOSDocumentsDirectory.readFile(withName: "myFile3.txt")
iOSDocumentsDirectory.showAttributes(forFile: "myFile3.txt")
iOSDocumentsDirectory.deleteFile(withName: "myFile3.txt")

Here’s the output to console from executing the previous code snippet in my playground:
----------------------------
LISTING: /var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Facade-Design-Pattern-1C4BD3E3-E23C-4991-A344-775D5585D1D7/Documents

File: "myFile3.txt"
File: "Shared Playground Data"

----------------------------

File created with contents: New file created.

(key: __C.FileAttributeKey(_rawValue: NSFileType), value: NSFileTypeRegular)
(key: __C.FileAttributeKey(_rawValue: NSFilePosixPermissions), value: 420)
(key: __C.FileAttributeKey(_rawValue: NSFileSystemNumber), value: 16777223)
(key: __C.FileAttributeKey(_rawValue: NSFileExtendedAttributes), value: {
    "com.apple.quarantine" = <30303836 3b356238 36656364 373b5377 69667420 46616361 64652044 65736967 6e205061 74746572 6e3b>;
})
(key: __C.FileAttributeKey(_rawValue: NSFileReferenceCount), value: 1)
(key: __C.FileAttributeKey(_rawValue: NSFileSystemFileNumber), value: 24946094)
(key: __C.FileAttributeKey(_rawValue: NSFileGroupOwnerAccountID), value: 20)
(key: __C.FileAttributeKey(_rawValue: NSFileModificationDate), value: 2018-08-29 18:58:31 +0000)
(key: __C.FileAttributeKey(_rawValue: NSFileCreationDate), value: 2018-08-29 18:58:31 +0000)
(key: __C.FileAttributeKey(_rawValue: NSFileSize), value: 17)
(key: __C.FileAttributeKey(_rawValue: NSFileExtensionHidden), value: 0)
(key: __C.FileAttributeKey(_rawValue: NSFileOwnerAccountID), value: 502)

File deleted.

Let’s briefly discuss the protocols that were used to compose iOSAppFileSystemDirectory. Here we have the AppDirectoryNames protocol and protocol extension which compartmentalize the retrieval of full paths of type URL to the Apple-predefined directories as specified in my AppDirectories enum:
protocol AppDirectoryNames {
    
    func documentsDirectoryURL() -> URL
    
    func inboxDirectoryURL() -> URL
    
    func libraryDirectoryURL() -> URL
    
    func tempDirectoryURL() -> URL
    
    func getURL(for directory: AppDirectories) -> URL
    
    func buildFullPath(forFileName name: String, inDirectory directory: AppDirectories) -> URL
    
} // end protocol AppDirectoryNames

extension AppDirectoryNames {
    
    func documentsDirectoryURL() -> URL {
        return FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
    }
    
    func inboxDirectoryURL() -> URL {
        return FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent(AppDirectories.Inbox.rawValue) // "Inbox")
    }
    
    func libraryDirectoryURL() -> URL {
        return FileManager.default.urls(for: FileManager.SearchPathDirectory.libraryDirectory, in: .userDomainMask).first!
    }
    
    func tempDirectoryURL() -> URL {
        return FileManager.default.temporaryDirectory
        //urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent(AppDirectories.Temp.rawValue) //"tmp")
    }
    
    func getURL(for directory: AppDirectories) -> URL {
        switch directory {
        case .Documents:
            return documentsDirectoryURL()
        case .Inbox:
            return inboxDirectoryURL()
        case .Library:
            return libraryDirectoryURL()
        case .Temp:
            return tempDirectoryURL()
        }
    }
    
    func buildFullPath(forFileName name: String, inDirectory directory: AppDirectories) -> URL {
        return getURL(for: directory).appendingPathComponent(name)
    }
} // end extension AppDirectoryNames

AppFileStatusChecking is my protocol and protocol extension that encapsulate getting state data about files stored in directories as specified in my AppDirectories enum. By “state,” I mean determining if a file exists, if it’s writable, etc.
protocol AppFileStatusChecking {
    func isWritable(file at: URL) -> Bool
    
    func isReadable(file at: URL) -> Bool
    
    func exists(file at: URL) -> Bool
}

extension AppFileStatusChecking {
    func isWritable(file at: URL) -> Bool {
        if FileManager.default.isWritableFile(atPath: at.path) {
            print(at.path)
            return true
        }
        else {
            print(at.path)
            return false
        }
    }
    
    func isReadable(file at: URL) -> Bool {
        if FileManager.default.isReadableFile(atPath: at.path) {
            print(at.path)
            return true
        }
        else {
            print(at.path)
            return false
        }
    }
    
    func exists(file at: URL) -> Bool {
        if FileManager.default.fileExists(atPath: at.path) {
            return true
        }
        else {
            return false
        }
    }
} // end extension AppFileStatusChecking

AppFileSystemMetaData is my protocol and protocol extension that compartmentalize listing directory contents and getting extended file attributes, both from directories as specified in my AppDirectories enum:
protocol AppFileSystemMetaData {
    func list(directory at: URL) -> Bool
    
    func attributes(ofFile atFullPath: URL) -> [FileAttributeKey : Any]
}

extension AppFileSystemMetaData
{
    func list(directory at: URL) -> Bool {
        let listing = try! FileManager.default.contentsOfDirectory(atPath: at.path)
        
        if listing.count > 0 {
            print("\n----------------------------")
            print("LISTING: \(at.path)")
            print("")
            for file in listing {
                print("File: \(file.debugDescription)")
            }
            print("")
            print("----------------------------\n")
            
            return true
        }
        else {
            return false
        }
    }
    
    func attributes(ofFile atFullPath: URL) -> [FileAttributeKey : Any] {
        return try! FileManager.default.attributesOfItem(atPath: atFullPath.path)
    }
} // end extension AppFileSystemMetaData

Finally, the AppFileManipulation protocol and protocol extension encapsulate the reading, writing, deleting, renaming, moving, copying, and changing the file extension of files located in directories as specified in my AppDirectories enum:
protocol AppFileManipulation : AppDirectoryNames {
    func writeFile(containing: String, to path: AppDirectories, withName name: String) -> Bool
    
    func readFile(at path: AppDirectories, withName name: String) -> String
    
    func deleteFile(at path: AppDirectories, withName name: String) -> Bool
    
    func renameFile(at path: AppDirectories, with oldName: String, to newName: String) -> Bool
    
    func moveFile(withName name: String, inDirectory: AppDirectories, toDirectory directory: AppDirectories) -> Bool
    
    func copyFile(withName name: String, inDirectory: AppDirectories, toDirectory directory: AppDirectories) -> Bool
    
    func changeFileExtension(withName name: String, inDirectory: AppDirectories, toNewExtension newExtension: String) -> Bool
}

extension AppFileManipulation {
    func writeFile(containing: String, to path: AppDirectories, withName name: String) -> Bool {
        let filePath = getURL(for: path).path + "/" + name
        let rawData: Data? = containing.data(using: .utf8)
        return FileManager.default.createFile(atPath: filePath, contents: rawData, attributes: nil)
    }
    
    func readFile(at path: AppDirectories, withName name: String) -> String {
        let filePath = getURL(for: path).path + "/" + name
        let fileContents = FileManager.default.contents(atPath: filePath)
        let fileContentsAsString = String(bytes: fileContents!, encoding: .utf8)
        print("File created with contents: \(fileContentsAsString!)\n")
        return fileContentsAsString!
    }
    
    func deleteFile(at path: AppDirectories, withName name: String) -> Bool {
        let filePath = buildFullPath(forFileName: name, inDirectory: path)
        try! FileManager.default.removeItem(at: filePath)
        print("\nFile deleted.\n")
        return true
    }
    
    func renameFile(at path: AppDirectories, with oldName: String, to newName: String) -> Bool {
        let oldPath = getURL(for: path).appendingPathComponent(oldName)
        let newPath = getURL(for: path).appendingPathComponent(newName)
        try! FileManager.default.moveItem(at: oldPath, to: newPath)
        
        // highlights the limitations of using return values
        return true
    }
    
    func moveFile(withName name: String, inDirectory: AppDirectories, toDirectory directory: AppDirectories) -> Bool {
        let originURL = buildFullPath(forFileName: name, inDirectory: inDirectory)
        let destinationURL = buildFullPath(forFileName: name, inDirectory: directory)
        // warning: constant 'success' inferred to have type '()', which may be unexpected
        // let success =
        try! FileManager.default.moveItem(at: originURL, to: destinationURL)
        return true
    }
    
    func copyFile(withName name: String, inDirectory: AppDirectories, toDirectory directory: AppDirectories) -> Bool {
        let originURL = buildFullPath(forFileName: name, inDirectory: inDirectory)
        let destinationURL = buildFullPath(forFileName: name, inDirectory: directory)
        try! FileManager.default.copyItem(at: originURL, to: destinationURL)
        return true
    }
    
    func changeFileExtension(withName name: String, inDirectory: AppDirectories, toNewExtension newExtension: String) -> Bool {
        var newFileName = NSString(string:name)
        newFileName = newFileName.deletingPathExtension as NSString
        newFileName = (newFileName.appendingPathExtension(newExtension) as NSString?)!
        let finalFileName:String =  String(newFileName)
        
        let originURL = buildFullPath(forFileName: name, inDirectory: inDirectory)
        let destinationURL = buildFullPath(forFileName: finalFileName, inDirectory: inDirectory)
        
        try! FileManager.default.moveItem(at: originURL, to: destinationURL)
        
        return true
    }
} // end extension AppFileManipulation

The adapter design pattern

  The word “adapt” is defined as “to make fit (as for a new use) often by modification.”
– https://www.merriam-webster.com/dictionary/adapts

  The word “adapter” is defined as “an attachment for adapting apparatus for uses not originally intended.”
– https://www.merriam-webster.com/dictionary/adapter
The adapter pattern is used so that an existing codebase (call it “A”) can work, without modifying the original “A” code, with other code (call it “B”) that may not be completely compatible with the existing, original codebase “A.” We can create some kind of adapter that allows “A” and “B” to work together despite their differences. Remember that the existing, original codebase “A” cannot be modified (either because it would break the code or because we don’t have the source).
Use case for adapter design pattern app
My adapter example playground, available on GitHub, showcases how we’ll use the iOS file system as a substrate on which to discuss and design an example of the adapter pattern. Let’s say we’ve got my iOS file system code from the preceding sections up above where all paths to directories and files are expressed as URL instances. Consider a scenario in which we’ve been given a huge chunk of code that also manipulates the iOS file system, but where all paths to directories and files are expressed as String path instances, and the URL-based code must be made to work with the String path-based code.
Sample code for the adapter design pattern
Let’s walk through my code. Make sure you follow along with my code in the playground hosted on GitHub. In order to concentrate solely on the adapter pattern, we’ll use slimmed-down versions of my AppDirectories enum and AppDirectoryNames protocol and protocol extension:
enum AppDirectories : String {
    case Documents = "Documents"
    case Temp = "tmp"
}

protocol AppDirectoryNames {
    func documentsDirectoryURL() -> URL
    
    func tempDirectoryURL() -> URL
}

extension AppDirectoryNames {
    func documentsDirectoryURL() -> URL {
        return FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
    }
    
    func tempDirectoryURL() -> URL {
        return FileManager.default.temporaryDirectory
    }
}

One technique we could use is to create a “dedicated” adapter, one which gives us string-based paths to directories as specified in AppDirectories and also gives us string-based paths to files stored in directories as specified in AppDirectories:
// A dedicated adapter
struct iOSFile : AppDirectoryNames {
    let fileName: URL
    var fullPathInDocuments: String {
        return documentsDirectoryURL().appendingPathComponent(fileName.absoluteString).path
    }
    var fullPathInTemporary: String {
        return tempDirectoryURL().appendingPathComponent(fileName.absoluteString).path
    }
    var documentsStringPath: String {
        return documentsDirectoryURL().path
    }
    var temporaryStringPath: String {
        return tempDirectoryURL().path
    }

    init(fileName: String) {
        self.fileName = URL(string: fileName)!
    }
}

Here’s some code that tests the iOSFile “dedicated” adapter — and note my one inline comment:
let iOSfile = iOSFile(fileName: "myFile.txt")
iOSfile.fullPathInDocuments
iOSfile.documentsStringPath

iOSfile.fullPathInTemporary
iOSfile.temporaryStringPath

// We STILL have access to URLs
// through protocol AppDirectoryNames.
iOSfile.documentsDirectoryURL()
iOSfile.tempDirectoryURL()

Here are my playground’s line-by-line annotations which appear to the right of each line of code, on the same line, representing runtime code values, corresponding to the previous code snippet — the annotations below correspond one-to-one to the lines of code above:
iOSFile
"/var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-0A71F81A-9388-41F5-ACBE-52A1A61A9B99/Documents/myFile.txt"
"/var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-0A71F81A-9388-41F5-ACBE-52A1A61A9B99/Documents"

"/Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/F08EFF4F-8C4F-4BB7-B220-980E16344F18/tmp/myFile.txt"
"/Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/F08EFF4F-8C4F-4BB7-B220-980E16344F18/tmp"

file:///var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-0A71F81A-9388-41F5-ACBE-52A1A61A9B99/Documents/
file:///Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/F08EFF4F-8C4F-4BB7-B220-980E16344F18/tmp/

The technique I prefer is to design an adapter protocol that my string path-based code could adopt so that it could use String paths instead of URL paths.
// Protocol-oriented approach
protocol AppDirectoryAndFileStringPathNamesAdpater : AppDirectoryNames {
    
    var fileName: String { get }
    var workingDirectory: AppDirectories { get }

    func documentsDirectoryStringPath() -> String
    
    func tempDirectoryStringPath() -> String
    
    func fullPath() -> String
    
} // end protocol AppDirectoryAndFileStringPathAdpaterNames

extension AppDirectoryAndFileStringPathNamesAdpater {
   
    func documentsDirectoryStringPath() -> String {
        return documentsDirectoryURL().path
    }
    
    func tempDirectoryStringPath() -> String {
        return tempDirectoryURL().path
    }
    
    func fullPath() -> String {
        switch workingDirectory {
        case .Documents:
            return documentsDirectoryStringPath() + "/" + fileName
        case .Temp:
            return tempDirectoryStringPath() + "/" + fileName
        }
    }

} // end extension AppDirectoryAndFileStringPathNamesAdpater

struct AppDirectoryAndFileStringPathNames : AppDirectoryAndFileStringPathNamesAdpater {
    
    let fileName: String
    let workingDirectory: AppDirectories
    
    init(fileName: String, workingDirectory: AppDirectories) {
        self.fileName = fileName
        self.workingDirectory = workingDirectory
    }
    
} // end struct AppDirectoryAndFileStringPathNames

Here’s some code that tests my AppDirectoryAndFileStringPathNames struct, which adopts the AppDirectoryAndFileStringPathNamesAdpater adapter protocol (which is a descendent of the AppDirectoryNames protocol) — and note my two inline comments:
let appFileDocumentsDirectoryPaths = AppDirectoryAndFileStringPathNames(fileName: "myFile.txt", workingDirectory: .Documents)
appFileDocumentsDirectoryPaths.fullPath()
appFileDocumentsDirectoryPaths.documentsDirectoryStringPath()

// We STILL have access to URLs
// through protocol AppDirectoryNames.
appFileDocumentsDirectoryPaths.documentsDirectoryURL()

let appFileTemporaryDirectoryPaths = AppDirectoryAndFileStringPathNames(fileName: "tempFile.txt", workingDirectory: .Temp)
appFileTemporaryDirectoryPaths.fullPath()
appFileTemporaryDirectoryPaths.tempDirectoryStringPath()

// We STILL have access to URLs
// through protocol AppDirectoryNames.
appFileTemporaryDirectoryPaths.tempDirectoryURL()

Here are my playground’s line-by-line annotations which appear to the right of each line of code, on the same line, representing runtime code values, corresponding to the previous code snippet — the annotations below correspond one-to-one to the lines of code above:
AppDirectoryAndFileStringPathNames
"/var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-A3DE7CC8-D60F-4448-869F-2A19556C62B2/Documents/myFile.txt"
"/var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-A3DE7CC8-D60F-4448-869F-2A19556C62B2/Documents"



file:///var/folders/5_/kd8__nv1139__dq_3nfvsmhh0000gp/T/com.apple.dt.Xcode.pg/containers/com.apple.dt.playground.stub.iOS_Simulator.Swift-Adapter-Design-Pattern-A3DE7CC8-D60F-4448-869F-2A19556C62B2/Documents/

AppDirectoryAndFileStringPathNames
"/Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/CF3D4156-E773-4BC4-B117-E7BDEFA3F34C/tmp/tempFile.txt"
"/Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/CF3D4156-E773-4BC4-B117-E7BDEFA3F34C/tmp"



file:///Users/softwaretesting/Library/Developer/XCPGDevices/52E1A81A-98AF-42DE-ADCF-E69AC8FA2791/data/Containers/Data/Application/CF3D4156-E773-4BC4-B117-E7BDEFA3F34C/tmp/

Conclusion
Not only do design patterns encourage code reuse, but can help you make your code consistent, readable, loosely coupled, and thus maintainable and extensible. When you identify recurring and generalized features in your apps, I encourage you to take your design pattern-based code and put it into frameworks so you write it once and use it many more times.
Thanks for joining me again here on AppCoda. Enjoy your work, keep on learning, and I’ll see you soon!





Design Patterns in Swift #2: Observer and Memento
Andrew Jaffee — Mon, 06 Aug 2018 00:43:39 GMT


This tutorial is the second installment in an AppCoda series on design patterns started last week. There are 23 classic software development design patterns probably first identified,  collected, and explained all in one place by the “Gang of Four” (“GoF”), Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides in their seminal book, “Design Patterns: Elements of Reusable Object-Oriented Software.”. Today, we’ll focus on two of these patterns, “observer” and “memento,” which fall into what the GoF calls the “behavioral” category.
Software development is an endeavor into modeling real world scenarios in the hopes of creating tools to enhance the human experience in such scenarios. Tools for managing finances, e.g., banking apps and shopping aids like Amazon or eBay’s iOS apps, definitely make life much simpler than it was for consumers just ten years ago. Think of how far we’ve come. While software apps have generally gotten more powerful and simpler to use for consumers, development of said apps has gotten much more complex for developers.
So developers have created an arsenal of best practices to manage complexity, like object-oriented programming, protocol-oriented programming, value semantics, local reasoning, breaking large pieces of code into smaller ones with well-defined interfaces (like with Swift extensions), syntactic sugar, to name some of the most popular. One of the most important best practices that I didn’t mention, but that merits much attention, is the use of design patterns.
Design Patterns
Design patterns are an extremely important tool with which developers can manage complexity. It’s best to conceptualize them as generally templated techniques, each tailored to solving a corresponding, recurring, and readily identifiable problem. Look at them as a list of best practices you would use for coding scenarios that you see over and over again, like how to create objects from a related family of objects without having to understand all the gory implementation details of that family. The whole point of design patterns is that they apply to commonly occurring scenarios. They’re reusable because they’re generalized. A specific example should help.
Design patterns are not specific to some use case like iterating over a Swift array of 11 integers (Int). For example, the GoF defined the iterator pattern to provide a common interface for traversing through all items in some collection without knowing the intricacies (i.e., type) of the collection. A design pattern is not programming language code. It is a set of guidelines or rule of thumb for solving a common software scenario.
Remember that I discussed the “Model-View-ViewModel” or “MVVM” design pattern here on AppCoda — and of course the very well-known “Model-View-Controller” or “MVC” design pattern, long favored by Apple and many iOS developers.
These two patterns are generally applied to entire applications. MVVM and MVC are architectural design patterns and are meant to separate the user interface (UI) from the app’s data and from code for presentation logic, and to separate the app’s data from core data processing and/or business logic. The GoF design patterns are more specific in nature, meant to solve more distinct problems inside an application’s code base. You may use three or seven or even twelve GoF design patterns in one app. Remember my iterator example. Delegation is another great example of a design pattern, though not specifically on the GoF’s list of 23.
While the GoF book has taken on biblical connotations for many developers, it is not without its detractors. We’ll talk about that in the conclusion to this article.
Design pattern categories
The GoF organized their 23 design patterns into 3 categories, “creational,” “structural,” and “behavioral.” This tutorial discusses two patterns in the behavioral category. This  pattern’s purpose is imposing safe, common sense, and consistent etiquette, form, and best practices for behaviour onto classes and structs (actors). We want good, consistent, and predictable behavior from all actors inside an entire application. We want good behavior both within actors themselves and between different actors that interact/communicate. Evaluation of actors’ behavior should be considered before and at compile time, which I sometimes call “design time,” and at runtime, when we’ll have lots of instances of classes and structs all doing their own thing and constantly interacting/communicating. Since communication between instances leads to so much software complexity, having rules for consistent, efficient, and safe communications is of paramount importance, but that concept should not in any way diminish the need for good design practices when building each individual actor. Since we’re so focused on behavior, we must remember to use consistent patterns when assigning responsibilities to actors and when assigning responsibilities to combinations of actors.
Before I wax too far theoretical, let me provide tangible examples to assure you that I’ll be demonstrating theory with in-depth practice as realized in Swift code. In this tutorial, we’ll see how to consistently assign responsibility for maintaining an actor’s state. We’ll also see how to consistently assign responsibility for one actor, the subject, to send notifications to many actor-observers, and conversely, how to consistently assign responsibility to the observers for registering with the subject to get notifications.
The whole notion of consistency should be self-evident to you when discussing design patterns. Keep in mind a theme that was highlighted in last week’s post, a theme that will occur over and over as we discuss more and more design patterns: hiding complexity (encapsulation). It is one the highest goals of smart developers. For example, object-oriented (OOP) classes can provide very complex, sophisticated, and powerful functionality without requiring the developer to know anything about the internal workings of those classes. In the same vein, Swift protocol-oriented programming is an extremely important yet relatively new technique for controlling complexity. Managing complexity is a developer’s greatest burden, but here we are talking about taming that beast!
A note on this tutorial’s prose and definitions
For this tutorial, I’ve decided to concentrate my explanatory prose as inline commentary in my sample apps’ code. While I will provide brief explanations of today’s design pattern concepts, I very much want you to look at my code, read the comments, and fully internalize the techniques I’m sharing with you. After all, if you can’t write the code, and can only talk about the code, you’re not going to make it through very many job interviews — and you’re not really a hardcore developer.
You probably noticed in my definition of the behavioral design pattern that I’m following Apple’s documentation convention:

  An instance of a class is traditionally known as an object. However, Swift structures and classes are much closer in functionality than in other languages, and much of this chapter describes functionality that applies to instances of either a class or a structure type. Because of this, the more general term instance is used.

I’ve also taken the liberty of referring to classes and structs as “actors” at design time.
The observer design pattern
The observer pattern is probably something you’ve all experienced while using Apple mobile devices, but hopefully you’ve also noticed it while coding your iOS apps. Every time it rains where I live, I and a whole lot of other people around here get push notifications which pop up on our iPhones — lock screen or normal screen — whenever it rains. Here’s what they look like:

One source, Apple, is sending out — broadcasting — notifications to many thousands of iPhones, on behalf of the National Weather Service, warning people in my area of the possibility of flooding. In more concrete terms, like at the level of an iOS app, one instance, the subject, notifies (many) other instances, the observers, of changes to the state of the subject. The instances participating in this broadcast type communication don’t need to know about one another. This is a great example of loose coupling.
The subject instance, usually a single critical resource, broadcasts notifications about a change in its state to many observer instances that depend on that resource. Interested observers must subscribe to get notifications.
Thankfully, iOS has a built-in and well-known feature for enabling the observer pattern: NotificationCenter, which I’ll let you study up on yourself here.
Use case for observer design pattern app
My observer example project, available on GitHub, showcases how this broadcast type communication works.
I know this is not quite how the iOS Human Interface Guidelines advise you to do things, but bear with me as I needed an example of a single critical resource. Suppose we were to take a proactive approach and have a single instance of a subject responsible for monitoring network connectivity/reachability. This is the broadcaster, and to implement one, you just need to have an actor adopt my ObservedProtocol.
Suppose there are multiple instances of observers, like an image downloader class, a login instance that verifies user credentials via a REST API, and an in-app browser that all subscribe to the subject to get notified of network connection status. To implement these, you could take pretty much any class and make it a descendent of my “abstract” Observer class, which adopts the ObserverProtocol. (I’ll explain later why I limited my example observer code to a class.)
To implement observers for the purposes of my example app, I created the NetworkConnectionHandler class. When instances of this concrete class get notifications of NetworkConnectionStatus.connected, they turn a UIView instance green; when they   get notifications of NetworkConnectionStatus.disconnected, they turn a UIView instance red.
Here’s my sample app code compiled, installed, and running on an iPhone 8 Plus:

Here’s the Xcode console output corresponding to the previous video:

Sample code for observer design pattern app
To see the heavily commented code I just described in the previous section, please look at file Observable.swift in my sample project:
import Foundation

import UIKit

// Make notification names consistent and avoid stringly-typing.
// Try to use constants instead of strings or numbers.
extension Notification.Name {
    
    static let networkConnection = Notification.Name("networkConnection")
    static let batteryStatus = Notification.Name("batteryStatus")
    static let locationChange = Notification.Name("locationChange")

}

// Various network connection states -- made consistent.
enum NetworkConnectionStatus: String {
    
    case connected
    case disconnected
    case connecting
    case disconnecting
    case error
    
}

// The key to the notification's "userInfo" dictionary.
enum StatusKey: String {
    case networkStatusKey
}

// This protocol forms the basic design for OBSERVERS,
// entities whose operation CRTICIALLY depends
// on the status of some other, usually single, entity.
// Adopters of this protocol SUBSCRIBE to and RECEIVE
// notifications about that critical entity/resource.
protocol ObserverProtocol {
    
    var statusValue: String { get set }
    var statusKey: String { get }
    var notificationOfInterest: Notification.Name { get }
    func subscribe()
    func unsubscribe()
    func handleNotification()
    
}

// This template class abstracts out all the details
// necessary for an entity to SUBSCRIBE to and RECEIVE
// notifications about a critical entity/resource.
// It provides a "hook" (handleNotification()) in which
// subclasses of this base class can pretty much do whatever
// they need to do when specific notifications are received.
// This is basically an "abstract" class, not detectable
// at compile time, but I felt this was an exceptional case.
class Observer: ObserverProtocol {
    
    // This specific state reported by "notificationOfInterest."
    // I use String for maximum portability. Yeah, yeah...
    // stringly-typed...
    var statusValue: String
    // The key to the notification's "userInfo" dictionary, with
    // which we can read the specific state and store in "statusValue."
    // I use String for maximum portability. Yeah, yeah...
    // stringly-typed...
    let statusKey: String
    // The name of the notification this class has registered
    // to receive whenever messages are broadcast.
    let notificationOfInterest: Notification.Name
    
    // Initializer which registers/subscribes/listens for a specific
    // notification and then watches for a specific state as reported
    // by notifications when received.
    init(statusKey: StatusKey, notification: Notification.Name) {
        
        self.statusValue = "N/A"
        self.statusKey = statusKey.rawValue
        self.notificationOfInterest = notification
        
        subscribe()
    }
    
    // We're registering self (this) with NotificationCenter to receive
    // all notifications with the name stored in "notificationOfInterest."
    // Whenever one of those notifications is received, the
    // "receiveNotification(_:)" method is called.
    func subscribe() {
        NotificationCenter.default.addObserver(self, selector: #selector(receiveNotification(_:)), name: notificationOfInterest, object: nil)
    }
    
    // It's a good idea to un-register from notifications when we no
    // longer need to listen, but this is more of a historic curiosity
    // as, since iOS 9.0, the OS does some type of cleanup.
    func unsubscribe() {
        NotificationCenter.default.removeObserver(self, name: notificationOfInterest, object: nil)
    }
    
    // Called whenever a message labelled "notificationOfInterest"
    // is received. This is our chance to do something when the
    // state of that critical resource we're observing changes.
    // This method "must have one and only one argument (an instance
    // of NSNotification)."
    @objc func receiveNotification(_ notification: Notification) {
        
        if let userInfo = notification.userInfo, let status = userInfo[statusKey] as? String {
            
            statusValue = status
            handleNotification()
            
            print("Notification \(notification.name) received; status: \(status)")
            
        }
        
    } // end func receiveNotification
    
    // YOU MUST OVERRIDE THIS METHOD; YOU MUST SUBCLASS THIS CLASS.
    // I've MacGyvered this class into being "abstract" so you
    // can subclass and specialize as much as you want and not
    // have to worry about NotificationCenter details.
    func handleNotification() {
        fatalError("ERROR: You must override the [handleNotification] method.")
    }
    
    // Be kind and stop tapping a resource (NotificationCenter)
    // when we don't need to anymore.
    deinit {
        print("Observer unsubscribing from notifications.")
        unsubscribe()
    }
    
} // end class Observer

// An example of an observer, usually one of several
// (many?) that are all listening for notifications
// from some usually single critical resource. Notice that
// it's brief and can serve as a model for creating
// handlers for all sorts of notifications.
class NetworkConnectionHandler: Observer {
    
    var view: UIView
    
    // As long as you call "super.init" with valid
    // NotificationCenter-compatible values, you can
    // create whatever type of initializer you want.
    init(view: UIView) {
        
        self.view = view
        
        super.init(statusKey: .networkStatusKey, notification: .networkConnection)
    }
    
    // YOU MUST OVERRIDE THIS METHOD, but that
    // gives you the chance to handle notifications
    // in whatever way you deem fit.
    override func handleNotification() {
        
        if statusValue == NetworkConnectionStatus.connected.rawValue {
            view.backgroundColor = UIColor.green
        }
        else {
            view.backgroundColor = UIColor.red
        }
        
    } // end func handleNotification()
    
} // end class NetworkConnectionHandler

// An template for a subject, usually a single
// critical resource, that broadcasts notifications
// about a change in its state to many
// subscribers that depend on that resource.
protocol ObservedProtocol {
    var statusKey: StatusKey { get }
    var notification: Notification.Name { get }
    func notifyObservers(about changeTo: String) -> Void
}

// When an adopter of this ObservedProtocol
// changes status, it notifies ALL subsribed
// observers. It BROADCASTS to ALL SUBSCRIBERS.
extension ObservedProtocol {

    func notifyObservers(about changeTo: String) -> Void {
       NotificationCenter.default.post(name: notification, object: self, userInfo: [statusKey.rawValue : changeTo])
    }
    
} // end extension ObservedProtocol

I had intended to put most of the observer’s notification handling logic into an extension of ObserverProtocol but ran into @objc when setting my #selector, then thought about using the block-based version of  addObserver(forName:object:queue:using:), then passing in a notification handler closure, blah, blah, blah… I decided that my notification handling code would be much more intelligible and educational as an abstract class.
I also realize that Swift has no formal concept of an abstract class, but you probably already know there is a commonly used workaround for creating one. So, again, to simplify my didactic goal of explaining the observer pattern, I made the Observer class “abstract” by forcing you to override its handleNotification() method. By doing so, I gave you the opportunity to inject any type of specialized logic you want to have executed whenever your Observer subclass instance receives a notification.
Shown immediately below is my sample project’s ViewController.swift file, which shows you how to make use of my core logic in Observable.swift, which we just discussed and reviewed:
import UIKit

// By adopting the ObservedProtocol, this view controller
// gains the capability for broadcasting notifications via
// NotificationCenter to ANY entities throughout this
// WHOLE APP whom are interested in receiving those notifications.
// Notice how little this class needs to do to gain
// notification capability?
class ViewController: UIViewController, ObservedProtocol {
    
    @IBOutlet weak var topBox: UIView!
    @IBOutlet weak var middleBox: UIView!
    @IBOutlet weak var bottomBox: UIView!
    
    // Mock up three entities whom are dependent upon a
    // critical resource: network connectivity. They need
    // to observe the status of the critical resource.
    var networkConnectionHandler0: NetworkConnectionHandler?
    var networkConnectionHandler1: NetworkConnectionHandler?
    var networkConnectionHandler2: NetworkConnectionHandler?
    
    // ObservedProtocol conformance -- two properties.
    let statusKey: StatusKey = StatusKey.networkStatusKey
    let notification: Notification.Name = .networkConnection
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        
        // Here are three entities now listening for notifications
        // from the enclosing ViewController class.
        networkConnectionHandler0 = NetworkConnectionHandler(view: topBox)
        networkConnectionHandler1 = NetworkConnectionHandler(view: middleBox)
        networkConnectionHandler2 = NetworkConnectionHandler(view: bottomBox)
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }
    
    // Mock up a critical resource whose state can change.
    // I'm pretending that this ViewController is
    // responsible for network reachability/connectivity.
    // When we have a network connection, all interested
    // listeners are informed. When network access is lost,
    // all interested listeners are informed.
    @IBAction func switchChanged(_ sender: Any) {
        
        let swtich:UISwitch = sender as! UISwitch
        
        if swtich.isOn {
            notifyObservers(about: NetworkConnectionStatus.connected.rawValue)
        }
        else {
            notifyObservers(about: NetworkConnectionStatus.disconnected.rawValue)
        }
        
    } // end func switchChanged
    
} // end class ViewController

The memento design pattern
Most iOS developers are familiar with the memento pattern. Think of iOS facilities for archives and serialization which allow you to “Convert objects and values to and from property list, JSON, and other flat binary representations.” Think of the iOS state preservation and restoration feature, which remembers and then returns “your app to its previous state after it is terminated by the system.”
The memento design pattern is meant to capture, represent, and store the internal state of an instance at a specific point in time and then allow you to find that instance’s state representation at a later time and restore it. When you restore the state of an instance, it should exactly reflect it’s state at the time of capture. While this may sound obvious, you should ensure that all instance property access levels should be respected during capture and restoration, e.g., public data should be restored to public properties and private data should be restored to private properties.
To keep things simple, I used iOS’s UserDefaults as the core of my instance state storage and recovery process.
Use case for memento design pattern app
While I understand that iOS already has facilities for archiving and serialization, I developed sample code that can save and recover an class’s state. My code does a pretty good job of abstracting archiving and de-archiving so that you can store and recover the state of a variety of different instances with varying properties. But my example is not meant for production use. It is a didactic example formulated to explain the memento pattern.
My memento example project, available on GitHub, showcases how a User class instance’s state, with firstName, lastName, and age properties, can be persisted to  UserDefaults and then later recovered. At first, no User instance is available to recover, but then I enter one, archive it, and then recover it, as shown here:

Here’s the console output corresponding to the previous video:
Empty entity.

lastName: Adams
age: 87
firstName: John

lastName: Adams
age: 87
firstName: John

Sample code for memento design pattern app
My memento code is straightforward. It provides the Memento protocol and protocol extension for handling and abstracting all the details of gross archiving and de-archiving of the member properties of classes that adopt the Memento protocol. The extension also allows you to print the entire state of an instance to console at any given point in time. I used a Dictionary to store an adopting class’s property names as keys and property contents as values. I stored values as String to keep my implementation simple and easily understood, fully well acknowledging that there are many use cases which would require you to archive and de-archive much more complex property types. This is a tutorial about design patterns, not a code base for a production app.
Notice that I added persist() and recover() methods to the Memento protocol, which must be implemented by any class that adopts the Memento protocol. These methods provide developers with the opportunity to archive and de-archive Memento protocol-adopting class’s specific properties, by name. In other words, the elements of the state property of type Dictionary can be matched one-to-one with the Memento protocol-adopting class’s properties. Each property name corresponds to a dictionary element key and each property value corresponds to the dictionary element’s value which matches said key. Just look at the code and you’ll understand.
Since the persist() and recover() methods must be implemented by any class that adopts the Memento protocol, properties of all access levels, e.g., public, private, and fileprivate are visible to, and accessible by, these methods.
You may wonder why I made the Memento protocol class-only. I did so because of that horrible Swift compiler message, “Cannot use mutating member on immutable value: ‘self’ is immutable.” Discussing it is way beyond the scope of this tutorial, but if you’d like to torture yourself, read a great description of the issue here.
Here’s my core logic for implementing the memento design pattern, found in file Memento.swift of my sample app:
import Foundation

// I've only limited this protocol to reference types because of the
// "Cannot use mutating member on immutable value: ‘self’ is immutable"
// conundrum.
protocol Memento : class {
    
    // Key for accessing the "state" property
    // from UserDefaults.
    var stateName: String { get }
    
    // Current state of adopting class -- all
    // property names (keys) and property values.
    var state: Dictionary { get set }
    
    // Save "state" property with key as specified
    // in "stateName" into UserDefaults ("generic" save).
    func save()
    
    // Retrieve "state" property using key as specified
    // in "stateName" from UserDefaults ("generic" restore).
    func restore()
    
    // Customized, "specific" save of "state" dictionary with
    // keys corresponding to member properties of adopting
    // class, and save of each property value (class-specific).
    func persist()
    
    // Customized, "specific" retrieval of "state" dictionary using
    // keys corresponding to member properties of adopting
    // class, and retrieval of each property value  (class-specific).
    func recover()
    
    // Print all adopting class's member properties by
    // traversing "state" dictionary, so output is of
    // format:
    //
    // Property 1 name (key): property 1 value
    // Property 2 name (key): property 2 value ...
    func show()
    
} // end protocol Memento

extension Memento {
    
    // Save state into dictionary archived on disk.
    func save() {
        UserDefaults.standard.set(state, forKey: stateName)
    }
    
    // Read state into dictionary archived on disk.
    func restore() {
        
        if let dictionary = UserDefaults.standard.object(forKey: stateName) as! Dictionary? {
            state = dictionary
        }
        else {
            state.removeAll()
        }
        
    } // end func restore()
    
    // Storing state in dictionary makes display
    // of object state so easy and intuitive.
    func show() {
        
        var line = ""
        
        if state.count > 0 {
            
            for (key, value) in state {
                line += key + ": " + value + "\n"
            }
            
            print(line)
            
        }
        
        else {
            print("Empty entity.\n")
        }
            
    } // end func show()
    
} // end extension Memento

// By adopting the Memento protocol, we can, with relative
// ease, save the state of an entire class to persistant
// storage and then retrieve that state at a later time, i.e.,
// across different instances of this app running.
class User: Memento {
    
    // These two properties are required by Memento.
    let stateName: String
    var state: Dictionary
    
    // These properties are specific to a class that
    // represents some kind of system user account.
    var firstName: String
    var lastName: String
    var age: String
    
    // Initializer for persisting a new user to disk, or for
    // updating an existing user. The key value used for accessing
    // persistent storage is property "stateName."
    init(firstName: String, lastName: String, age: String, stateName: String) {
        
        self.firstName = firstName
        self.lastName = lastName
        self.age = age
        
        self.stateName = stateName
        self.state = Dictionary()
        
        persist()
        
    } // end init(firstName...
    
    // Initializer for retrieving a user from disk, if one
    // exists. The key value used for retrieving state from
    // persistent storage is property "stateName."
    init(stateName: String) {
        
        self.stateName = stateName
        self.state = Dictionary()
        
        self.firstName = ""
        self.lastName = ""
        self.age = ""
        
        recover()
        
    } // end init(stateName...

    // Save the user's properties to persistent storage.
    // We intuitively save each property value by making
    // the keys in the dictionary correspond one-to-one with
    // this class's property names.
    func persist() {
        
        state["firstName"] = firstName
        state["lastName"] = lastName
        state["age"] = age
        
        save() // leverage protocol extension
        
    } // end func persist()
    
    // Read existing user's properties from persistent storage.
    // After retrieving the "state" dictionary from UserDefaults,
    // we easily restore each property value because
    // the keys in the dictionary correspond one-to-one with
    // this class's property names.
    func recover() {
        
        restore() // leverage protocol extension
            
        if state.count > 0 {
            firstName = state["firstName"]!
            lastName = state["lastName"]!
            age = state["age"]!
        }
        else {
            self.firstName = ""
            self.lastName = ""
            self.age = ""
        }
        
    } // end func recover
    
} // end class User

Here’s the code for implementing the memento design pattern use case I described earlier (archiving and de-archiving an instance of class User), as found in my sample app as file ViewController.swift:
import UIKit

class ViewController: UIViewController {
    
    @IBOutlet weak var firstNameTextField: UITextField!
    @IBOutlet weak var lastNameTextField: UITextField!
    @IBOutlet weak var ageTextField: UITextField!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }

    // Called when "Save User" button is tapped. Stores
    // "User" class instance properties to UserDefaults
    // based on stateName property value of "userKey" (but
    // use whatever lights your fire).
    @IBAction func saveUserTapped(_ sender: Any) {
        
        if firstNameTextField.text != "" &&
            lastNameTextField.text != "" &&
            ageTextField.text != "" {
            
            let user = User(firstName: firstNameTextField.text!,
                            lastName: lastNameTextField.text!,
                            age: ageTextField.text!,
                            stateName: "userKey")
            user.show()
            
        }
        
    } // end func saveUserTapped
    
    // Called when "Restore User" button is tapped. Retrieves
    // "User" class instance properties from UserDefaults
    // based on stateName property value of "userKey," if
    // a key/value pair with key "userKey" exists.
    @IBAction func restoreUserTapped(_ sender: Any) {
        
        let user = User(stateName: "userKey")
        firstNameTextField.text = user.firstName
        lastNameTextField.text = user.lastName
        ageTextField.text = user.age
        user.show()

    }
    
} // end class ViewController

Conclusion
Some critics have claimed that use of design patterns is proof of deficiencies in programming languages and that seeing recurring patterns in code is a bad thing. I disagree. Expecting a language to have a feature for everything is silly and would most likely lead to enormous languages like C++ into becoming even larger and more complex and thus harder to learn, use, and maintain. Recognizing and solving recurring problems is a positive human trait worthy of positive reinforcement. Design patterns are successful examples of learning from history, something humankind has failed to do too many times. Coming up with abstract and standardized solutions to common problems makes those solutions portable and more likely to be distributed.
A combination of a compact language like Swift and an arsenal of best practices, like design patterns, is an ideal and happy medium. Consistent code is generally readable and maintainable code. Remember too that design patterns are ever-evolving as millions of developers are constantly discussing and sharing ideas. By virtue of being linked together over the World Wide Web, this developer discussion has lead to constantly self-regulating collective intelligence.





Design Patterns in Swift #1: Factory Method and Singleton
Andrew Jaffee — Tue, 24 Jul 2018 17:56:44 GMT


There are 23 classic software development design patterns probably first identified,  collected, and explained all in one place by the “Gang of Four” (“GoF”), Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides in their seminal book, “Design Patterns: Elements of Reusable Object-Oriented Software.” This tutorial focuses on two of those patterns in terms of what the GoF calls the “creational” category: factory method and singleton.
Software development is an endeavor into modeling real world scenarios in the hopes of creating tools to enhance the human experience in such scenarios. Tools for managing finances, e.g., banking apps and shopping aids like Amazon or eBay’s iOS apps, definitely make life much simpler than it was for consumers just ten years ago. Think of how far we’ve come. While software apps have generally gotten more powerful and simpler to use for consumers, development of said apps has gotten much more complex for developers.
So developers have created an arsenal of best practices to manage complexity, like object-oriented programming, protocol-oriented programming, value semantics, local reasoning, breaking large pieces of code into smaller ones with well-defined interfaces (like with Swift extensions), syntactic sugar, to name some of the most popular. One of the most important best practices that I didn’t mention, but that merits much attention, is the use of design patterns.
Design Patterns
Design patterns are an extremely important tool with which developers can manage complexity. It’s best to conceptualize them as generally templated techniques, each tailored to solving a corresponding, recurring, and readily identifiable problem. Look at them as a list of best practices you would use for coding scenarios that you see over and over again, like how to create objects from a related family of objects without having to understand all the gory implementation details of that family. The whole point of design patterns is that they apply to commonly occurring scenarios. They’re reusable because they’re generalized. A specific example should help.
Design patterns are not specific to some use case like iterating over a Swift array of 11 integers (Int). For example, the GoF defined the Iterator pattern to provide a common interface for traversing through all items in some collection without knowing the intricacies (i.e., type) of the collection. A design pattern is not programming language code. It is a set of guidelines or rule of thumb for solving a common software scenario.
Remember that I discussed the “Model-View-ViewModel” or “MVVM” design pattern here on AppCoda — and of course the very well-known “Model-View-Controller” or “MVC” design pattern, long favored by Apple and many iOS developers.
These two patterns are generally applied to entire applications. MVVM and MVC are architectural design patterns and are meant to separate the user interface (UI) from the app’s data and from code for presentation logic, and to separate the app’s data from core data processing and/or business logic. The GoF design patterns are more specific in nature, meant to solve more specific problems inside an application’s code base. You may use three or seven or even twelve GoF design patterns in one app. Remember my Iterator example. Delegation is another great example of a design pattern, though not specifically on the GoF’s list of 23.
While the GoF book has taken on biblical connotations for many developers, it is not without its detractors. We’ll talk about that in the conclusion to this article.
Design pattern categories
The GoF organized their 23 design patterns into 3 categories, “creational,” “structural,” and “behavioral.” This tutorial discusses two patterns in the creational category. This  pattern’s purpose is to make the creation of (often complex) objects straightforward (easy), understandable, and maintainable for developers, hiding details like instantiation and class implementation.
Hiding complexity (encapsulation) is one the highest goals of smart developers. For example, object-oriented (OOP) classes can provide very complex, sophisticated, and powerful functionality without requiring the developer to know anything about the internal workings of those classes. In the creational pattern, a developer may not even have to know about a class’s key properties and methods, but if necessary, she/he can take a peek at the interface — protocol in Swift — to the class(es) of interest and just plug and play. You’ll see what I mean in our first example of a “factory method” design pattern.
The factory method design pattern
If you’ve delved into the GoF design patterns and/or spent a lot of time in the world of OOP, you’ve probably at least heard of the “abstract factory,” “factory,” or “factory method” pattern. While we could quibble over “exact” nomenclature, the example I’m going to show you here most closely fits the “factory method” pattern.
In this paradigm, you can create very useful objects without directly calling class constructors and without knowing anything about the class(es) or class hierarchy that your factory method is instantiating. You get a lot of bang for cheap. You get functionality and UI (if applicable) with a minimal amount of code. So my factory method example project, available on GitHub, showcases how objects from a nontrivial class hierarchy can be used easily by, say, a team’s UI developer:

Most successful apps have a consistent look — a theme — that is pleasing and becomes associated with the app and/or app developer. We’ll assume that all shapes used in our hypothetical app will be the same color and same size so as to stay in tune with the app’s theme — it’s branding. These shapes could be useful through an app as custom buttons, or maybe just part of background imagery during the onboarding process.
Let’s assume that the design team has agreed that my app theming code has been selected to be used as app background imagery. We’ll go through my code, starting with the protocol, class hierarchy, and factory methods that our hypothetical UI developer shouldn’t have to worry about.
See file ShapeFactory.swift. Here’s a protocol for drawing shapes inside preexisting view controllers. Since it could be used for a variety of purposes, it’s access level is public:
// these values have been pre-selected by
// the graphics and design teams
let defaultHeight = 200
let defaultColor = UIColor.blue

protocol HelperViewFactoryProtocol {
    
    func configure()
    func position()
    func display()
    var height: Int { get }
    var view: UIView { get }
    var parentView: UIView { get }
    
}

Remember that the UIView class has a rectangular frame by default, so it was simplest for me to make Square my base shape class:
fileprivate class Square: HelperViewFactoryProtocol {
    
    let height: Int
    let parentView: UIView
    var view: UIView
    
    init(height: Int = defaultHeight, parentView: UIView) {
        
        self.height = height
        self.parentView = parentView
        view = UIView()
        
    }
    
    func configure() {
        
        let frame = CGRect(x: 0, y: 0, width: height, height: height)
        view.frame = frame
        view.backgroundColor = defaultColor
        
    }
    
    func position() {
        
        view.center = parentView.center
        
    }

    func display() {
        
        configure()
        position()
        parentView.addSubview(view)
        
    }
    
} // end class Square

Notice that I’m taking advantage of OOP to reuse my code and thus make my shape hierarchy simple and maintainable. Classes Circle and Rectangle are just specializations of Square (and remember how easy it is to draw a circle by starting with a perfect square):
fileprivate class Circle : Square {
    
    override func configure() {
        
        super.configure()
        
        view.layer.cornerRadius = view.frame.width / 2
        view.layer.masksToBounds = true
        
    }
    
} // end class Circle

fileprivate class Rectangle : Square {
    
    override func configure() {
        
        let frame = CGRect(x: 0, y: 0, width: height + height/2, height: height)
        view.frame = frame
        view.backgroundColor = UIColor.blue
        
    }
    
} // end class Rectangle

I’ve used fileprivate to emphasize one of the purposes behind the factory method pattern: hiding complexity. You should also see how the shape class hierarchy could be easily modified or extended without changing the factory methods below. Here’s the code for the factory methods that makes object creation so abstract and simple:
enum Shapes {
    
    case square
    case circle
    case rectangle
    
}

class ShapeFactory {
    
    let parentView: UIView
    
    init(parentView: UIView) {
        
        self.parentView = parentView
        
    }
    
    func create(as shape: Shapes) -> HelperViewFactoryProtocol {
        
        switch shape {
            
        case .square:
            
            let square = Square(parentView: parentView)
            return square
            
        case .circle:
            
            let circle = Circle(parentView: parentView)
            return circle
            
        case .rectangle:
            
            let rectangle = Rectangle(parentView: parentView)
            return rectangle
            
        }
        
    } // end func display
    
} // end class ShapeFactory

// Public factory method to display shapes.
func createShape(_ shape: Shapes, on view: UIView) {
    
    let shapeFactory = ShapeFactory(parentView: view)
    shapeFactory.create(as: shape).display()
    
}

// Alternative public factory method to display shapes.
// Technically, the factory method should return one of
// a number of related classes.
func getShape(_ shape: Shapes, on view: UIView) -> HelperViewFactoryProtocol {
    
    let shapeFactory = ShapeFactory(parentView: view)
    return shapeFactory.create(as: shape)
    
}

Notice that I’ve developed a class factory and two factory methods to give you some food for thought. Technically, a factory method should return one of a number of related classes, all with common base class and/or a common protocol. Since the purpose here was to draw a shape in a view, I personally prefer the createShape(_:view:) method. Sometimes it’s a good idea to provide alternatives — or just to experiment and explore new possibilities.
Finally, I show the use of two factory methods to draw shapes. The UI developer doesn’t have to know anything about how the shape classes are encoded. He/she especially doesn’t have to worry about how shape classes are initialized. The code in file ViewController.swift is easily readable:
import UIKit

class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }

    @IBAction func drawCircle(_ sender: Any) {
        
        // just draw the shape
        createShape(.circle, on: view)
        
    }
    
    @IBAction func drawSquare(_ sender: Any) {

        // just draw the shape
        createShape(.square, on: view)
        
    }
    
    @IBAction func drawRectangle(_ sender: Any) {

        // actually get an object from the factory
        // and use it to draw the shape
        let rectangle = getShape(.rectangle, on: view)
        rectangle.display()
        
    }
    
} // end class ViewController

The singleton design pattern
Most iOS developers are familiar with the singleton pattern. Think of the UNUserNotificationCenter.current(), UIApplication.shared, or FileManager.default singletons that you have to use if you want to send notifications, or open a URL in Safari, or manipulate iOS files, respectively. Singletons can be good for protecting shared resources, providing access to some system which contains one and only one instance of an object, supporting one object which performs some type of app-wide coordination, and, as we’ll see here, can be good for providing a value-added wrapper of a built-in iOS singleton.
To act as a singleton, we make sure that a class:

declares and initializes a static and constant property of itself, and calls that property shared to convey the fact that an instance of the class is a singleton (public by default);

declares a private property of some resource we want to control/protect but also share via shared; and,


declares a private initializer so that only our singleton class can initialize itself, and inside this init, we initialize the resource we want to control but also share.


By making the class’s initializer private and defining the shared static constant, we’ve ensured that there can only be one instance of the class, the class can only initialize itself once, and the class’s shared instance is accessible throughout our app code. We’ve created a… singleton!
My singleton example project, available on GitHub, showcases how a development team can store user preferences safely, consistently, and with very few errors. Here’s my sample app remembering whether the user prefers to see their password as unencrypted plain text or as masked, which is not the greatest idea in retrospect, but I needed an example to show you that my code works. This code is solely for educational purposes. I advise you never to leave a password exposed. Here’s how the user can set her/his password preference — and that preference is saved in UserDefaults:

When the user closes and eventually comes back to the app, note that her/his password preference is remembered:

Let me show you an excerpt of the code in file PreferencesSingleton.swift, with inline commentary, and you’ll see exactly what I mean:
class UserPreferences {

    // Create a static, constant instance of
    // the enclosing class (itself) and initialize.
    static let shared = UserPreferences()
    
    // This is the private, shared resource we're protecting.
    private let userPreferences: UserDefaults
    
    // A private initializer can only be called by
    // this class itself.
    private init() {
        
        // Get the iOS shared singleton. We're
        // wrapping it here.
        userPreferences = UserDefaults.standard
        
    }

} // end class UserPreferences

There’s no need to worry about impact on, say, app startup as initializers of static properties and global variables are run lazily, as I understand Swift.
You may ask, “Why has he created a singleton wrapper of another singleton, UserDefaults?” First, my main purpose herein was to show you a best practice for creating and using a singleton in Swift, and user preferences is the type of resource that should have a single point of entry. So UserDefaults served a very obvious didactic example. But secondly, think about how many times you’ve seen UserDefaults used (abused) almost flippantly through an app’s code base.
I’ve seen apps where UserDefaults (or NSUserDefaults in the “old” days) were spread all over project code without any rhyme or reason. Every single reference to a key in user preferences was spelling out by hand. I just found a bug in my own code where I had misspelled the word “switch” as “swithc,” and because I had copied and pasted, I had ended up with quite a few instances of “swithc” before I caught the problem. What if other team member(s) on that app started or continued to used “switch” as a key in saving the corresponding value? The app could’ve ended up with two or more states being preserved for what should’ve been one state. UserDefaults uses strings as the keys to the values we wish to maintain as part of app state, which is fine because it’s best to describe something — values — with meaningful, easily identified, and easily remembered words. But strings are not without risk.
Many of you have probably read about what has become known as “stringly-typed” code, as in my discussion about “swithc” vs. “switch.” While strings are very descriptive — a good thing — the use of raw strings as unique identifiers all over a code base is likely to lead to subtle yet eventually catastrophic errors because of misspellings. The Swift compiler doesn’t prevent us from making stringly-typed mistakes.
The solution to stringly-typed errors is making use of string constants in the form of the Swift enum. Not only can we standardize our use of strings, but we can organize them by breaking them into categories. Again, see PreferencesSingleton.swift:
...
class UserPreferences {
    
    enum Preferences {
        
        enum UserCredentials: String {
            case passwordVisibile
            case password
            case username
        }
        
        enum AppState: String {
            case appFirstRun
            case dateLastRun
            case currentVersion
        }

    } // end enum Preferences
...

I’m starting to wander from the definition of the singleton design pattern, but I do want to briefly show you and explain why I myself use a singleton wrapper for UserDefaults in most of my production apps. There are many value-added features that can make a UserDefaults singleton wrapper very convenient and enhance the reliability of code. Providing error checking when getting and setting preferences immediately comes to mind. Another feature I like to add is providing convenience methods for commonly used user preferences, like for how to handle passwords. You’ll see below as you read my code. Here’s everything in my PreferencesSingleton.swift file:
import Foundation

class UserPreferences {
    
    enum Preferences {
        
        enum UserCredentials: String {
            case passwordVisibile
            case password
            case username
        }
        
        enum AppState: String {
            case appFirstRun
            case dateLastRun
            case currentVersion
        }

    } // end enum Preferences
    
    // Create a static, constant instance of
    // the enclosing class (itself) and initialize.
    static let shared = UserPreferences()
    
    // This is the private, shared resource we're protecting.
    private let userPreferences: UserDefaults
    
    // A private initializer can only be called by
    // this class itself.
    private init() {
        
        // Get the iOS shared singleton. We're
        // wrapping it here.
        userPreferences = UserDefaults.standard

    }
    
    func setBooleanForKey(_ boolean:Bool, key:String) {
        
        if key != "" {
            userPreferences.set(boolean, forKey: key)
        }
        
    }
    
    func getBooleanForKey(_ key:String) -> Bool {
        
        if let isBooleanValue = userPreferences.value(forKey: key) as! Bool? {
            print("Key \(key) is \(isBooleanValue)")
            return true
        }
        else {
            print("Key \(key) is false")
            return false
        }
        
    }
    
    func isPasswordVisible() -> Bool {
        
        let isVisible = userPreferences.bool(forKey: Preferences.UserCredentials.passwordVisibile.rawValue)
        
        if isVisible {
            return true
        }
        else {
            return false
        }
        
    }

    func setPasswordVisibity(_ visible: Bool) {
        
        userPreferences.set(visible, forKey: Preferences.UserCredentials.passwordVisibile.rawValue)
        
    }

} // end class UserPreferences

If you look at my ViewController.swift file, you’ll see how easy it is to access and make use of a well-constructed singleton:
import UIKit

class ViewController: UIViewController {
    
    @IBOutlet weak var passwordTextField: UITextField!
    @IBOutlet weak var passwordVisibleSwitch: UISwitch!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        
        if UserPreferences.shared.isPasswordVisible() {
            passwordVisibleSwitch.isOn = true
            passwordTextField.isSecureTextEntry = false
        }
        else {
            passwordVisibleSwitch.isOn = false
            passwordTextField.isSecureTextEntry = true
        }
        
    } // end func viewDidLoad

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }
    
    @IBAction func passwordVisibleSwitched(_ sender: Any) {
        
        let pwdSwitch:UISwitch = sender as! UISwitch
        
        if pwdSwitch.isOn {
            passwordTextField.isSecureTextEntry = false
            UserPreferences.shared.setPasswordVisibity(true)
        }
        else {
            passwordTextField.isSecureTextEntry = true
            UserPreferences.shared.setPasswordVisibity(false)
        }
        
    } // end func passwordVisibleSwitched
    
} // end class ViewController

Conclusion
Some critics have claimed that use of design patterns is proof of deficiencies in programming languages and that seeing recurring patterns in code is a bad thing. I disagree. Expecting a language to have a feature for everything is silly and would most likely lead to enormous languages like C++ into becoming even larger and more complex and thus harder to learn, use, and maintain. Recognizing and solving recurring problems is a positive human trait worthy of positive reinforcement. Design patterns are successful examples of learning from history, something humankind has failed to do too many times. Coming up with abstract and standardized solutions to common problems makes those solutions portable and more likely to be distributed.
A combination of a compact language like Swift and an arsenal of best practices, like design patterns, is an ideal and happy medium. Consistent code is generally readable and maintainable code. Remember too that design patterns are ever-evolving as millions of developers are constantly discussing and sharing ideas. By virtue of being linked together over the World Wide Web, this developer discussion has lead to constantly self-regulating collective intelligence.