Helge Heß

@Model for CoreData

Thu, 28 Sep 2023 00:00:00 +0200

At WWDC 2023 Apple finally released a persistence framework specifically for Swift: SwiftData. My ManagedModels provides a similar API, on top of regular CoreData, and doesn’t require iOS 17+.

Article Sections:

A little bit of History
SwiftData
ManagedModels
- Differences to SwiftData
Example App
Internals
Closing Notes

TL;DR

ManagedModels is a package that provides a Swift 5.9 macro similar to the SwiftData @Model. It can generate CoreData ManagedObjectModel’s declaratively from Swift classes, w/o having to use the Xcode “CoreData Modeler”.
Unlike SwiftData it doesn’t require iOS 17+ and works directly w/ CoreData. It is not a direct API replacement, but a look-a-like.

Example model class:

@Model
class ToDo: NSManagedObject {
    var title: String
    var isDone: Bool
    var attachments: [ Attachment ]
}

setting up a store in SwiftUI:

ContentView()
    .modelContainer(for: ToDo.self)

Performing a query:

struct ToDoListView: View {
    @FetchRequest(sort: \.isDone)
    private var toDos: FetchedResults<ToDo>

    var body: some View {
        ForEach(toDos) { todo in
            Text("\(todo.title)")
                .foregroundColor(todo.isDone ? .green : .red)
        }
    }
}

Swift package: https://github.com/Data-swift/ManagedModels.git
Example ToDo list app: https://github.com/Data-swift/ManagedToDosApp.git
Northwind database using ManagedModels (more complex example): Northwind for ManagedModels

TL;DR ✔︎

A Little Bit of History

Prior iOS 17 / macOS 14 the recommended Apple way to do persistence is CoreData, an old framework that originates way back to NeXT times. Back then NeXT had a product called the “Enterprise Objects Framework” / EOF, probably one of the first ORM’s. Unlike CoreData, EOF was able to talk to a large range of database systems, from RDBMS like Oracle, to more obscure things like LDAP servers. Good times.

CoreData picked up on that, but refocused on client-side only, local storage. Either in XML files or in SQLite databases. It is worth mentioning that it lost the “mapping” aspect of ORMs/EOF. I.e. it is not possible to take an arbitrary SQLite database and map that to the model layer objects. CoreData “owns” the schema of the underlying database.

There is a confusing terminology mismatch between CoreData and SwiftData. When people talk about a “model” today, they usually mean what is called the “entity” in an ER model. Previously a “model” was the set of entites and their relationships.
CoreData is using the “old” naming (e.g. ManagedObjectModel) while SwiftData uses todays convention. The “model” is now called the Schema and the “models” are the classes.

A problem w/ CoreData (or Swift, depending on your PoV) is that it makes extensive use of the Objective-C runtime features, i.e. heavy swizzling, dynamic subclassing and more. That bites w/ the static nature that Swift developers prefer.

Another problem w/ CoreData is the “modeler” that is (now) part of Xcode. In that the schema is setup dynamically, it gets stored to disk and loaded at runtime (and then uses reflection to match up the schema with the classes). It is a little similar to using Interface Builder vs. SwiftUI.

In short: CoreData and Swift was never a particularily good match.

SwiftData

So at WWDC 2023 Apple eventually released SwiftData. It’s available for iOS 17+ and macOS 14+, same for the new Observation framework it integrates with.

SwiftData turned out to be quite surprising. I think it is fair to say that many envisioned something completely reimagined, built from scratch, specifically for Swift. Like Apple did with SwiftUI. Structures and async/await everywhere.
SwiftData is that not. At least not yet.

SwiftData is a Swift shim around CoreData, but it completely hides it (which may be a hint that a different variant will be provided at one point). SwiftData PersistentModel’s become CoreData NSManagedObject’s under the hood (check BackingData).
And PersistentModel’s still have to be actual class objects (reference types) vs. structures aka value types that Swift devs love.

So what does the API look like. The two key components are the @Model macro and the @Query property wrapper for SwiftUI. That’s all you need to get up and running:

import SwiftUI
import SwiftData

@Model class Contact {
    var name = ""
    var addresses = [ Address ]()
}

@Model class Address {
    var street: String = ""
    var contact: Contact?
}

struct ContentView: View {
    @Query var contacts: [ Contact ]

    var body: some View {
        ForEach(contacts) { contact in
            Text(verbatim: contact.name)
        }
        .modelContainer(for: Contact.self)
    }
}

Much more convenient than fiddling w/ CoreData directly. Models directly declared in code, CoreData setup procedure massively simplified.

Here is a set of links to SwiftData WWDC videos, they are all pretty good:

ManagedModels

Now ManagedModels tries to provide that convenience for CoreData itself. Instead of wrapping CoreData, it directly builds upon CoreData. The primary advantage over SwiftData is that it back deployes a long way. And if a CoreData application exists already, it can be easily added to that, dropping the requirement for the xcdatamodel.

The SwiftData example from above, but using ManagedModels:

import SwiftUI
import ManagedModels

@Model class Contact: NSManagedObject {
    var name = ""
    var addresses = [ Address ]()
}

@Model class Address: NSManagedObject {
    var street = ""
    var contact: Contact?
}

struct ContentView: View {
    @FetchRequest var contacts: FetchedResults<Contact>

    var body: some View {
        ForEach(contacts) { contact in
            Text(verbatim: contact.name)
        }
        .modelContainer(for: Contact.self)
    }
}

That its slightly different, but almost as convenient.

Just add https://github.com/Data-swift/ManagedModels.git as a package dependency to get this up and running.

Note: When building for the first time, Xcode will ask you to approve the use of the provided macro.

Differences to SwiftData

It looks similar, and kinda is similar, but there are some differences.

Explicit Superclass

First of all, the classes must explicitly inherit from NSManagedObject. That is due to a limitation of Swift Macros. A macro can add protocol conformances, but it can’t a superclass to a type.

Instead of just this in SwiftData:

@Model class Contact {}

the superclass has to be specified w/ ManagedModels:

@Model class Contact: NSManagedObject {}

@FetchRequest instead of @Query

Instead of using the new SwiftUI @Query wrapper, the already available @FetchRequest property wrapper is used.

SwiftData:

@Query var contacts : [ Contact ]

ManagedModels:

@FetchRequest var contacts: FetchedResults<Contact>

Properties

The properties now work quite similar, thanks to some hints by Aleksandar Vacić.

ManagedModels also provides implementations of the @Attribute, @Relationship and @Transient macros.

More complex Swift types are always stored as JSON by ManagedModels. RawRepresentable’s w/ a base types (like enum Color: String {...} or enum Priority: Int {...}) are stored as the base type.

Codable attributes should now work, untested. It works a little different to SwiftData, which decomposes some Codables (splits nested properties into own attributes / database columns).

Initializers

A CoreData object has to be initialized through some very specific initializer, while a SwiftData model class must have an explicit init, but is otherwise pretty regular.

The ManagedModels @Model macro generates a set of helper inits to deal with that. But the general recommendation is to use a convenience init like so:

convenience init(title: String, age: Int = 50) {
    self.init()
    title = title
    age = age
}

If the own init prefilles all properties (i.e. can be called w/o arguments), the default init helper is not generated anymore, another one has to be used:

convenience init(title: String = "", age: Int = 50) {
    self.init(context: nil)
    title = title
    age = age
}

The same init(context:) can be used to insert into a specific context. Often necessary when setting up relationships (to make sure that they live in the same NSManagedObjectContext).

Those should be the most important differences ✔︎ Still a few, but workable.

Example App

There is a small SwiftUI todo list example app, demonstrating the use of ManagedModels. It has two connected entities and shows the general setup: Managed ToDos.

Everyone loves screenshots, this is what it looks like:

It should be self-explanatory. Works on macOS 13 and iOS 16, due to the use of the new SwiftUI navigation views. Could be backported to even earlier versions.

Northwind

There is also a significantly more complex example: Northwind for ManagedModels.

This is the old Northwind database packaged up as a Swift package that works with ManagedModels. It contains a set of model classes and a prefilled database which makes it ideal for testing, to get started quickly.

It is actually a straight port of a SwiftData version: NorthwindSwiftData and as a result a good way to compare how SwiftData and ManagedModels differ.

Sample usage (import https://github.com/Northwind-swift/NorthwindSwiftData.git):

import SwiftUI
import NorthwindSwiftData // @Northwind-swift/NorthwindManagedModels

@main
struct NorthwindApp: App {

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(try! NorthwindStore.modelContainer())
    }
}

struct ContentView: View {

    @FetchRequest(sort: \.name)
    private var products: FetchedResults<Product>
    
    var body: some View {
        List {
            ForEach(products) { product in
                Text(verbatim: product.name)
            }
        }
    }    
}

Northwind for ManagedModels Documentation

Internals

The provided @Model is a non-trivial Swift Macro and might be helpful for people interested in how to write such.

Interested how this Swift code:

@Model class Contact: NSManagedObject {    
    var name: String
    var age: Int
}

is expanded by @Model? Buckle up:

class Contact: NSManagedObject {

    // @_PersistedProperty
    var name: String
    {
        set {
            setValue(forKey: "name", to: newValue)
        }
        get {
            getValue(forKey: "name")
        }
    }    

    // @_PersistedProperty
    var age: Int
    {
        set {
            setValue(forKey: "age", to: newValue)
        }
        get {
            getValue(forKey: "age")
        }
    }    
    
    /// Initialize a `Contact` object, optionally providing an
    /// `NSManagedObjectContext` it should be inserted into.
    /// - Parameters:
    //    - entity:  An `NSEntityDescription` describing the object.
    //    - context: An `NSManagedObjectContext` the object should be inserted into.
    override init(entity: CoreData.NSEntityDescription, insertInto context: NSManagedObjectContext?)
    {
        super.init(entity: entity, insertInto: context)
    }

    /// Initialize a `Contact` object, optionally providing an
    /// `NSManagedObjectContext` it should be inserted into.
    /// - Parameters:
    //    - context: An `NSManagedObjectContext` the object should be inserted into.
    init(context: CoreData.NSManagedObjectContext?) {
        super.init(entity: Self.entity(), insertInto: context)
    }

    /// Initialize a `Contact` object w/o inserting it into a
    /// context.
    init() {
        super.init(entity: Self.entity(), insertInto: nil)
    }

    static let schemaMetadata : [ CoreData.NSManagedObjectModel.PropertyMetadata ] = [
        .init(name: "name", keypath: \Contact.name,
              defaultValue: nil,
              metadata: CoreData.NSAttributeDescription(name: "name", valueType: String.self)),
        .init(name: "age", keypath: \Contact.age,
              defaultValue: nil,
              metadata: CoreData.NSAttributeDescription(name: "age", valueType: Int.self))]

    static let _$originalName : String? = nil
    static let _$hashModifier : String? = nil
}
extension Contact: ManagedModels.PersistentModel {}

Essentially:

Attaches setters and getters to properties, which hit the actual CoreData storage.
Override of init(entity:insertInto:), that ties into the entity.
A helper init(context:) that calls init(entity:insertInto:) with the entity.
Two supporting attributes for CoreData migration: _$originalName and _$hashModifier.

If someone has more specific questions, feel free to ping me.

Closing Notes

ManagedModels still has some open ends and I’d welcome any PR’s enhancing the package.

Even though I’ve re-implemented EOF quite a few times already (e.g. in SOPE, GETobjects, ZeeQL), I have to admit that I’m not a CoreData expert specifically 😀 So I’m happy about any feedback on things I might be doing incorrectly. Though it does seem to work quite well.

Either way, I hope you like it!

Contact

Feedback is warmly welcome: @helje5, @helge@mastodon.social, me@helgehess.eu. GitHub.

Want to support my work? Buy an app: Code for SQLite3, Past for iChat, SVG Shaper, HMScriptEditor. You don’t have to use it! 😀

The Lighter Swift Codegen for SQLite3

Tue, 16 Aug 2022 00:00:00 +0200

Lighter is a set of technologies applying code generation to access SQLite3 databases from Swift, e.g. in iOS applications or on the server. Like SwiftGen but for SQLite3.

Type-safe down to the SQL schema.

State of the art: Developer writes Swift structures that match a SQLite table. Enlighter reverses this, the generated Swift code reflects what the SQLite table is actually defined as. No place for mistakes. Remove a “somewhere” in the “it’s always any-o-clock somewhere in the stack”.

Very, very, fast.

Lighter builds upon the database schema and hence directly knows what it looks like at compile time. For common operations no mapping is necessary at all, the generated code runs as fast (usually faster) than hand written code. It directly binds Swift structures to the SQLite API.

Dependency free.

Lighter itself is a small and convenient API to access SQLite databases. Enlighter, the code generator, can however produce code that just uses the SQLite API and doesn’t require any dependencies, i.e. tech debt. Don’t ship 3rd party libraries, directly generate the necessary code into your app.

Lighter is useful for two main scenarios:

Shipping SQLite databases within your app (e.g. containing a product database).

SQLite databases are very resource efficient way to ship and access small and big amounts of data. As an alternative to bundling JSON resources files that are large and have to be parsed fully into memory on each start. With a SQLite database only the required data needs to be loaded and the database files are extremely compact (e.g. no duplicate keys). > SQLite database are also efficient and useful for downloading > data from the network!

Maintaining a fast local SQL cache or database.

If the needs are simpler than a full [ORM](https://en.wikipedia.org/wiki/Object–relational_mapping) like [CoreData](https://developer.apple.com/documentation/coredata), Lighter can be a great way to produce neat and typesafe APIs for local caches or databases. It is basic but convenient to use and very very fast as no runtime mapping or parsing has to happen at all. The code directly binds the generated structures to the SQLite API. Databases can be created on the fly or from prefilled database files shipped as part of the application resources. > Linux is also supported, and Lighter can be a great choice for simple servers that > primarily access a readonly set or run on a single host.

Overview

Lighter works the reverse from other “mapping” tools or SQLite wrappers. Instead of writing Swift code that generates SQLite tables dynamically, Lighter generates Swift code for a SQLite database. Either literally from SQLite database files, or from SQL files that create SQLite databases.

Small Example Database (stored in either a SQLite db or created from .sql files):

CREATE TABLE person (
  person_id INTEGER PRIMARY KEY NOT NULL,
  name      TEXT NOT NULL,
  title     TEXT NULL
);

CREATE TABLE address (
  address_id INTEGER PRIMARY KEY NOT NULL,
  
  street  VARCHAR NULL,
  city    VARCHAR NULL,
  
  person_id INTEGER,
  FOREIGN KEY(person_id) REFERENCES person(person_id) ON DELETE CASCADE DEFERRABLE
);

Can be converted to a structure like this (in a highly configurable way):

struct ContactsDB {

  struct Person: Identifiable, Hashable {
    var id       : Int
    var name     : String
    var title    : String?
  }

  struct Address: Identifiable, Hashable {
    var id       : Int
    var street   : String?
    var city     : String?
    var personId : Int?
  }
}

The code generator can either generate dependency free code that only uses the raw SQLite3 API or code that uses the Lighter library. The Lighter library is not an ORM, but just a set of Swift protocols that allow for typesafe queries (and it is only intended to be used to support the code generator, not as a standalone library).

How does the code generation work?

The setup is intended to work with the new Swift Package Plugins feature of the Swift Package Manager, available since Swift 5.6 (and exposed in Xcode 14+). If SPM plugins cannot be used yet, the sqlite2swift tool can be called directly as well.
If you want to support the project, there is also the Code for SQLite3 app on the Mac AppStore. It does the same code generation as this FOSS project in a little more interactive way.

The Lighter package comes with a “build tool plugin” called Enlighter, that automatically integrates the code generation results into the build process. If it is added to a target, it’ll scan for databases and SQL files and create the Swift accessors for them:

.target(name: "ContactsDB", dependencies: [ "Lighter" ],
        resources: [ .copy("ContactsDB.sqlite3") ],
        plugins: [ "Enlighter" ]) // <== tell SPM to use Enlighter on this target

This variant is fully automatic, i.e. other code within the ContactsDB target has direct access to the database types (e.g. the Person struct above).

As a manual alternative the Generate Code for SQLite “command plugin” is provided. This plugin does the same generation as Enlighter, but is explicitly run by the developer using the Xcode “File / Packages” menu. It places the resulting code into the “Sources” folder of the app (where it can be inspected or modified).

Accessing a database using the higher level Lighter API

// Open a SQLite database embedded in the module resources:
let db = ContactsDB.module!

// Fetch the number of records:
print("Total number of people stored:", 
      try db.people.fetchCount())

// There are various ways to filter, including a plain Swift closure:
let people = try db.people.filter { person in
  person.title == nil
}

// Primary & foreign keys are directly supported:
let person    = try db.people.find(1)
let addresses = try db.addresses.fetch(for: person)

// Updates can be done one-shot or, better, using a transaction:
try await db.transaction { tx in
  var person = try tx.people.find(2)!
  
  // Update a record.
  person.title = "ZEO"
  try tx.update(person)

  // Delete a record.
  try tx.delete(person)
  
  // Reinsert thew same record
  let newPerson = try tx.insert(person) // gets new ID!
}


#### Fetching Individual Columns

One of the advantages of SQL is that individual columns can be selected
and updated for maximum efficiency. Only things that are
required need to be fetched (vs. full records):
```swift
// Fetch just the `id` and `name` columns:
let people = try await db.select(from: \.people, \.id, \.name) {
  $0.id > 2 && $0.title == nil
}

// Bulk update a specific column:
try db.update(\.people, set: \.title, to: nil, where: { record in
  record.name.hasPrefix("Duck")
})

The references are fully typesafe down to the schema, only columns contained in the person table can be specified.

Dependency free SQLite3 API

The toolkit is also useful for cases in which the extra dependency on Lighter is not desirable. For such the generator can produce database specific Swift APIs that work alongside the regular SQLite API.

// Open the database, can also just use `sqlite3_open_v2`:
var db : OpaquePointer!
sqlite3_open_contacts("contacts.db", &db)
defer { sqlite3_close(db) }

// Fetch a person by primary key:
let person = sqlite3_person_find(db, 2)
  
// Fetch and filter people:
let people = sqlite3_people_fetch(db) {
  $0.name.hasPrefix("Ja")
}

// Insert a record
var person = Person(id: 0, name: "Jason Bourne")
sqlite3_person_insert(db, &person)

There is another style the code generator can produce, it attaches the same functions to the generated types, e.g.:

let people = Person.fetch(in: db) { $0.name.hasPrefix("So") }
var person = Person.find(2, in: db)

person.name = "Bourne"
person.update(in: db)
person.delete(in: db)
person.insert(into: db)

The main advantage of using the raw API is that no extra dependency is necessary at all. The generated functions are completely self-contained and can literally be copied&pasted into places where needed.

Beautiful, autogenerated DocC API Comments

The Lighter code generator can also generate API comments for the database types.

Example: Northwind Database.

Interested? 👉 Getting Started.

Who

Lighter is brought to you by Helge Heß / ZeeZide. We like feedback, GitHub stars, cool contract work, presumably any form of praise you can think of.

Want to support my work? Buy an app: Code for SQLite3, Past for iChat, SVG Shaper, HMScriptEditor. You don’t have to use it! 😀

Flutter for SwiftUI Developers (and 🔄)

Mon, 06 Jun 2022 00:00:00 +0200

In the last few months Flutter gained some popularity as a cross platform UI framework. We’ll have a look at it from a SwiftUI developer’s perspective, as it has a quite similar way to construct user interfaces, “declaratively”.

This is going to be a longish article looking at various aspects. Feel free to jump around:

Introduction
Setup: Install Flutter using Homebrew.
Basic Concepts: Dart and Widgets.
Comparing the HelloWorld App: Flutter and Swift, side-by-side.
Intermission: A video!
Dart and Swift: Dart syntax alongside Swift.
Packages: Pub.dev Cows.
Platform Widgets: Welcome to Cupertino!
Advanced State Management: ViewController, Environment Objects
Navigation: ViewController, again
Small Web Service App: HTTP, JSON, Flutter
Closing Notes

Disclaimer: Flutter knowledge is from playing with things for about a week. Feel free to send corrections to me@helgehess.eu.

Introduction

Having seen “XP kits” come and go for over 25 years (yes, including YellowBox for Windows, XUL or Swing), I generally believe that it is proven by history that using cross platform UI frameworks is almost universally the wrong™️ approach.
They tend to produce a look and feel that is off on all platforms, rarely integrate with platform features, are often slugish and also fail to deliver lower development costs.

But hey, it is still interesting and fun to play with things and see how stuff fits together 🤓 Flutter is quite interesting for SwiftUI developers because it is very similar. Almost feels like Apple hired the original Flutter developers to produce a “better” version.

So I’ve been interested what the hype is about and took some time to build a small Flutter app, to learn how that goes and how it compares to SwiftUI.

Oh, something to keep in mind: Flutter is a Google project.

As a preview, this is what a simple Flutter app looks like, we’ll get to all the details later:

import 'package:flutter/material.dart'; // import module

void main() {            // the Dart app entry point
  runApp(const MyApp()); // const is funny, later!
}

class MyApp extends StatelessWidget { // Application
  const MyApp({Key? key}) : super(key: key); // named parameter

  @override // var body: some View
  Widget build(BuildContext context) { // ctx is the Environment
    return MaterialApp( // use the ugly Material styling
      title: 'Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyHomePage(title: 'Demo')
    ); // notice all the `;`? required!
  }
}

class MyHomePage extends StatefulWidget { // a View
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title; // non @State View ivar, final is let

  @override  // A `StatefulWidget`, State is extra
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> { // generics
  int _counter = 0; // roughly an ObservableObject ivar

  @override // var view: some View
  Widget build(BuildContext context) {
    return Scaffold( // ~NavigationView
      appBar: AppBar(title: Text(widget.title)), // .navigationTitle...
      body: Center(child: Column( // ~ZStack(VStack(...))
        mainAxisAlignment: MainAxisAlignment.center, // VStack(alignment:)
        children: [
          const Text('Count:'),
          Text('$_counter') // String interpolation
        ]
      )),
      floatingActionButton: FloatingActionButton(
        onPressed: () { // closure
          setState(() { // objectWillChange.send()
            _counter++; // ++!!
          });
        },
        tooltip: 'Increment',
        child: const Icon(Icons.add)
      )
    );
  }
}

It is more boilerplate and syntax, but pretty close to what one would do in SwiftUI.

Setup

Installing Flutter using Homebrew is simple (and doesn’t seem to clutter the system much or do unexpected things):

$ brew install flutter

And since we are going to use Visual Studio Code as the “IDE”, this might be useful:

$ brew install --cask visual-studio-code

I had a look at VSCode for Swift in this article, if an introduction is desirable. There doesn’t seem to be a nice looking Mac IDE for Flutter, maybe Nova? VSCode is ugly but bearable.

There is a flutter doctor command that can be run to check whether the Flutter installation went well:

$ flutter doctor
[✓] Flutter (Channel stable, 3.0.1, on macOS 12.4 21F79 darwin-arm, locale en-DE)
[✗] Android toolchain - develop for Android devices
...

To create a new project, flutter create is used:

$ flutter create cowtastic
Signing iOS app for device deployment using developer identity: "Apple Development: Helge Heß (ABC12DEFGH)"
Creating project cowtastic...
Running "flutter pub get" in cowtastic...                          918ms
Wrote 127 files.

All done!
In order to run your application, type:

  $ cd cowtastic
  $ flutter run

Your application code is in cowtastic/lib/main.dart.

Yes, no kidding, this produces a folder with no less than 65 directories and 132 files. The sole interesting to us is main.dart, living in the lib subfolder.

This can be run on the command line already, but it is more useful to go straight to Visual Studio Code. There are two extensions which seem useful and should be installed (using the extensions tab on the left): Flutter and Pubspec Assist.

This is what it will look like:

When starting the app for the first time, macOS signing issues come up. In case Google (and Homebrew) are trusted, confirm such in the macOS preferences:

To select whether you want to test the app on a device, on a simulator or run it as a “Mac app”, click the target at the lower right. Then chose “Start iOS Simulator” for simulator (or stick to the device):

This will just start the simulator.

Pressing F5 builds and starts the app (and potentially brings up the macOS security panels until things are granted). Starting the app takes a moment as things are being xcodebuild’.

Congratulations, first Flutter app is running.

You’ll notice that the app looks quite wrong for an iOS app. That is because everything defaults to Google’s “Material” theme (and most of the tutorials rely on it). It can be changed to look a little more like UIKit, we’ll get to that.

Basic Concepts

It may look a lot like Java on first sight, but Flutter apps are actually written in an own programming language called Dart. It’s OK, less strict. Swift looks nicer, has way more conveniences. Dart compiles myriads faster - literally on save. And has a proper GC, no ARC. A few language examples follow below.

Flutter itself is a framework on top. The key concept of Flutter is a Widget, which is essentially the same thing like a SwiftUI View (though it is also used for ViewModifier’s, App, everything). Their tagline is:

Flutter, where Everything is a Widget™

I wonder whether the common desire to force everything into Views on SwiftUI is rooted in that.

What is different to SwiftUI is that a Widget itself doesn’t really have state, it is immutable. It can be a StatefulWidget, but those still don’t carry the state inside the Widget, but in a separate, State<Widget> object. Pretty similar to our ViewController.
Speaking of objects, everything in Dart is classes and objects (though often immutable or const), no structs.

Comparing the HelloWorld App

In the introduction I’ve shown the boilerplate app flutter create generates. It is a simple screen with a Text, showing a counter, and a button to increase that counter. Because it has to store the current count it involves a StatefulWidget.

Note how the SwiftUI app an the right looks proper by default and the Flutter app on the left looks like an Android thing. We will look at that later.

This is roughly what the same app would look like in SwiftUI:

import SwiftUI

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      MyHomePage(title: "SwiftUI Demo")
    }
  }
}

struct MyHomePage: View {
  
  let title : String
  @State private var counter = 0
  
  var body: some View {
    NavigationView {
      VStack(alignment: .center) {
        Text("You have pushed the button this many times:")
        Text("\(counter)")
          .font(.title)
      }
      .navigationTitle(title)
      .toolbar {
        Button(action: { counter += 1 }) {
          Label("Increment", systemImage: "plus.circle")
        }
      }
    }
  }
}

Let’s compare the different parts.

App Setup

In both environments there is a main entry point, where the application itself is configured. It is just a main function in Dart and Swift got the magic @main annotation in 2020.

import 'package:flutter/material.dart';

void main() { runApp(const MyApp()); }

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) => MaterialApp(
    title: 'Demo',
    theme: ThemeData(primarySwatch: Colors.blue),
    home: const MyHomePage(title: 'Demo')
  );
}

SwiftUI:

import SwiftUI

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      MyHomePage(title: "Flutter Demo Home Page")
    }
  }
}

Flutter has more boilerplate, it kinda feels like how you would write a SwiftUI-like framework in a language you don’t control (weird as it seems tightly coupled to Dart).
Swift got a set of specific language enhancements to support SwiftUI, including Property Wrappers and Result Builders. Those make SwiftUI sources look nicer, but not necessarily easier to follow along.

As mentioned, Flutter uses Widget for everything, while SwiftUI has more specific types, like App, but the idea is the same:

Widget build(BuildContext context) => MaterialApp(...);

In SwiftUI the build function is a computed body property:

var body: some Scene { ... }

In Flutter the build functions carry around a BuildContext, which is quite similar to the SwiftUI Environment. E.g. it is used to pass down FontStyle’s, themes and something comparable to @EnvironmentObject’s.

The page setup is a little more interesting (in SwiftUI the “root view” is commonly called ContentView, but I went with MyHomePage to match up w/ the Flutter setup).

State

In Flutter “state” is handled separately from Widgets, while in SwiftUI allows View “configuration” and its “state” to be intermingled in a single entity. The latter makes for nice compact demos (as this) but generally tends to lead to spaghetti code once apps start to grow. When doing things cleanly in SwiftUI they end up looking quite similar.

So in Flutter, the MyHomePage is a StatefulWidget:

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title; // final is let

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

Note that “StatefulWidget” doesn’t mean that the widget itself carries state, it is still the immutable “configuration” (the title parameter). Instead the state is pushed into a separate State object:

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) { ... }
}

Very similar to what people do in clean SwiftUI code and often call “ViewModels” (implemented as ObservableObject’s).
What I found a little surprising that the State itself also has a build function, instead of the associated widget having a build function that can get to the State. That is very similar to our ViewController approach. State is such a ViewController, it is a very specific ObservableObject that has a View attached, which is being controlled.

This is what the plain, demoware, version in SwiftUI looks like:

struct MyHomePage: View {
  
  let title : String
  @State private var counter = 0
  
  var body: some View { ... }
}

It carries the title configuration as well as the counter @State. This is way more compact then the Flutter version w/ two objects, but it also adds a lot of magic and often unexpected behaviour. @State essentially turns the View “struct” into an object (i.e. it gets an “identity”).
Here I actually prefer the Flutter setup where the State has its own identity, and as mentioned, that’s what you often end up with in SwiftUI anyways.

There is one more aspect to state management in that Widget/View, how the state is modified.

Flutter:

onPressed: () {
  setState(() { 
    _counter++;
  }
}

SwiftUI:

action: { counter += 1 }

This is much more compact in SwiftUI because the @State property wrapper sees the modification and automatically marks the View for re-evaluation (similar thing w/ @Published).
In Flutter the modifications have to be wrapped in a setState() call, which tells the system that things changed explicitly (presumably it does snapshotting and diffing as part of that).

Page Layout

The way the build/body is implemented is quite similar again. There are two significant differences:

SwiftUI uses Result Builders, essentially a different language syntax with some benefits to both source code beauty and performance (they preserve the full static type of the View tree).
Flutter just uses regular function calls in the common builder pattern.
Flutter doesn’t usually use ViewModifier’s like .padding (though I think that would be possible, it is just not idiomatic), but rather wraps Widgets in Widgets in Widgets (e.g. in a Container for padding).

Widget build(BuildContext context) => Scaffold(
  appBar: AppBar(title: Text(widget.title)),
  body: Center(child: Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: [
      const Text('Count:'),
      Text('$_counter')
    ]
  )),
  floatingActionButton: FloatingActionButton(
    onPressed: () => setState(() { _counter++; }),
    tooltip: 'Increment',
    child: const Icon(Icons.add)
  )
);

This is just calling into the constructors of the respective widgets, with the arguments being subwidgets, sometimes for specific sections. No trailing closures or result builders, hence the subviews live within the arguments of the widget’s “init call”.

Widgets used:

Scaffold is a widget from the “Material” library. It essentially provides the layout w/ the title bar, the floating button, and the page contents. Somewhat similar to NavigationView in SwiftUI.
AppBar is a widget drawing the actual title bar. Similar to the .navigationTitle modifier and companions.
Center just centers its single child Widget in the available space, kinda like a ZStack with just one child, though it also “expands” (takes the available space).
Column is a VStack, its mainAxisAlignment says how the content distributes vertically, somewhat related to .layoutPriority. The crossAxisAlignment is the same like the alignment parameter of the VStack (uses start instead of leading, end instead of trailing, note that the enum needs to be spelled out, just .center is insufficient).
Text, which is just like Text. Though the interpolation (Text('$_counter)) is done by the language, not by Text itself. I.e. it probably can’t do the localization things SwiftUI can do.
Other containers are:
- Row, which is the HStack
- Container, which is used to add padding and decoration like borders, background colors.

Approximately the same in SwiftUI:

var body: some View {
  NavigationView {
    VStack(alignment: .center) {
      Text("You have pushed the button this many times:")
      Text("\(counter)")
        .font(.title)
    }
    .navigationTitle(title)
    .toolbar {
      Button(action: { counter += 1 }) {
        Label("Increment", systemImage: "plus.circle")
      }
    }
  }
}

I think that SwiftUI definitely looks nicer, but the Flutter thing is quite reasonable as well. And doesn’t require any extra language features.

Intermission: Things that are great in Flutter.

That was a lot already, let’s have a video. Something that is really great about Flutter is the speed of iteration, seeing is believing:

Your browser does not support the video tag.

The app was originally started using F5, which takes a moment. But you rarely ever do that. Once started you just edit a source file (here we change the theme color from blue to green), save the file and 💥 boom, the app just updates in the simulator.
And it just works. Like always. It is nothing like Xcode previews which are a trainwreck except for the most simple scenarios (I tend to create own Xcode projects just for previews, when having to iterate over some visuals of a View).

This part is really unbelievably good about Flutter development. Swift has a hard time here due to it being extremely static and incredibly slow. We’ll see whether WWDC 2022 brings improvements. I kinda doubt it.

Another thing that is just great in Flutter, but awful in SwiftUI, is the documentation. Don’t get us wrong, the SwiftUI documentation is extremely beautiful. What it doesn’t do well is document actual SwiftUI development (presumably because it is written by people who never wrote a real SwiftUI application).
And the documentation of symbols, usability is close to zarro 🙈

Flutter documentation is the opposite. A little ugly, but extremely helpful and always to the point. It feels like it is written by developers who actually used Flutter and know what information a developer is looking for. From Getting Started, over class documentation, to the Cookbook. Great stuff.

I think those two things are where Flutter doesn’t flutter but really flies. But let’s go back to the tech.

Dart and Swift

If you used a C or Java language before, it is pretty straight forward. What follows is a small overview of Dart syntax.

You have to use semicolons, coming from Swift I forgot them all the time:

onPressed: () {
  setState(() {
    _counter++; // <= semicolon!
  });           // <= another semicolon!
},

Also shows Dart closures, above two closures without parameters:

( parameters ) { code }

It does not have trailing closures like Swift, e.g. you cannot write it like this:

setState { // doesn't fly in Dart
  _counter++
}
setState(() { // needs to be inside the argument list
  _counter++;
});

There are a lot of those small syntactic things which make Swift look more beautiful and clean, though oftentimes it actually makes it harder to read.

You also have to use return in blocks that return a value, e.g. this returns a new Widget (read: View):

Widget build(BuildContext context) {
  return MaterialApp(...);
}

Though there is a similar shortcut syntax like in JavaScript, if the function is just a single expression. I found it to be applicable often, and generally nice looking:

Widget build(BuildContext context) => MaterialApp(
  ...
); // <= semicolon needed here!

Also shown: the return types of functions and arguments and variables are spelled before the name, not after. Like in C/Java. Also no func keyword is needed. E.g. the above would be this in Swift:

func build(_ context: BuildContext) -> Widget {
  MaterialApp(...)
}

Dart has both positional and named parameters, like Swift. Shown above are positional, i.e. build is called like this:

widget.build(context);

not like this (which would be the default in Swift, w/o the _ placeholder):

widget.build(context: context); // wrong for positional

Named parameter declarations have a syntax that is a little weird:

MyApp({Key? key})

key is the parameter name, Key? the type.

Which brings us to Optionals (Key? - an optional Key). Current Dart has the concept of nullability and nullability checks, but does it a little less “in your face”. Generally, like in Smalltalk, all values in Dart are objects (and allow a null variant). That even includes things like int:

final int  a = 42;   // pushing null raises error
final int? b = null;
if (b != null) return b!;
final int  c = b!;   // force unwrap is there, error throws
final d      = c;    // "auto" also available

The final is the same like let in Swift:

let a : Int  = 42;   // not possible to set to `nil`
let b : Int? = nil;
if let b { return b }
let c : Int  = b!;   // runtime crash
let d = c

Note that Dart requires parenthesis () in if conditions (and for etc), but allows single statement blocks w/o braces {} (if (x) return 42;).

Shown before, Dart doesn’t have have Result Builders like in this Swift:

VStack {
  Text("Hello")
  Text("World")
}

which is a clever but complicated thing explained elsewhere, instead things are constructed using regular calls:

Row(children: [
  Text("Hello"),
  Text("World")
])

Which isn’t that awful from a coding perspective.

I don’t want to go too much into generics, but generally in SwiftUI you’ll get to fight with them more often (for somewhat good reasons). I.e. things like AnyView are not necessary in Flutter, you just use the Widget base class.

Dart has stdlib functions like map, which return an Iterable. Again, less generic boilerplate that has to be dealt with. Sample:

_saved.map( (pair) => Text(pair.asPascalCase));

The Swift Any type is called dynamic in Flutter. E.g. this Swift:

let json : [ String : Any ]
let json : Dictionary<String, Any> // or this

looks like this in Dart:

final Map<String, dynamic> json;

To cast, Dart has is and as:

List<SPIPackage> _decodeJSON(dynamic json) {
  final jsonDict = json as Map<String, dynamic>;
  final results  = jsonDict["results"] as List<dynamic>;

  for (final result in results) {
    final json = result as Map<String, dynamic>;
    if (json["package"] == null) continue;

The way to work w/ a JSONSerialization like JSON result. If the type doesn’t match, they fail with a runtime error. “Deep casts” don’t work like in Swift. E.g. this doesn’t fly:

final typed = json as Map<String, Map<String, List<Map<String, dynamic>>>>

The casting has to be done step-by-step.

(Thanks god) there is no Coddable in Dart. Though it also disables runtime reflection, which results in the developer having to do it manually (which I think is OK):

factory SPIPackage.fromJson(Map<String, dynamic> json) => SPIPackage(
  packageId      : json['packageId'],
  repositoryName : json['repositoryName'],
  ...
);

… or resort to code generation (which I dislike, code generation is wrong™️). This also does an implicit as cast, to String in this case:

class SPIPackage {
  final String packageId;
  final String repositoryName;
  ...
}

final class doesn’t work, btw. Nor can you nest a class in another class.

There is async/await, but it is Future based. The compute function starts things in an isolate, which seems kinda like a Swift actor. An example:

class _SPMListPageState extends State<SPMListPage> { 
  late Future<List<SPIPackage>> _packages; // late is like lazy

  Future<List<SPIPackage>> _querySPI(String query) async { // <= async!
    final response = await http.get( // <= await
      Uri(scheme: "https",  host: "swiftpackageindex.com",
          path: "/api/search", 
          queryParameters : { "query": query })
    );

    if (response.statusCode == 200) {
      return _decodeJSON(jsonDecode(response.body));
    }
    else {
      throw Exception("Failed to run query! ${response.statusCode}");
    }
  }
  ...
}

How does that integrate into Flutter Widgets? Everything is a widget! FutureBuilder:

Widget _buildResultView(BuildContext context) =>
  FutureBuilder<List<SPIPackage>>(
    future: _packages,
    builder: ( ctx, snapshot ) {
      if (snapshot.hasData) {
        return _buildResultList(context, snapshot.data as List<SPIPackage>);
      }
      else if (snapshot.hasError) {...}
      else { PlatformCircularProgressIndicator()); }
    }
  );

The Swift typealias is also available and called typedef in Dart, from UXKit.dart:

typedef UXApp        = PlatformApp;
typedef UXScaffold   = PlatformScaffold;
typedef UXAppBar     = PlatformAppBar;
typedef UXIconButton = PlatformIconButton;

Another funny thing the attentive reader may have noticed are the _ prefixes everywhere, like:

late Future<List<SPIPackage>> _packages;
Widget _buildResultView(BuildContext context)

It is exactly what you’d think it is: the _ prefix marks things as internal/private. Symbols w/o are public. E.g. the State of a StatefulWidget is usually private and starts with an _.
I think that’s not the worst approach as it removes clutter and is obvious.

A few data types:

final answer         = 42;            // an int
final isIt           = "1337";        // a String
final setOfWordPairs = <WordPair>{};  // a Set
final wordPairs      = <WordPair>[];  // a List, Array in Swift
final answers = { 42: "The Answer" }; // a Map,  Dictionary in Swift

final answer = answers[42];

Strings have interpolation, but not the customizable subsystem Swift has:

final singleVar = Text('$answer');
final exprPath  = Text("${answers[42]}");

To finish the Dart overview, it has a funny const construct you see a lot:

Column(children: [
  const Text('Count:'),
  Text('$_counter')
]);

It is a little like a callsite singleton and makes sure that just one instance of a “constant object” exists. E.g. in this case the Text w/o a variable reference is a compile time constant and won’t be required each time. That “constantness” can propagate through hierarchies, like that:

const Column(children: [
  Text('Hello'),
  Text('World')
]);

VSCode tells you if a const should be added.

Packages

🐄 Time to add some cows! 🐮

Dart comes with a package system and has an official package registry: pub.dev. Swift has SPM and the (unofficial but great) Swift Package Index.

What Package.swift is to Swift, pubspec.yaml is for Dart:

name: cowtastic
description: A new Flutter project.
version: 1.0.0+1

environment:
  sdk: ">=2.17.1 <3.0.0"

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.2

dev_dependencies:
  flutter_test:
    sdk: flutter
flutter:
  uses-material-design: true

Should be self-explanatory.

Packages can be added manually, or if the Pubspec Assist VSCode extension was installed, using that (⌘⇧ P, then “Pubspec”, “Add/update deps”):

Dart doesn’t seem to have a great cows package like Swift (or JavaScript), but at least cowsay is available. This gets added to the pubspec.yaml:

dependencies:
  cowsay: ^1.0.0
  cupertino_icons: ^1.0.2
  flutter:
    sdk: flutter

Generally having a declarative package format seems like a waaay better approach than what SPM does with Package.swift (and all the pain that comes due to that).

To use cowsay, it needs to be imported into the main.dart file. Package lookup has (working!) auto-complete in VSCode:

import 'package:flutter/material.dart';
import 'package:cowsay/cowsay.dart';

Note how a specific .dart file is imported, not really a package. And package is an URL scheme making the compiler lookup the file in a specific file structure.

Cowsay can then be used in the build function (aka body) of the State:

body: Center(
  child: Column(
    mainAxisAlignment: MainAxisAlignment.start,
    children: [
      Text(Cowsay.getString('Hello!')), // <==
      const Text(
        'You have pushed the button this many times:',
      ),

And et voilà (again, just ⌘s to save, compile and live-deploy!):

This doesn’t use a monospaced font, and it actually took us quite a while to figure out how to get that. In SwiftUI it would be a simple Font.monospaced:

Text(cows.vaca())
  .font(.body.monospaced())

In Flutter I had to tie that to a specific font:

Text(cowsay.getString('Hello!'), 
     style: TextStyle(fontFamily: "Menlo"))

There is probably a better way.

Multiple Files in your Package

To use multiple files in Swift, you just create them next to each other in the same target folder. There is no need to explicitly import them, which is nice and clean. But presumably not exactly helpful for the compilation speed.

In Dart additional files can also be added in the lib directory, alongside the main.dart. But to use them, they need to be imported. E.g. if you moved the MyApp class to an own my_app.dart file (yes, snakecase is what they do in Dart for filenames):

import 'my_app.dart';
import 'uxkit.dart';

Platform Widgets

When I first played w/ Flutter, I’ve been kinda surprised that we get the Android Material look. Well, not exactly surprised about that. But that there is no simple switch to tell Flutter to render like an iOS app. And it looks like there really is none!

Instead Flutter comes with a set of “Material” widgets, which is what the boilerplate app imports:

import 'package:flutter/material.dart';

and a completely distinct “Cupertino” widget set:

import 'package:flutter/cupertino.dart';

Yes, those are different widgets, with different parameters and layouts. And Material, widgets like ListTile can’t be used as children of say a CupertinoPageScaffold.

To get the iOS look, a different page has to be written:

Widget build(BuildContext context) => CupertinoApp( // <==
  title: "Flutter Demo Home Page",
  home: const MyHomePage(title: 'Flutter Demo Home Page')
);

Widget build(BuildContext context) =>
  CupertinoPageScaffold( // <==
    navigationBar: 
      CupertinoNavigationBar(middle: Text(widget.title)),
    child: ListView(children: [
      Column(children: [
        Text(Cowsay.getString('Hello!'),
        style: const TextStyle(fontFamily: "Menlo")),
        const Text(
          'You have pushed the button this many times:',
        ),
        Text(
          '$_counter',
          style: Theme.of(context).textTheme.headline4,
        )
      ])
    ])
  );

A little crazy isn’t it? Well, maybe not 😎 It actually follows the learn-once-apply-anywhere mantra of SwiftUI. Different platforms need different configurations anyways to look proper.

Also remember that Flutter doesn’t actually use UIKit (like SwiftUI does for many things under the hood)!
Both, the Material and Cupertino sets do all the rendering within Flutter, i.e. they are reimplementations of the UI frameworks. Just due to that they have a different look and feel, get outdated when the main OS goes forward, and simply feel “off” on all platforms.

OK, so do we have to write separate Flutter apps for the different platforms? Not necessarily. There are a few packages abstracting the two widget sets into a common cross platform one.
E.g. Flutter Platform Widgets, which can be added as a dependency and then get imported:

import 'package:flutter_platform_widgets/flutter_platform_widgets.dart';

This contains widgets that switch to either Material or Cupertino, depending on the platform:

Widget build(BuildContext context) => PlatformApp(
  title: "Flutter Demo Home Page",
  home: const MyHomePage(title: 'Flutter Demo Home Page'),
);

Widget build(BuildContext context) =>
  PlatformScaffold(
    appBar: PlatformAppBar(title: Text(widget.title)),
    body: ListView(children: [
      Column(children: [
        Text(Cowsay.getString('Hello!'))
...        

It also has a PlatformWidget that allows for different widgets on each like so:

PlatformWidget(
  cupertino : (_, __) => Text(cow)
  material  : (_, __) => ListTile(title: cow)
)

I’m not really sure what to think about that. That this isn’t the default was a little surprising. In particular because the Cupertino widget set doesn’t actually use UIKit. Presumably everything started out as Material and then people actually tried to use Flutter on iOS.

Because those widget names can get long, I’ve created myself a small UXKit.dart:

import 'package:flutter_platform_widgets/flutter_platform_widgets.dart';

typedef UXApp        = PlatformApp;
typedef UXScaffold   = PlatformScaffold;
typedef UXAppBar     = PlatformAppBar;
typedef UXIcons      = PlatformIcons;
typedef UXIconButton = PlatformIconButton;

(Note that just Scaffold and such often clashes with the Material set, as those have unqualified global names, so a prefix should be used.)

It is also worth noting that SwiftUI does seem to go the way of abstracting (Apple) platform specific things like navigationBarTitle (iOS specific concept) into a more general navigationTitle. So maybe we do get write-once in SwiftUI 🧐

Advanced State Management

State management is a funny topic, because it kinda matches what SwiftUI does here: Not much 🤓 Instead multiple approaches are supported: List of state management approaches (but documentation, again: :chefskiss: here!).

As we’ve seen Flutter itself decouples the State from the StatefulWidget, giving the setup more structure. Where the State object is kinda how SwiftUI people use ObservableObject “ViewModels” or ViewController’s.

Flutter also comes with a concept of a more general observable object, and @EnvironmentObject. The ObservableObject’s are called ChangeNotifier’s in Flutter and look like this:

class CartModel extends ChangeNotifier {

  final List<Item> _items = [];
  int get totalPrice => _items.length * 42; // computed property!

  void add(Item item) {
    _items.add(item);
    notifyListeners();
  }
}

In Swift that would look like:

class CartModel: ObservableObject {
  
  @Published private var items = [ Item ]()
  var totalPrice : Int { items.count * 42 } // yes,yes

  func add(_ item: Item) { items.append(item) }
}

The @Published property wrapper does the change notification magic when the array is modified (it will invoke objectWillChange.send()).

In Dart the notifyListeners method needs to be called explicitly, after the change happened. (Which is funny, because SwiftUI originally started out with didChange but switched to objectWillChange prior the first release.)

The ChangeNotifier is part of Dart/Flutter itself. But even though Flutter carries along the BuildContext, which is kinda like the SwiftUI environment, it doesn’t have an @EnvironmentObject itself. That can be added using the Provider package.

To create and inject an environment object, the ChangeNotifierProvider is used:

class Root extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
    ChangeNotifierProvider(
      create: ( ctx ) => CartModel(),
      child: const HomePage()
    );
  }
}

This is kinda similar to:

struct Root: View {

  @StateObject var cart = CartModel() // autoclosure, also on-demand!

  var body: some View {
    HomePage()
      .environmentObject(cart)
  }
}

To access the model, the Consumer widget is used:

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) => Consumer<CartModel>(
    builder: ( ctx, cart, child ) {
      return Text("Total: ${cart.total}");
    }
  );
}

This will refresh the child widget if the model changes.

In SwiftUI the same would look like:

struct HomePage: View {
  
  @EnvironmentObject var cart : CartModel
  
  var body: some View {
    Text("Total: \(cart.total)")
  }
}

Again SwiftUI gets several extra points for looking nicely, but what is going on is arguably easier to understand in the Flutter setup.

BTW: Not 100% sure, but I think there is also a difference in that Flutter always rebuilds all child widgets on a change. It is complicated, but generally in SwiftUI child Views need to explicitly subscribe to the respective environment/observable objects to get refreshed (either using @EnvironmentObject or @ObservedObject).

Overall similar concepts in SwiftUI and Flutter. Also, both refer to other packages for more complex setups. I recommend ViewController 😬

2022-06-05: SwiftUI 4 (iOS 16+) has a new navigation API that fixes a lot of things. Learn about it over here.

Navigation in SwiftUI is pretty much a buggy mess. There are few topics which get as many complaints.

In SwiftUI navigation is bound to state, which kinda make sense for such a framework. A little example:

struct MainPage: View {

  @State var showDetail = false

  var body: some View {
    NavigationView {
      VStack {
        NavigationLink("Goto detail", isActive: $showDetail) {
          DetailPage()
        }
      }
    }
  }
}
struct DetailPage: View {
  ...
}

To trigger the navigation programmatically, you’d “just” change the state of the showDetail state:

func gotoDetail() {
  showDetail = true
}

And it’ll happen magically. Until it doesn’t anymore. It really is a dispatchy-main-asyncAfter mess.

In Flutter the app’s navigation state isn’t derived from state, but it is explicitly held and pushed to a Navigator object:

UXIconButton(
  icon: Icon(UXIcons(context).book),
  onPressed: () {
    Navigator.of(context)
      .push(platformPageRoute(context: context, 
        builder: (ctx) => DetailPage()
      ));
  }
)

Which is quite similar to what I do in ViewController:

class HomePage: ViewController {
  var view: some View {
    Button("Goto Detail") {
      show(DetailPage())
    }
  }
}

People have mentioned that the current Flutter Navigator may be overly complex. I can’t say much about it, but at least it seems to work reliably, regardless of the situation.

Small Web Service App

As I do, I ended up writing a small Flutter frontend to the Swift Package Index:

It has a TextField, does HTTP and JSON and shows search results in a ListView (did I mention: Flutter documentation 😚).

Important: Don’t use this API in your own apps, get into contact with Sven or Dave if you want to access SPI programmatically.

All the files with small annotations:

main.dart:

import 'package:flutter/widgets.dart';
import 'my_app.dart';

void main() {
  runApp(const MyApp());
}

Moved the app widget to an own file, which gets imported, my_app.dart:

import 'package:flutter/material.dart';
import 'package:hello_flutter/spm_list_page.dart';
import 'uxkit.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) => const UXApp(
    title : 'Welcome to Flutter',
    home  : SPMListPage()
  );
}

Not much magic, SPMListPage is the “ContentView”, spm_list_page.dart:

import 'package:flutter/material.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_platform_widgets/flutter_platform_widgets.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';    // for jsonDecode
import 'uxkit.dart';
import 'spipackage.dart'; // the 'model'

class SPMListPage extends StatefulWidget {
  const SPMListPage({Key? key}) : super(key: key);

  @override
  State<SPMListPage> createState() => _SPMListPageState();
}

class _SPMListPageState extends State<SPMListPage> { 

  late Future<List<SPIPackage>> _packages; // Swift "lazy"
  final _biggerFont  = const TextStyle(fontSize: 28);
  final _searchField = TextEditingController(text: "Dart");
  
  @override
  void initState() { // like onAppear
    super.initState();
    _fetch();
  }
  @override
  void dispose() {
    _searchField.dispose();
    super.dispose();
  }
  
  List<SPIPackage> _decodeJSON(dynamic json) {
    var packages = <SPIPackage>[];
    final jsonDict = json as Map<String, dynamic>;
    final results  = jsonDict["results"] as List<dynamic>;
    
    for (final result in results) {
      final json = result as Map<String, dynamic>;
      
      if (json["package"] == null) continue;
      final nest = json["package"] as Map<String, dynamic>;
      if (nest["_0"] == null) continue; // Coddable, lolz
      final packageJSON = nest["_0"] as Map<String, dynamic>;
      final package = SPIPackage.fromJson(packageJSON);
      packages.add(package);
    }
    return packages;
  }
  
  Future<List<SPIPackage>> _querySPI(String query) async {
    final response = await http.get(
      Uri(scheme: "https",  host: "swiftpackageindex.com",
          path: "/api/search", 
          queryParameters : { "query": query })
    );
    
    if (response.statusCode == 200) {
      return _decodeJSON(jsonDecode(response.body));
    }
    else {// is this attached to the future?
      throw Exception("Failed to run query! ${response.statusCode}");
    }
  }
  
  void _fetch() {
    setState(() {
      _packages = _querySPI(_searchField.text);      
    });
  }

  // MARK: - UI

  Widget _buildCell(BuildContext context, SPIPackage item) {
    return Container(
      margin     : const EdgeInsets.fromLTRB(16, 16, 16, 0),
      padding    : const EdgeInsets.all(8),
      decoration : BoxDecoration(
        border: Border.all(width: 4, color: Colors.black38),
        borderRadius: const BorderRadius.all(Radius.circular(8)),
      ),

      child: Column( // VStack
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(item.packageName ?? item.repositoryName, style: _biggerFont),
          Text("Stars: ${item.stars}")
        ]
      )
    );
  }

  Widget _buildResultList(BuildContext context, List<SPIPackage> packages) {
    return ListView.builder(
      itemCount: packages.length,
      padding: const EdgeInsets.all(0.0),
      itemBuilder: ( ctx, index ) => _buildCell(context, packages[index])
    );
  }

  Widget _buildResultView(BuildContext context) {
    return FutureBuilder<List<SPIPackage>>(
      future: _packages,
      builder: ( ctx, snapshot ) {
        if (snapshot.hasData) {
          return _buildResultList(context, snapshot.data as List<SPIPackage>);
        }
        else if (snapshot.hasError) {
          return Center(child: Text("ERROR: ${snapshot.error}"));
        }
        else {
          return Center(child: PlatformCircularProgressIndicator());
        }
      }
    );
  }

  Widget _buildSearchForm(BuildContext context) {
    return Row(children: [
      Expanded(child: PlatformTextField(controller: _searchField)),
      UXIconButton(icon: Icon(UXIcons(context).search), 
                   onPressed: () => _fetch())
    ]);
  }

  @override
  Widget build(BuildContext context) => UXScaffold(
    appBar            : UXAppBar(title: const Text("SPI")),
    body              : Column(children: [ 
      Padding(padding: const EdgeInsets.fromLTRB(16, 8, 16, 0), child:
        _buildSearchForm(context)
      ),
      Expanded(child: _buildResultView(context)) // expanded is required
    ]),

    iosContentPadding : true
  );
}

I admit, not a beauty, but hey, it is quite OK.

Flutter doesn’t seem to have @Binding’s, so there is the TextEditingController object (a ChangeNotifier!). I don’t actually listen to change events here, but only fetch if the user presses the button.

A point to note is that it is not uncommon to use local methods to construct parts of a UI. Something people do a lot in SwiftUI as well.

The (immutable, all final) “model”, SPIPackage.dart:

class SPIPackage {

  final String  packageId;
  final String  repositoryName;
  final String? packageName;
  final String  packageURL;
  final int     stars;
  final String  summary;

  const SPIPackage({
    required this.packageId,
    required this.repositoryName,
    required this.packageName,
    required this.packageURL,
    required this.stars,
    required this.summary
  });

  factory SPIPackage.fromJson(Map<String, dynamic> json) {
    return SPIPackage(
      packageId      : json['packageId'],
      repositoryName : json['repositoryName'],
      packageName    : json['packageName'],
      packageURL     : json['packageURL'],
      stars          : json['stars'],
      summary        : json['summary']
    );
  }
}

Note the optionals. No idea why the “factory” is a separate concept from the constructor. The dynamic values of json don’t have to be casted explicitly.

That’s it!

Closing Notes

First of all, many thanks go to @pfriedrich_ for helping us to get started w/ Flutter!

Developing in Flutter seems enjoyable from a developer perspective. Hot reload, great documentation, actually working tooling is just excellent.

What I generally dislike is the “looks”. VSCode is as practical as it is ugly. The apps that Flutter produces are ugly (@kiliankoe always asks for a single Flutter app that doesn’t feel crap on iPhone). The source code is ugly if you use actual Flutter conventions (trailing commas everwhere, comments injected on closing braces, …).

But well, the API/language is OK. If I would be forced (💰💰💰💰💰) to produce an Android app, Flutter seems like a decent option (though Kotlin/Jetpack Compose sound interesting as well).
SwiftUI developers will find a lot to like (but risk hating Xcode even more).

While it is always hard to talk about performance without doing decent tests, it feels like SwiftUI has the potential to be dramatically faster (10×?). Given all the static typing, stack allocation, per-view invalidation. But who knows, maybe the Dart compiler can compensate for all that 🙅‍♀️

As usual all feedback is welcome: @helje5 or me@helgehess.eu.

Contact

Feedback is warmly welcome: @helje5, @helge@mastodon.social, me@helgehess.eu. GitHub.

Want to support our work? Buy an app: Past for iChat, SVG Shaper, Shrugs, HMScriptEditor. You don’t have to use it! 😀

Model View Controller for SwiftUI

Fri, 29 Apr 2022 00:00:00 +0200

Overall SwiftUI has been well received after its introduction. However, something most developers stumble upon quickly is how to structure non-trivial applications. One option is to just stick to MVC and get a reasonably clean architecture that isn’t full of hacks.

We decided to stick to the “MVC” terminology Apple came up with for UIKit. As @mpweiher correctly points out, “Apple MVC” isn’t really MVC, but more like MWC. This is what we talk about.

When asked about the architecture to use with SwiftUI (MVC, MVVM, Viper, TCA …), Apple at the WWDC 2021 essentially said: Use whatever you like!
Which, while more guidance would be helpful, actually makes sense. SwiftUI doesn’t force the developer into “MVC” in the same way UIKit did, it provides the primitives to implement very different architectures. Now that we aren’t forced to use MVC anymore, we might start to like it 🤓

This is how we do it:

class HomePage: ViewController {
  
  // MARK: - Actions
  
  func showPreferences() {
    present(Preferences())
  }
  
  // MARK: - View
  
  var view : some View {
    Button(action: self.showPreferences) {
      Label("Preferences", systemImage: "gear")
    }
  }
}

ViewControllers are like freaking zombies. Just won’t die, no matter how many times you shoot it […], or douse it in gasoline and light it on fire, or anything.

I think that SwiftUI is just another iteration of WebObjects. And hence structure SwiftUI apps in a similar way we used to. After bringing a few SwiftUI applications to the AppStore, that turned out to work really well for us.

No package/framework is needed at all to implement this! Though we will present a small one to assist the approach: called ViewController, a set of conveniences and “Ah, that I understand” stuff.

Direct access:

The Problem
A Solution: Model View Controller
Optional Micro Framework: ViewController

News 2022-06-05: SwiftUI 4 (iOS 16+) has a new navigation API that fixes a lot of things. Learn about it over here. Looks like that will make SwiftUI navigation much more reliable. Not quite sure yet how I’m going to fit it into ViewController. The new approach fixes some things. But it isn’t a “presentation stack” either, i.e. it only addresses navigation (not sheets etc). We’ll see.

The Problem

Simple things are astonishingly simple to create in SwiftUI. But as soon as even trivial things like a master-detail setups come into play, developers seem to forget clean architectures they practiced for years. Instead come up with a mess of View’s carrying state around, duplicating data, hack-patching and breaking encapsulation on the way.

Something that can be seen a lot is a setup like this (cows module over here):

import SwiftUI
import cows // @AlwaysRightInstitute

struct ContentView: View {
  var body: some View {
    NavigationView {
      CowsOverview()
    }
  }
}

struct CowsOverview: View {

  @StateObject private var viewModel = CowsViewModel()

  var body: some View {
    List(viewModel.cows, id: \.self) { cow in
      Text(verbatim: cow)
        .font(.body.monospaced())
    }
    .searchable(text: $viewModel.search)
    .navigationTitle("Cows Overview")
  }
}

class CowsViewModel: ObservableObject {
  
  @Published var cows   = allCows
  @Published var search = "" {
    didSet { 
      cows = allCows.filter { search.isEmpty || $0.contains(search) } 
    }
  }
}

Reasonably clean, the logic is pulled out of the View to not end up with a Massive View and to make it testable. Looks like this:

Talking about “ViewModels”. This seems to be very common terminology for this thing in the SwiftUI world. We are not entirely sure why, those things seem quite different to ViewModels when doing MVVM in UIKit.
We call them ViewController’s, because that is what they do, they control the view holding a reference to them. Everyone is welcome to replace “ViewController” with “ViewModel” when reading this article.

Master Detail

Things start to get interesting (and problematic) when some kind of “navigation” is added to the application, e.g. showing a certain detail view when selecting a cow (could also be in a sheet or NavigationView, we use an inline presentation for the example).

WARNING: Incorrect Code: What people often try first:

struct CowDetail: View {

  @ObservedObject var viewModel : CowDetailViewModel

  init(cow: String) { // ugh ugly
    _viewModel = ObservedObject(wrappedValue: CowDetailViewModel(cow: cow))
  }

  var body: some View {
    Text(verbatim: viewModel.cow)
      .font(.body.monospaced())
      .navigationTitle("Cow Detail")
  }
}
class CowDetailViewModel: ObservableObject {
  
  @Published var cow = ""
  init(cow: String) { self.cow = cow }
}

And tracking the selection in the CowsOverview:

struct CowsOverview: View {

  @StateObject private var viewModel = CowsViewModel()

  var body: some View {
    VStack {
      if let cow = viewModel.selectedCow {
        CowDetail(cow: cow)
        Text("Selection")
          .font(.footnote)
        Divider()
      }
      
      List(viewModel.cows, id: \.self) { cow in
        Button(action: { viewModel.selectedCow = cow }) {
          Text(verbatim: cow)
            .font(.body.monospaced())
        }
      }
    }
    .searchable(text: $viewModel.search)
    .navigationTitle("Cows Overview")
  }
}

class CowsViewModel: ObservableObject {
  
  @Published var search = "" {
    didSet { cows = allCows.filter { search.isEmpty || $0.contains(search) } }
  }
  @Published var cows = allCows
  
  @Published var selectedCow : String?
}

WARNING: Incorrect Code.

Strange things will happen, it has at least two issues:

@ObservedObject doesn’t “own” the object, so it might actually go away (because the parent also doesn’t hold a reference to it, it is View-local, but only has storage for the OO’s Publisher assigned).
A new instance of the CowDetailViewModel is created everytime the body of the parent view refreshes. (This very often results in confusion. Remember that a View’s body can be evaluated arbitrary number of times as the framework sees fit.)

Using a @StateObject addresses parts of the issue:

struct CowDetail: View {
  @StateObject var viewModel : CowDetailViewModel
  init(cow: String) { // ugh ugly
    _viewModel = .init(wrappedValue: CowDetailViewModel(cow: cow))
  }

Slightly better. This will make sure that the CowDetail View (i.e. someone) is actually going to own the associated ViewModel.
But now a funny thing happens when another cow is selected: Nothing happens in the UI, the selection sticks to the first selected cow.

Click another cow, the displayed selection won’t ever change anymore. Why is that, the selectedCow in the parent ViewModel is properly updating, the CowDetail is re-initialized?
The reason is that for a StateObject the wrappedValue closure only runs once, if the state is first initialized. All subsequent calls to init will just drop the input on the floor.

Often people do a hodgepodge of different hacks to address that, but let’s look at a common one:

struct CowDetail: View {

  @StateObject var viewModel : CowDetailViewModel
  
  let cow : String
  
  init(cow: String) {
    self.cow = cow
    _viewModel = .init(wrappedValue: CowDetailViewModel(cow: cow))
  }

  var body: some View {
    Text(verbatim: viewModel.cow)
      .font(.body.monospaced())
      .navigationTitle("Cow Detail")
      .onChange(of: cow) { newCow in viewModel.cow = newCow }
  }
}

That actually works.

Introduces a copy of the cow as an instance variable in the View itself.
If the View is refreshed, the value of cow will update using the init (the VM closure will still get created and dropped w/o being used).
And if the View’s cow ivar changed, the new value is (manually) pushed into the “ViewModel”

But, jeez, is that stuff ugly! Overriding View init’s, creating a property wrapper copy and push it into the state (capturing a closure each time!), duplicating all input in instance variables for API purposes, manual tracking of arbitrary values (imagine the VM has more than one property), …
Something is clearly going wrong here, there has to be a better way!

There are other hacks around this, and different ones for different situations (e.g. using onAppear), but they all one thing in common: they are just that, ugly hacks.

A Solution: Model View Controller

A solution is nothing fancy or complicated, but just sticking to what was best practice in UIKit already: keep state out of View’s.

Instead of having the View’s own the ViewModels, a ViewController (again, feel free to call them ViewModels) hierarchy is formed. It is just “drawn” by the View’s. The View’s sole two purposes: rendering and event handling.

Let’s see what we mean using our cows example app. Again, this doesn’t require any library or framework and all apps we deploy today just use the concept, not even ViewController (yet).

class CowDetail: ObservableObject {

  @Published var cow = ""
  
  init(cow: String) { self.cow = cow }
  
  struct ContentView: View {
    
    @ObservedObject var viewController : CowDetail
    
    var body: some View {
      Text(verbatim: viewController.cow)
        .font(.body.monospaced())
        .navigationTitle("Cow Detail")
    }
  }
}

It is almost the same like the “problematic approach” shown above, just the “other way around”. Solving a ton of problems and requiring zero SwiftUI hack-a-rounds.

The CowDetail is now an ObservableObject representing that section of the screen, a “ViewController”.
Things you’d put into View @State before, become @Published properties of the controller. Because no state belongs into Views.
The sample contains the ContentView as a subtype of the CowDetail controller. That’s fine for simple setups, in real apps it isn’t unusual to put them into separate files that are concerned only about a specific representation (e.g. like Storyboards before). There can be multiple “ContentViews”, e.g. for different themes, device sizes or types.
The associated View is receiving its controller as an @ObservedObject. This is fine in this case, because the ViewController hierarchy now explictly owns the chained controllers:

class CowsOverview: ObservableObject {

  @Published var search = "" {
    didSet { cows = allCows.filter { search.isEmpty || $0.contains(search) } }
  }
  @Published var cows = allCows
  
  @Published var detailViewController : CowDetail?
  
  // MARK: - Actions
  
  func showDetail(_ cow: String) {
    detailViewController = CowDetail(cow: cow)
  }
  
  // MARK: - View

  struct ContentView: View {
    
    @ObservedObject var viewController : CowsOverview
    
    var body: some View {
      VStack {
        if let presentedViewController = viewController.detailViewController {
          CowDetail.ContentView(viewController: presentedViewController)
          Text("Selection")
            .font(.footnote)
          Divider()
        }
        
        List(viewController.cows, id: \.self) { cow in
          Button(action: { viewController.showDetail(cow) }) {
            Text(verbatim: cow)
              .font(.body.monospaced())
          }
        }
      }
      .searchable(text: $viewController.search)
      .navigationTitle("Cows Overview")
    }
  }
}

Notice how the CowsOverview is now owning the CowDetail. Very similar to how a presentingViewController is owning the presentedViewController in UIKit.

This call initiates the presentation:

func showDetail(_ cow: String) {
  // like `self.present(CowDetail(cow: cow))` in UIKit
  detailViewController = CowDetail(cow: cow)
}

Just sticking to this pattern produces reasonably clean SwiftUI application. It takes out the uglyness of the “problematic solution” where Views and state intermingle:

Views can use @ObservedObject, because it is clear who owns the associated object (ViewController).
There is no capturing of unused state initializers anymore.
A single source of truth, no duplicated state in Views, no watching and synchronization of local values.
No ugly _ propery wrapper inits anymore (would be nice to have synthesized class inits in Swift though).

As in UIKit additional concepts can be added around this basic one (which deals primarily with “app navigation state”). E.g. one could create view model structs to represent the state, or use Coordinators to decide on the actual presentation flow (i.e. what ViewControllers are going to be presented when).

There is one minor thing missing. The “Root ViewController” needs to be setup. That is the sole place where we still use a @StateObject:

struct ContentView: View {
  
  @StateObject var sceneViewController = CowsOverview()
  
  var body: some View {
    NavigationView {
      CowsOverview.ContentView(viewController: sceneViewController)
    }
  }
}

We tend to call that ContentView in the main SwiftUI application the “Scene View”. Each scene should have an own root, as the user might navigate differently through each one.

ViewController

Using the general approach shown is usually fine for most apps. But sometimes there are a lot of pages with many different presentations, navigation, sheets, etc. So we came up with ViewController, a reasonably small library formalizing the concept a little. It can be added as a Swift package to an Xcode project:

Package URL: https://github.com/ZeeZide/ViewController.git

The main thing it adds is the ViewController protocol, which is derived from ObservableObject. The VC variant of the CowDetail component:

import ViewController

class CowDetail: ViewController {

  @Published var cow : String
  
  init(cow: String) { self.cow = cow }

  var view: some View {
    Text(verbatim: cow)
      .font(.body.monospaced())
      .navigationTitle("Cow Detail")
  }
}

Pretty similar to a SwiftUI View, but with an important distinction: It has a proper object identity and can track (and own!) the presentation of other ViewController’s.

The library supports both, directly embedding the associated View construction as shown above or using an own ContentView type. The latter either inline or as a separate top-level type.
CowsOverview with an explicit ContentView:

class CowsOverview: ViewController {

  @Published var search = "" {
    didSet { cows = allCows.filter { search.isEmpty || $0.contains(search) } }
  }
  @Published var cows = allCows

  // MARK: - Actions

  func showDetail(_ cow: String) {
    present(CowDetail(cow: cow))
  }
  
  // MARK: - View

  struct ContentView: View {
    
    @EnvironmentObject var viewController : CowsOverview
    
    var body: some View {
      VStack {
        List(viewController.cows, id: \.self) { cow in
          Button(action: { viewController.showDetail(cow) }) {
            Text(verbatim: cow)
              .font(.body.monospaced())
          }
        }
      }
      .searchable(text: $viewController.search)
      .navigationTitle("Cows Overview")
    }
  }
}

The active ViewController can be acquired using the SwiftUI environment, using either its concrete type, or the AnyViewController type-erased version.
This makes splitting up the ContentView into specific subviews easy and straight forward.

Note how the showDetail action is calling .present. This will push the detail to the ViewController stack and present the cow in a sheet. No manual tracking of the presented ViewController is necessary anymore (though it still can be done if desirable).
The framework is keeping track of the presentation stack, and makes it accessible using the old school presentingViewController and presentedViewController accessors.

There is one final piece to get things going, the root sceneViewController needs to be setup. There are two ways to do it, the plain version:

struct ContentView: View {
  
  @StateObject var sceneViewController = CowsOverview()
  
  var body: some View {
    NavigationView {
      sceneViewController.view // Or: CowsOverview.ContentView()
        .controlled(by: sceneViewController) // activate
    }
  }
}

Or using a small helper View which does the same, MainViewController:

struct ContentView: View {
  
  var body: some View {
    NavigationView {
      MainViewController(CowsOverview())
    }
  }
}

We think that this looks quite pretty!

NavigationController

Calling present (in auto mode) is always going to present a ViewController in a sheet. ViewController also provides show (and technically showDetail, though the SplitViewController is not finished yet).

When using show the presentation can adapt to the container view it is in (i.e. the container view gets a chance to decide on the presentation).
If a NavigationController is used, show will result in a navigation transition, instead of a sheet. How a ViewController is presented is transparent to it (the current mode can be queried from the environment).

To wrap up, this is how an automatic show version looks like:

struct ContentView: View {
  
  var body: some View {
    MainViewController(
      NavigationController(rootViewController: CowsOverview())
    )
  }
}

And instead of present the action should use show:

func showDetail(_ cow: String) {
  show(CowDetail(cow: cow))
}

In case you wonder, this also works:

func showDetail(_ cow: String) {
  let detail = CowDetail(cow: cow)
  detail.modalPresentationStyle = .navigation // .sheet, .custom, …
  present(detail)
}

Notes

The approach also solves issues people have with onAppear, when it fires and how it fires. Because navigation / component activation is explicitly encoded in the view controller presentation stack (instead of being a side effect).
Massive View Controller can still become a thing, same measures as with UIKit apply. Use ViewController containment and the likes (ViewController does support child controllers).
This doesn’t fix programmatic SwiftUI navigation (aka “deep linking”), which still happens to be a buggy mess in SwiftUI. There are hacks around it, but nothing really reasonable.
ViewController features support for representedObject, i.e. associating another, usually “model”, object with the VC (also along the lines of MWC). Often helpful (e.g. the datasource of contacts being listed, or the individual contact being shown).
Along those lines, since the ViewController is often the main redraw driver for a View, it has a willChange(with:) hook, to republish changes in other objects, e.g. models.
Flutter also seems to do explicit navigation, i.e. “push a route”, instead of deriving the navigation position from state.

Closing Notes

We meant to write about this, and formalize it in a small package, for quite a while (by now years, actually 🙈). The presented solution is used in various of our apps in the AppStore.
ViewController isn’t deployed yet, but was created for a more complex application w/ multiple, stacked presentations going on. We quite like it.

As usual all feedback is welcome. Tell us why you hate it and why this is wrong!
@helje5 or me@helgehess.eu.

Contact

Feedback is warmly welcome: @helje5, @helge@mastodon.social, me@helgehess.eu. GitHub.

Want to support our work? Buy an app: Past for iChat, SVG Shaper, Shrugs, HMScriptEditor. You don’t have to use it! 😀

🐮 iOS App w/ VisualStudio Code. Or not?

Wed, 29 Dec 2021 00:00:00 +0100

In SwiftUI Tools w/ VisualStudio Code we explored how to use
VisualStudio Code to build macOS apps using the new Swift extension. But can we also build an iOS application using that?

This is an updated version of SwiftUI Tools w/ VisualStudio Code using the new Swift support for Visual Studio Code, which is an updated version of SwiftUI Tools w/ just SwiftPM.

It is well known that building iOS apps doesn’t work using Swift Package Manager only, or is it? In a (very inconvenient) way it now is!

Apple recently introduced the new Swift Playgrounds 4 which features the new ability to build “real” iOS applications. Guess what? This is using a Swift package under the hood. Aaron Sky revisted the mechanism early on and blogged about it over here: Swift Playgrounds App Projects.

In short, Xcode 13.2 adds a new iOSApplication product to the builtin SPM, it looks like this:

import PackageDescription
import AppleProductTypes

let package = Package(
    name: "Tows",
    platforms: [ .iOS("15.2") ],
    products: [
        .iOSApplication(
            name: "Tows",
            targets: ["AppModule"],
            displayVersion: "1.0",
            bundleVersion: "1",
            supportedDeviceFamilies: [ .pad, .phone ],
            supportedInterfaceOrientations: [ .portrait ],
            capabilities: []
        )
    ],
    targets: [ .executableTarget(name: "AppModule", path: ".") ]
)

Let’s see whether can get our Hello World SwiftUI going from within VSCode:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

Installing VisualStudio Code w/ Swift

This is really easy, download VisualStudio Code from Microsofts Download Page, and drag it to the /Applications folder.

One may also want to link up the code tool, so that VSC can be started from the shell:

$ ln -s "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" \
        /usr/local/bin/code

On startup, VSCode is going to show a little tutorial, though most things are self explanatory. The basics:

They call the dock on the left the “activity bar”. It is roughly comparable to the sidebar tab selector in Xcode. Relevant shortcuts:
- ⌘⇧ E: Jump into the “Explorer” (the file navigation pane) and if the focus is on the Explorer, back to the editor (thanks @pfriedrich_).
- ⌘⇧ F: Open search pane.
- ⌘⇧ D: Run & Debug pane (also seems to be used for tests).
- ^⇧ G: Git pane.
A terminal can be brought up using Ctrl-Backtick (similar to M-x shell)
More shortcuts:
- Navigate forward/backward: ⌘⌥ < / ⌘⌥ >
- F5: Start in debugger, ^ F5: just run
- F12: Jump to definition of a symbol
- ⌘⇧ N: Open a new VSCode window
- ⌘⇧ P: Open “command palette”, this is similar to M-x in Emacs, one can invoke all the available functions.
Usually you seem to open just one “folder” in a VSCode window (similar to Xcode), which is your project root (though you can also create workspaces, again similar to Xcode).

Afterwards one can install the “Swift Language Support for Visual Studio Code” extension using the extensions button in the activity bar. Search for “Swift”, should be the top hit:

So far so gut, the ARI ran into no issues.

Setting up the App Package and Build

The new Swift extension for VisualStudio Code doesn’t yet support creating new Swift projects. So that part still has to be done in the shell.

First make sure that you have Xcode 13.2 installed and that Swift 5.5 is active:

$ swift --version
swift-driver version: 1.26.21 Apple Swift version 5.5.2 (swiftlang-1300.0.47.5 clang-1300.0.29.30)
Target: arm64-apple-macosx11.0

If it is not: sudo xcode-select -s /Applications/Xcode.app.

Next create the package boilerplate:

$ mkdir Tows && cd Tows
$ swift package init --type executable
Creating executable package: Tows
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/Tows/main.swift
Creating Tests/
Creating Tests/TowsTests/
Creating Tests/TowsTests/TowsTests.swift

This needs to be massaged a little more. First we need to rename the main.swift to something else. main.swift is a special file which essentially wraps the whole content in a big function (i.e. you can run statements like print("Moo!") at the top level). This clashes with how @main works.

$ mv Sources/Tows/main.swift \
     Sources/Tows/Tows.swift

This can be opened in VisualStudio Code now, to do so, just type:

$ code .

It should come up like this:

Replace the contents (the print("Hello")) with our app as shown above:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

VSCode is going to show a set of errors:

Next we need to adjust the Package.swift to build an iOS product:

// swift-tools-version:5.5

import PackageDescription
import AppleProductTypes

let package = Package(
    name: "Tows",
    platforms: [ .iOS("15.2") ],
    products: [
        .iOSApplication(
            name: "Tows",
            targets: ["Tows"],
            displayVersion: "1.0",
            bundleVersion: "1",
            supportedDeviceFamilies: [
                .pad,
                .phone
            ],
            supportedInterfaceOrientations: [
                .portrait,
                .landscapeRight,
                .landscapeLeft,
                .portraitUpsideDown(.when(deviceFamilies: [.pad]))
            ],
            capabilities: []
        )
    ],
    dependencies: [],
    targets: [
        .executableTarget(
            name: "Tows",
            dependencies: []),
        .testTarget(
            name: "TowsTests",
            dependencies: ["Tows"]),
    ]
)

This is going to show an error that the AppleProductTypes (which contains the iOSApplication product) is not available:

Why is this? It is because the SwiftPM one can invoke in Terminal (e.g. using swift build) is different (🙄) to the SwiftPM built into Xcode! Not sure anything can be done about, maybe? We’ll ignore the error for now.

The other thing is that Tows.swift still says that macOS BS is required. Looks like the Swift extension still has a bug w/ refreshing things when the platform changes. This can be worked around by renaming the Tows.swift file to Tows2.swift (just click on the filename in the explorer), and et voilà, the source looks proper now:

The answer is kinda obvious, but can we run the app in the simulator by pressing F5? Unfortunately not:

OK, but VSCode let’s us “configure” the swift build “task” (we intentionally didn’t reindent the generated JSON to visualize how wrong it is to used tabs for formatting …):

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "swift",
			"command": "swift",
			"args": [
				"build",
				"--build-tests"
			],
			"group": "build",
			"problemMatcher": [],
			"label": "swift: Build All",
			"detail": "swift build --build-tests"
		}
	]
}

We know we can’t use the Terminal SwiftPM. But we can invoke the Xcode SwiftPM by the means of the xcodebuild tool. Let’s try that:

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "swift",
			"command": "xcodebuild",
			"args": [
				"-scheme",
        "Tows",
        "-destination",
        "platform=iOS Simulator,OS=15.2,name=iPhone 13 Pro"
			],
			"group": "build",
			"problemMatcher": [],
			"label": "swift: Build All",
			"detail": "xcodebuild"
		}
	]
}

Doesn’t help when pressing F5. Unfortunatly ARI’s VSCode skillz are too weak on how to invoke such a task. But presumably, by reconfiguring all those, one could get it running automagically?

But we can invoke the shell using Ctrl-Backtick and run the build within that:

$ xcodebuild -scheme Tows \
  -destination 'platform=iOS Simulator,OS=15.2,name=iPhone 13 Pro'

This prints out a lot of errors we love to ignore, but fails with:

xcodebuild: error: Unable to find a destination matching the provided destination specifier:
                { platform:iOS Simulator, OS:15.2, name:iPhone 13 Pro }

and suggests only macOS destinations:

Available destinations for the "Tows" scheme:
        { platform:macOS, arch:arm64, id:00008103-000E618A3662001E }
...

Very weird. The setup is almost identical to what Swift Playgrounds produce 🧐 But there is one difference to those, the extension of the package folder is .swiftpm 💡

$ cd .. && mv Tows Tows.swiftpm && cd Tows.swiftpm && code .

And then within the VSCode terminal (Ctrl-Backtick):

$ xcodebuild -scheme Tows \
  -destination 'platform=iOS Simulator,OS=15.2,name=iPhone 13 Pro'

Nice! 🍻 Inconvenient, but works. It built and put the Tows.app into the DerivedData folder configured in Xcode.

Running the App in the Simulator

But how do we run that app? Using a small tool called simctl. First we need to figure out the ID of the simulator we want to use:

$ xcrun simctl list devices "iPhone 13 Pro" available | grep iPhone
    iPhone 13 Pro (9932C857-414E-4D9A-90DB-4E64A0B72B83) (Shutdown) 
    iPhone 13 Pro Max (759D3A4B-248E-4BC5-98C0-5CDABEC5E606) (Shutdown) 

Note how it says the simulator is “Shutdown”. We need to start it:

$ alias sim=/Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator
$ export ID=9932C857-414E-4D9A-90DB-4E64A0B72B83
$ sim -CurrentDeviceUDID $ID >/dev/null &

Then we can install our app:

$ alias sc="xcrun simctl"
$ sc install $ID \
  /tmp/DerivedData/Tows-bsyramamusgwwvgucsqrnwzhfvyb/Build/Products/Debug-iphonesimulator/Tows.app

And launch it:

$ sc launch $ID Tows

Splendid! 🍻🍻 Very manual, but works.

But can we write more complex apps with that? Something cowtastic? Yes we can!

          (__)
        /  .\/.     ______
       |  /\_|     |      \
       |  |___     |       |
       |   ---@    |_______|
    *  |  |   ----   |    |
     \ |  |_____
      \|________|
CompuCow Discovers Bug in Compiler

🐮 A Cowtastic App 🐮

This thing, as a SwiftPM tool, in 82 lines of code (including support for search, selection and dragging):

We are going to use the Swift cows package, let’s add it as a dependency to Package.swift (remember to add both, the package and the target dependency):

// swift-tools-version:5.5

import PackageDescription
import AppleProductTypes

let package = Package(
    name: "Tows",
    platforms: [ .iOS("15.2") ],
    products: [
        .iOSApplication(
            name: "Tows",
            targets: ["Tows"],
            displayVersion: "1.0",
            bundleVersion: "1",
            supportedDeviceFamilies: [
                .pad,
                .phone
            ],
            supportedInterfaceOrientations: [
                .portrait,
                .landscapeRight,
                .landscapeLeft,
                .portraitUpsideDown(.when(deviceFamilies: [.pad]))
            ],
            capabilities: []
        )
    ],
    dependencies: [ // Add this!
        .package(url: "https://github.com/AlwaysRightInstitute/cows",
                 from: "1.0.10")
    ],
    targets: [
        .executableTarget(
            name: "Tows",
            dependencies: [ "cows" ]) // Add this!
    ]
)

Since the Swift VSCode extension can’t properly run the Xcode SPM, the new “Package Dependencies” section will NOT pop up in the sidebar 😢

Let’s update the application code (Tows2.swift):

import SwiftUI
import cows // @AlwaysRightInstitute

struct ContentView: View {
  
  @State var searchString  = ""
  @State var matches       = allCows
  @State var selectedCow   : String?
    
  var body: some View {
    VStack {
      TextField("Search", text: $searchString)
        .textFieldStyle(RoundedBorderTextFieldStyle())
        .padding(8)
        .onChange(of: searchString) { nv in
          matches = nv.isEmpty
                  ? cows.allCows
                  : cows.allCows.filter { $0.contains(searchString) }
        }
      
      Divider()
      
      VStack(spacing: 0) {
        if matches.isEmpty {
          Text("Didn't find cows matching '\(searchString)' 🐮")
            .padding()
            .font(.title)
          Divider()
        }
        
        ScrollView {
          ForEach(matches.isEmpty ? allCows : matches, id: \.self) { cow in
            Text(verbatim: cow)
              .font(.body.monospaced())
              .onDrag { NSItemProvider(object: cow as NSString ) }
              .padding()
              .background(
                RoundedRectangle(cornerRadius: 16)
                  .strokeBorder()
                  .foregroundColor(.accentColor)
                  .padding(4)
                  .opacity(selectedCow == cow ? 1 : 0)
              )
              .frame(maxWidth: .infinity)
              .contentShape(Rectangle())
              .onTapGesture {
                selectedCow = selectedCow == cow ? nil : cow
              }
          }
        }
      }
    }
  }
}

@main
struct Tows: App {
  
  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}

And back to our manual cycle:

compile
install
run

$ xcodebuild -scheme Tows \
  -destination 'platform=iOS Simulator,OS=15.2,name=iPhone 13 Pro'
$ sc install $ID \
  /tmp/DerivedData/Tows-bsyramamusgwwvgucsqrnwzhfvyb/Build/Products/Debug-iphonesimulator/Tows.app
$ sc launch $ID Tows

Cowtastic! 🍻🍻🍻

Closing Notes

So can you develop iOS apps w/o opening Xcode and with just SwiftPM? Yes, you can.
Do you want to? Probably not, too much manual work to get going.

Though we think for some VSCode wizard it might actually be possible to just tweak the tasks to do the right things and get F5 working? Let us know if you know how!

The Swift for Visual Studio Code extension is still pretty nice and a good starting point. It has some limitations, but Adam Fowler and Steven Van Impe did a great job.

Want to have a readymade 🐮 app that is properly reviewed by Apple’s AppStore team?

There is CodeCows. Which (amongst other things) features a (language aware) Xcode extension (yes!) and support for macOS services (i.e. automatic ASCII Cows support in any Cocoa text field).

And for iOS there is ASCII Cows. Includes a Messages app and proper Markdown support, so that you can paste the cows into WhatsApp properly.

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu. GitHub.

Want to support my work? Buy an app! You don’t have to use it! 😀

🐮 SwiftUI Tools w/ VisualStudio Code

Tue, 28 Dec 2021 00:00:00 +0100

The Swift Package Manager coming with Swift 5.5 now supports the @main attribute. We can use that to build apps using just VisualStudio Code and SwiftPM, no Xcode involved! Let’s use it to build a Cowtastic app!

This is an updated version of SwiftUI Tools w/ just SwiftPM using the new Swift support for Visual Studio Code.

The @main attribute was actually introduced in earlier, but starting w/ Swift 5.5 it is now also supported in Swift Package Manager. (ObjC.io also has a nice pre-@main article about this, requiring more boilerplate.)

This is what is possible now, w/o having to use Xcode:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

Produces this little thing when it is run:

Installing VisualStudio Code w/ Swift

This is really easy, download VisualStudio Code from Microsofts Download Page, and drag it to the /Applications folder.

One may also want to link up the code tool, so that VSC can be started from the shell:

$ ln -s "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" \
        /usr/local/bin/code

On startup, VSCode is going to show a little tutorial, though most things are self explanatory. The basics:

They call the dock on the left the “activity bar”. It is roughly comparable to the sidebar tab selector in Xcode. Relevant shortcuts:
- ⌘⇧ E: Jump into the “Explorer” (the file navigation pane) and if the focus is on the Explorer, back to the editor (thanks @pfriedrich_).
- ⌘⇧ F: Open search pane.
- ⌘⇧ D: Run & Debug pane (also seems to be used for tests).
- ^⇧ G: Git pane.
A terminal can be brought up using Ctrl-Backtick (similar to M-x shell)
More shortcuts:
- Navigate forward/backward: ⌘⌥ < / ⌘⌥ >
- F5: Start in debugger, ^ F5: just run
- F12: Jump to definition of a symbol
- ⌘⇧ N: Open a new VSCode window
- ⌘⇧ P: Open “command palette”, this is similar to M-x in Emacs, one can invoke all the available functions.
- ⌘⌥ ^: Up/down for multiple cursors (multiline edits).
Usually you seem to open just one “folder” in a VSCode window (similar to Xcode), which is your project root (though you can also create workspaces, again similar to Xcode).

Afterwards one can install the “Swift Language Support for Visual Studio Code” extension using the extensions button in the activity bar. Search for “Swift”, should be the top hit:

So far so gut, the ARI ran into no issues.

Setting up the SwiftPM Boilerplate

The new Swift extension for VisualStudio Code doesn’t yet support creating new Swift projects. So that part still has to be done in the shell.

First make sure that Swift 5.5 is active:

$ swift --version
swift-driver version: 1.26.21 Apple Swift version 5.5.2 (swiftlang-1300.0.47.5 clang-1300.0.29.30)
Target: arm64-apple-macosx11.0

If it is not: sudo xcode-select -s /Applications/Xcode.app.

Next create the package boilerplate:

$ mkdir Tows && cd Tows
$ swift package init --type executable
Creating executable package: Tows
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/Tows/main.swift
Creating Tests/
Creating Tests/TowsTests/
Creating Tests/TowsTests/TowsTests.swift

$ mv Sources/Tows/main.swift \
     Sources/Tows/Tows.swift

This can be opened in VisualStudio Code now, to do so, just type:

$ code .

It should come up like this:

Replace the contents (the print("Hello")) with our app as shown above:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

VSCode is going to show a set of errors:

Oops. That says at least macOS BS is required. Easily fixed by adding that requirement to our Package.swift file:

// swift-tools-version:5.5
import PackageDescription

let package = Package(
  name: "Tows",
  platforms: [ .macOS(.v11) ], // <= add this!
  dependencies: [],
  targets: [ .executableTarget(name: "Tows", dependencies: []) ]
)

And … errors still show. Looks like the Swift extension still has a bug w/ refreshing things when the platform changes. This can be worked around by renaming the Tows.swift file to Tows2.swift (just click on the filename in the explorer), and et voilà, the source looks proper now:

Excellent, let’s start our app in the debugger by pressing F5, it just works. Magic:

Notice the little “Hello World” window, that’s the app:

You may have to search for the window, it is not put in front of your other windows.

IMPORTANT: This is not quite a full app yet. You’ll notice it has no menu bar and if you quit it, you’ll quit your editor instead 😈 To close it, you need stop it in the VSCode debugger.

Fixing the App Activation

To make the thing behave like an app proper, a Cocoa with Love trick from 2010 has to be applied. We are going to add an init to our App structure:

@main
struct HelloWorld: App {
  
  init() {
    DispatchQueue.main.async {
      NSApp.setActivationPolicy(.regular)
      NSApp.activate(ignoringOtherApps: true)
      NSApp.windows.first?.makeKeyAndOrderFront(nil)
    }    
  }
  ...
}

Re-run the tool by pressing F5 again, it’ll have a menu proper and it can be quit as usual.

We are done. That is all which is required. But can we write more complex apps with that? Something cowtastic? Yes we can!

          (__)
        /  .\/.     ______
       |  /\_|     |      \
       |  |___     |       |
       |   ---@    |_______|
    *  |  |   ----   |    |
     \ |  |_____
      \|________|
CompuCow Discovers Bug in Compiler

🐮 A Cowtastic App 🐮

This thing, as a SwiftPM tool, in 82 lines of code (including support for search, selection and dragging):

We are going to use the Swift cows package, let’s add it as a dependency to Package.swift (remember to add both, the package and the target dependency):

// swift-tools-version:5.5
import PackageDescription

let package = Package(
  name: "Tows",
  platforms: [ .macOS(.v11) ],
  dependencies: [ // add this:
    .package(url: "https://github.com/AlwaysRightInstitute/cows",
             from: "1.0.10")
  ],
  targets: [ 
    .executableTarget(name: "Tows", 
                      dependencies: [ "cows" ]) // <= add this!
  ]
)

After doing this, a new “Package Dependencies” section will pop up in the sidebar:

Let’s update the application code. Gist: Tows.swift

import SwiftUI
import cows // @AlwaysRightInstitute

struct ContentView: View {
  
  @State var searchString  = ""
  @State var matches       = allCows
  @State var selectedCow   : String?
  
  let font = Font(NSFont
    .monospacedSystemFont(ofSize: NSFont.systemFontSize, weight: .regular))
  
  var body: some View {
    NavigationView {
      ScrollView {
        TextField("Search", text: $searchString)
          .textFieldStyle(RoundedBorderTextFieldStyle())
          .padding(8)
          .onChange(of: searchString) { nv in
            matches = nv.isEmpty 
                    ? cows.allCows 
                    : cows.allCows.filter { $0.contains(searchString) }
          }
        Spacer()
      }
      
      ScrollView {
        VStack(spacing: 0) {
          if matches.isEmpty {
            Text("Didn't find cows matching '\(searchString)' 🐮")
              .padding()
              .font(.title)
            Divider()
          }
          
          ForEach(matches.isEmpty ? allCows : matches, id: \.self) { cow in
            Text(verbatim: cow)
              .font(font)
              .onDrag { NSItemProvider(object: cow as NSString ) }
              .padding()
              .background(
                RoundedRectangle(cornerRadius: 16)
                  .strokeBorder()
                  .foregroundColor(.accentColor)
                  .padding(4)
                  .opacity(selectedCow == cow ? 1 : 0)
              )
              .frame(maxWidth: .infinity)
              .contentShape(Rectangle())
              .onTapGesture {
                selectedCow = selectedCow == cow ? nil : cow
              }
          }
        }
      }
      .ignoresSafeArea()
    }
  }
}

@main
struct Tows: App {
  
  init() {
    DispatchQueue.main.async {
      NSApp.setActivationPolicy(.regular)
      NSApp.activate(ignoringOtherApps: true)
      NSApp.windows.first?.makeKeyAndOrderFront(nil)
    }
  }
  
  var body: some Scene {
    WindowGroup {
      ContentView()
        .frame(minWidth: 640, minHeight: 320)
    }
    .windowStyle(HiddenTitleBarWindowStyle())
  }
}

Just press F5 and a Cowtastic app is being started:

Closing Notes

Looks like a pretty nice Swift for Visual Studio Code extension. It still has some limitations, but Adam Fowler and Steven Van Impe did a great job.

Want to have a readymade app that is properly reviewed by Apple’s AppStore team?

There is CodeCows. Which (amongst other things) features a (language aware) Xcode extension (yes!) and support for macOS services (i.e. automatic ASCII Cows support in any Cocoa text field).

And for iOS there is ASCII Cows. Includes a Messages app and proper Markdown support, so that you can paste the cows into WhatsApp properly.

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu. GitHub.

Want to support my work? Buy an app! You don’t have to use it! 😀

🐮 SwiftUI Tools w/ just SwiftPM

Mon, 23 Aug 2021 00:00:00 +0200

The Swift Package Manager coming with Swift 5.5 / Xcode 13 now supports the @main attribute. We can use that to build apps using just SwiftPM, no Xcode involved! Let’s use it to build a Cowtastic app!

The @main attribute was actually introduced in Xcode 12, but starting w/ Swift 5.5 it is now also supported in Swift Package Manager. (ObjC.io also has a nice pre-@main article about this, requiring more boilerplate.)

This is what is possible now, w/o having to use Xcode:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

Produces this little thing when it is run:

Setting up the SwiftPM Boilerplate

Unfortunately the otherwise awesome swift-sh does not yet support @main. Issue #163 got filed. Once that is implemented, even SwiftPM can be completely avoided and Swift scripts w/ SwiftUI would just work.

For now, we still need to create a Swift package. First make sure that Swift 5.5 is active:

$ swift --version
swift-driver version: 1.26.9 Apple Swift version 5.5 (swiftlang-1300.0.29.102 clang-1300.0.28.1)
Target: arm64-apple-macosx11.0

If it is not: sudo xcode-select -s /Applications/Xcode-beta.app.

Next create the package boilerplate:

$ mkdir Tows && cd Tows
$ swift package init --type executable
Creating executable package: Tows
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/Tows/main.swift
Creating Tests/
Creating Tests/TowsTests/
Creating Tests/TowsTests/TowsTests.swift

$ mv Sources/Tows/main.swift \
     Sources/Tows/Tows.swift

Then we need to replace the contents (the print("Hello")) with our app as shown above:

import SwiftUI

@main
struct HelloWorld: App {
  
  var body: some Scene {
    WindowGroup { 
      Text("Hello World!").padding()
    }
  }
}

And then we can run swift build:

$ swift build
Tows.swift:3:1: error: 'main()' is only available in macOS 11.0 or newer
@main
^

Oops. That says at least macOS BS is required. Easily fixed by adding that requirement to our Package.swift file:

// swift-tools-version:5.5
import PackageDescription

let package = Package(
  name: "Tows",
  platforms: [ .macOS(.v11) ], // <= add this!
  dependencies: [],
  targets: [ .executableTarget(name: "Tows", dependencies: []) ]
)

Now it builds and runs:

$ swift run
[3/3] Build complete!

You may have to search for the window, it is not put in front of your other windows.

IMPORTANT: This is not quite a full app yet. You’ll notice it has no menu bar and if you quit it, you’ll quit your editor instead 😈 To close it, you need to Control-C the swift run in the terminal.

Fixing the App Activation

To make the thing behave like an app proper a Cocoa with Love trick from 2010 has to be applied. We are going to add an init to our App structure:

@main
struct HelloWorld: App {
  
  init() {
    DispatchQueue.main.async {
      NSApp.setActivationPolicy(.regular)
      NSApp.activate(ignoringOtherApps: true)
      NSApp.windows.first?.makeKeyAndOrderFront(nil)
    }    
  }
  ...
}

Re-run the tool, it’ll have a menu proper and it can be quit as usual.

We are done. That is all which is required. But can we write more complex apps with that? Something cowtastic? Yes we can!

          (__)
        /  .\/.     ______
       |  /\_|     |      \
       |  |___     |       |
       |   ---@    |_______|
    *  |  |   ----   |    |
     \ |  |_____
      \|________|
CompuCow Discovers Bug in Compiler

A Cowtastic App

This thing, as a SwiftPM tool, in 82 lines of code (including support for search, selection and dragging):

We are going to use the Swift cows package, let’s add it as a dependency to Package.swift:

// swift-tools-version:5.5
import PackageDescription

let package = Package(
  name: "Tows",
  platforms: [ .macOS(.v11) ],
  dependencies: [ // add this:
    .package(url: "https://github.com/AlwaysRightInstitute/cows",
             from: "1.0.10")
  ],
  targets: [ 
    .executableTarget(name: "Tows", 
                      dependencies: [ "cows" ]) // <= add this!
  ]
)

And the script itself. Gist: Tows.swift

import SwiftUI
import cows // @AlwaysRightInstitute

struct ContentView: View {
  
  @State var searchString  = ""
  @State var matches       = allCows
  @State var selectedCow   : String?
  
  let font = Font(NSFont
    .monospacedSystemFont(ofSize: NSFont.systemFontSize, weight: .regular))
  
  var body: some View {
    NavigationView {
      ScrollView {
        TextField("Search", text: $searchString)
          .textFieldStyle(RoundedBorderTextFieldStyle())
          .padding(8)
          .onChange(of: searchString) { nv in
            matches = nv.isEmpty 
                    ? cows.allCows 
                    : cows.allCows.filter { $0.contains(searchString) }
          }
        Spacer()
      }
      
      ScrollView {
        VStack(spacing: 0) {
          if matches.isEmpty {
            Text("Didn't find cows matching '\(searchString)' 🐮")
              .padding()
              .font(.title)
            Divider()
          }
          
          ForEach(matches.isEmpty ? allCows : matches, id: \.self) { cow in
            Text(verbatim: cow)
              .font(font)
              .onDrag { NSItemProvider(object: cow as NSString ) }
              .padding()
              .background(
                RoundedRectangle(cornerRadius: 16)
                  .strokeBorder()
                  .foregroundColor(.accentColor)
                  .padding(4)
                  .opacity(selectedCow == cow ? 1 : 0)
              )
              .frame(maxWidth: .infinity)
              .contentShape(Rectangle())
              .onTapGesture {
                selectedCow = selectedCow == cow ? nil : cow
              }
          }
        }
      }
      .ignoresSafeArea()
    }
  }
}

@main
struct TestAppApp: App {
  
  init() {
    DispatchQueue.main.async {
      NSApp.setActivationPolicy(.regular)
      NSApp.activate(ignoringOtherApps: true)
      NSApp.windows.first?.makeKeyAndOrderFront(nil)
    }
  }
  
  var body: some Scene {
    WindowGroup {
      ContentView()
        .frame(minWidth: 640, minHeight: 320)
    }
    .windowStyle(HiddenTitleBarWindowStyle())
  }
}

Closing Notes

The only thing we’d like is swift-sh support, so that we can drop all that SwiftPM boilerplate 🤓

Want to have a readymade app that is properly reviewed by Apple’s AppStore team?

There is CodeCows. Which (amongst other things) features an Xcode extension (yes!) and support for macOS services (i.e. automatic ASCII Cows support in any Cocoa text field, Electron not).

And for iOS there is ASCII Cows. Includes a Messages app and proper Markdown support, so that you can paste the cows into WhatsApp properly.

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu. GitHub.

Want to support my work? Buy an app! You don’t have to use it! 😀

DocC 📚 Archived and Analyzed

Fri, 02 Jul 2021 00:00:00 +0200

At WWDC 2021 Apple presented DocC, a way to create Swift documentation and tutorials right within Xcode. We are going to look at the documentation archive produced, the good&bad and how to generate a static website.

Update 2023-09-23: DocC itself now supports some static exports (but still exports dynamic sites).

TLDR: Just looking for the static exporter, don’t want to read all this junk? It is over here, but remember it is still an early and quick hack: docc2html. Works like that:

$ swift run docc2html --force \
    SlothCreator.doccarchive \
    /tmp/SlothCreatorSite/

Then open file:///tmp/SlothCreatorSite/documentation/slothcreator/index.html.

As part of this blog entry we are not going to look on how DocC documentation and tutorials are written (the Apple WWDC sessions do a very good job on explaining that), but rather on what the output of DocC is. And what we can do with it.

Let’s still revisit what the user facing part does.

DocC Quick Usage Intro

So what is the new feature about? In Xcode 13 you just have to press Ctrl-Shift-Cmd-D and it is going to produce documentation for all targets in your project. And open that in the Xcode documentation viewer (you can also trigger the action using the “Product / Build Documentation” menu). This is what it looks like:

DocC is working together w/ the Swift compiler infrastructure to extract the API of a Swift target and its documentation comments. A target can also (optionally!) include a “Documentation Catalog” which can enhance the source documentation of a target w/ additional overview documents, tutorials and more. It supports quite a lot of things and you can learn more about those in the WWDC sessions or Documenting a Swift Framework or Package.

We are going to look at something else, this feature:

It can also be automated using xcodebuild, which is covered in Host and automate your DocC documentation. That “export” is creating a “DocC Archive” and that happens to be the really interesting part.

The DocC Archive

A DocC Archive appears as an opaque file in Finder, but it is just a directory structure containing an export of your documentation (you can look at it by choosing “Show Package Contents” in Finder’s context menu).

$ ls ~/Downloads/SlothCreator.doccarchive/
css			favicon.ico		img			js
data			favicon.svg		index			theme-settings.json
downloads		images			index.html		videos

The big fancy, official feature being: It contains HTML and supporting files to show your site in a web browser, with similar features to the beautiful SwiftUI documentation you might have seen. This is what it looks like:

Just open the index.html file in the DocC Archive and it’ll open the documentation in the browser, NOT 🤦‍♀️ It’s funny how it could have possibly happened that such a basic feature doesn’t work.

I suspect the reason this happened is that Apple itself is using DocC to document just Xcode projects, not Swift Packages. And that all the docs are hosted internally on a central website automagically.

Long story short: To open a DocC Archive in the browser, you need an actual HTTP server. Yours truly has hacked up a small Macro.swift script to do the job: servedocc. No .htaccess configuration necessary.

This issue resulted in some serious backslash like: Apple’s DocC is excellent, but unusable for open source projects. I disagree, DocC is not useless for open source projects.

To understand why, we have to look at the exported DocC Archive in more detail.

It’s also worth mentioning that Apple said to release DocC itself as open source later this year. They also said that they are going to provide a hosting service for documentation, we’ll see how that works out.

The Three Kings Things (in a DocC Archive)

The archive is not just one thing, it contains three things:

A version of the documentation suitable for the Xcode Documentation Viewer
All the generated documentation as raw, parseable data, in a hierarchy of JSON files, plus images etc.
A Vue.js JavaScript web application to display the raw data. All webpacked.

We only ever use the Xcode Documentation Viewer by accident, but presumably it is useful to some? 🤷‍♀️ This part is contained in the index subdirectory (some binary plists and other stuff).

The JSON export is the real gem and the thing where the actual value of DocC lives. Instead of producing opaque HTML we get access to the raw, structured, data!

And the embedded Vue.js app is really nice too. E.g. it produces those fancy tutorials, but has the before mentioned (serious) issue of not being able to run w/o a server to please the URL demands of the JS app.

The Semantic Web

What DocC is doing here is conceptually a great idea and doesn’t actually bite w/ hosting an archive on say GitHub pages or straight S3. The documentation is exported as static JSON and a small JavaScript reads those and just does the fancy display (data as XML and rendering as XSLT would have been even cooler 👴).

Why is this cool? Search engines, IDEs, apps and other tooling can directly access the hosted raw data, index, understand and process it.

Why is this not just cool? Three reasons:

The DocC Vue.js app itself doesn’t currently work as a static export. That is likely a temporary flaw which can and is going to be fixed.
<noscript>
Google and companions do not process and display those JSON files as readable documents. They only show HTML pages. No semantic web for us 😢

Apart from the b0rked frontend app, the latter is a major reason to still export the docs as straight, static HTML.

Reading the DocC Archive Data in Swift

We’ve been interested how the JSON is layed out and how it works. And in the process created DocCArchive, a Swift package everyone can use. E.g. in Swift scripts that analyse API differences, documentation viewer applications (SwiftPM Catalog could show documentation inline, is that interesting?) or: static HTML exporters.

DocCArchive can parse all the JSON (including tutorials) created by the SlothCreator example.

Important: When using it on your own projects, you will likely run into setups we didn’t test and need to add. Please let us know, we’ll fix missing cases ASAP (PRs are welcome too). DocCArchive is just a rather quick hack up. Cleanup PRs and refactorings are welcome as well.

We’ll get to docc2html in a moment, a look at the structure of the raw DocC Archive data first.

Directory Structure

$ tree .
.
├── css
...
├── data
│   ├── documentation
│   │   ├── slothcreator
│   │   │   ├── activity
│   │   │   │   └── perform(with:).json
...
│   │   └── slothcreator.json
│   └── tutorials
...

All the raw data is located in the data subfolder of the subdir, specifically in the documentation and tutorials subfolders.

Using DocCArchive the archive can be opened like that, it manages the general layout of the archive:

let url     = URL(fileURLWithPath: "~/Downloads/SlothCreator.doccarchive")
let archive = try DocCArchive(contentsOf: url)

To browse the documentation, DocumentFolder objects are used:

if let docs = archive.documentationFolder() {
  ... work it ...
}

Documents

The JSON itself is versioned (currently 0.1.0), so it may still change. DocCArchive represents it as a Document object.

This is what the actual ~~XML~~ JSON looks like:

{ "topicSections": [
    { "title": "Essentials", "identifiers": [
        "doc://SlothCreator/tutorials/SlothCreator", ... ]
    }, ...
  ],
  "schemaVersion": { "major": 0, "minor": 1, "patch": 0 },
  "sections": [],
  "primaryContentSections": [
    { "kind": "content",
      "content": [
        { "type": "heading",  "level": 2,  
          "text": "Overview", "anchor": "Overview"
        },
        { "type": "paragraph", "inlineContent": [
          { "type": "text",
            "text": "SlothCreator provides models and ..."
        ...
        { "type": "paragraph", "inlineContent": [
          { "type": "image", "identifier": "sloth.png" } ] }
      ]
    }
  ],
  "variants": [
    { "paths" : [ "/documentation/slothcreator" ],
      "traits": [ { "interfaceLanguage": "swift" } ] }
  ],
  "identifier": {
    "url": "doc://SlothCreator/documentation/SlothCreator",
    "interfaceLanguage": "swift"
  },
  "abstract": [
    { "type": "text",
      "text": "Catalog sloths you find in nature and create new adorable virtual sloths."
    }
  ],
  "kind": "symbol",
  "metadata": {
    "roleHeading" : "Framework",
    "externalID"  : "SlothCreator",
    "title"       : "SlothCreator",
    "symbolKind"  : "module",
    "role"        : "collection",
    "modules"     : [ { "name": "SlothCreator" } ]
  },
  "hierarchy": { "paths": [[]] },
  "documentVersion": 0,
  "references": {
    "doc://SlothCreator/documentation/SlothCreator/Activity": {
      "role"    : "symbol",
      "title"   : "Activity",
      "fragments": [
        { "kind": "keyword",    "text": "protocol" },
        { "kind": "text",       "text": " "        },
        { "kind": "identifier", "text": "Activity" }
      ],
      "abstract": [ ... ],
		 ...
      "url"     : "/documentation/slothcreator/activity"
    },
	  ...
    "sloth.png": {
      "alt"        : "A sloth hanging off a tree.",
      "type"       : "image",
      "identifier" : "sloth.png",
      "variants": [
        { "url"    : "/images/sloth@2x.png",
          "size"   : { "width": 952, "height": 756 },
          "traits" : [ "2x", "light" ]
        },...
      ]
    },
	  ...
  }
}

An interesting thing is that the JSON, except for images, is self contained. For example to show the abstract of the Activity type, there is no need to load the associated Activity.json document. All the necessary metadata is embedded in the document already.

All the JSON info can be found in neat Swift types as part of the Document object:

var schemaVersion          : SchemaVersion
var identifier             : Identifier
var documentVersion        : Int
var kind                   : Kind
var metadata               : MetaData
var hierarchy              : Hierarchy
var variants               : [ Variant ]? // not in tutorial
var abstract               : [ InlineContent ]? // not in tutorial
var sections               : [ Section ]
var topicSections          : [ Section ]?
var seeAlsoSections        : [ Section ]?
var primaryContentSections : [ Section ]?
var references             : [ String : Reference ]

Summary: Use DocCArchive to write your own scripts and apps processing DocC archives. Let us know if you find open ends.

The Static HTML Exporter

Finally, let’s talk about docc2html, a tool to export DocC Archives to an actual, fully static HTML site. With relative linking, so it doesn’t matter where they live. Goodbye redirects.

First off: ~~This is a **very quick hack**/PoC full of quirks, and is pretty incomplete.~~ It does have working parts and we invite everyone to improve it and provide PRs. Or ignore it and come up with an own exporter based on this (and potentially DocCArchive).

Again, the tool is, as of today, just tested against the SlothCreator example. Expect issues with other DocC Archives 💥

~~It does not export tutorials yet, only the documents in the documentation folder.~~

Update 2021-07-10: docc2html is now in a pretty reasonable state and the implementation isn’t that hacky anymore. Custom templates can now be provided (and overridden) in the filesystem. It can even generate tutorials to a certain degree. At least for API documentation it should be viable to use. The CSS is the thing which will need some massage.

To play with it, clone the GitHub repo:

$ git clone https://github.com/DoccZz/docc2html.git
$ cd docc2html

And run like that:

$ swift run docc2html \
    --force \
    ~/Downloads/SlothCreator.doccarchive \
    /tmp/SlothCreatorSite/

This will create the static site in /tmp/SlothCreatorSite. The root documentation can be directly opened in the browser, e.g.

open file:///tmp/SlothCreatorSite/documentation/slothcreator/index.html

It is not much yet, but a pretty good starting point.

Using it on GitHub

We didn’t try that yet ∾ But hope to be able to move the SwiftBlocksUI Documentation to that. Going to take some time until it’s possible.

The GitHub action would need to:

patch the Package.swift version to 5.5
run the xcodebuild -doc thing to produce the DocC Archives
use docc2html on each of the archives
publish the result to GH Pages

2021-07-10: I don’t think GitHub supports Xcode 13b yet (i.e. no way to get DocC into a GH action).

Parsing Apple Online Docs

Apple itself is using DocC online and one can access the documentation JSON the same way as described.

For example the JSON for the Getting Started with Scrumdinger can be found over here: https://developer.apple.com/tutorials/data/tutorials/app-dev-training/getting-started-with-scrumdinger.json .

We didn’t try yet, but it should be possible to access the online documentation and tutorials using DocCArchive the same way as we access the archive exports.

Closing Notes

Funny, but neither DocCArchive nor docc2html are documented with DocC yet. PRs welcome!

To summarize some DocC complains we at the ARI have:

Only seems to document Swift targets, not Swift packages.
Requires the 5.5 tools version in the Package.swift to make Xcode 13 build documentation, which seems to make zarro sense.
The Vue.js app doesn’t work on a location independent, static, dataset. Even with a static site exporter, that might still make sense.
While they look nice, the UX of the tutorials is actually pretty awful.
OpenSource projects often document the sources using README.md files in subfolders. Those should be taken into account somehow.

When you open the Vue.js app in a browser that has JavaScript disabled (or doesn’t support JavaScript, like say Lynx), you’ll get the popular “This page requires JavaScript”. By mixing in the docc2html this could actually be fixed.

Summary: It has some flaws, but we particularily like that DocC outputs structured data one can process in own tooling.

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu.

Want to support my work? Buy an app! You don’t have to use it! 😀

Async/Await for iOS 14 and before

Thu, 17 Jun 2021 00:00:00 +0200

The secret Apple doesn’t want you to know about: It has been shipping an async/await runtime for years. Let’s have a look on how to use it from within Swift!

In another episode of “forums are awful”, people go at length to complain about Swift Concurrency not being available on iOS 14 / macOS 11 and before. Yes, that is right, the new async/await requires iOS 15 or later.

Damn, I guess that means I and many others won’t be using it for a few years 😞

Fret not. If you really, really want to use async/await and can’t wait, there is a secret Apple isn’t advertising: It is already shipping an async/await runtime since about iOS 12 (probably longer). You have to give up a little typesafety, but that’s overrated anyhow. Let’s have a look on how to use it.

What we are aiming for in the demo is the await URLSession.data(for:) as shown in Meet async/await in Swift around 9:31.

This is what we are going to run from our Swift program, almost identical code:

async function mainActor() {
  let [ data, res ] =
    await URLSession.shared.data("https://zeezide.com/")
  print("Data: " + data)
}

mainActor()

We ask URLSession to download some data asynchronously, and await the results (the data fetched and the response). Note that (as usual) await can only be run from within an async function, so we setup a mainActor() first.

Disclaimer: Yes, yes, we know. But the article is still worth a read! 🤓

The full example is available in this GiST: main.swift.

If you want to follow along, the easiest way is to create a macOS Tool project in Xcode (no Xcode 13 required, this also works with Xcode 12 and probably even xCode X).
Just dump the code into the main.swift.

Firing up the Secret Runtime

The first thing we need to do is import and setup the async/await runtime Apple is secretly shipping with older iOS/macOS versions:

// They use obfuscated names to hide it from us!
import JavaScriptCore

let runtime = JSContext()!
runtime.exceptionHandler = { _, error in print("ERROR:", error as Any) }

Let’s add a small debugging helper, a print function, to our concurrent runtime:

runtime.setObject(
  {()->@convention(block) (JSValue)->Void in { print($0) }}(),
  forKeyedSubscript: "print" as NSString
)

Adding Concurrency Support to URLSession

iOS 14 and before are shipping the runtime, but they do not ship the enhanced, async/await enabled, APIs. But it is easy enough to add them ourselves.

The first thing is adding a protocol declaring the concurrency support we are going to add to URLSession:

@objc protocol AsyncURLSession: JSExport {
  
  func data(_ url: String) -> JSValue
  
  @objc(shared) static var sharedSwift : URLSession { get }
}

The URLSession.data() function is the asynchronous function we are going to call with await like this:

let [ data, res ] =
  await URLSession.shared.data("https://zeezide.com/")

With the protocol we just declare our intention to the runtime. We still need to add concurrency support to the URLSession itself. That is a bit of boilerplate but nothing overly complicated:

@objc extension URLSession: AsyncURLSession {
  
  dynamic class var sharedSwift : URLSession { shared }

  func data(_ url: String) -> JSValue {
    /// Create our continuation
    return JSValue(newPromiseIn: JSContext.current()!) { 
      resolve, reject in
      
      guard let url = URL(string: url) else {
        reject?.call(withArguments: [ "invalidURL" ])
        return
      }
      
      self.dataTask(with: URLRequest(url: url)) { data, response, error in
        RunLoop.main.perform {
          if let error = error {
            reject?.call(withArguments: [ error.localizedDescription ])
          }
          else if let data = data, let response = response {
            resolve?.call(withArguments: [ [ data, response ] ])
          }
          else {
            reject?.call(withArguments: [ "missingResponse" ])
          }
        }
      }
      .resume()
    }
  }
}
runtime.setObject(URLSession.self, forKeyedSubscript: "URLSession" as NSString)
runtime.evaluateScript("URLSession.shared = URLSession.shared();")

Notice how we still call into the old, block based, URLSession.dataTask(with:) method to perform the job. All we do is add support for async/await.

And that’s all we need to do!

Using the Concurrency Features

With the runtime setup and our enhanced concurrency API in place, we can start using it from Swift. It requires the special #""" syntax, but you’ll get used to it in no time!

runtime.evaluateScript(#"""

  async function mainActor() {
    let [ data, res ] =
      await URLSession.shared.data("https://zeezide.com/")
    
    print(data)
    print(res)
  }
  
  mainActor()
"""#)

And et voilà we have async/await for iOS 14 and before!

One last thing: If you are running this from within a tool (instead of, say, a SwiftUI app), you need to make sure the tool keeps running until your async functions are done. This does the trick:

RunnLoop.main.run()

The full example is available in this GiST: main.swift.

Closing Notes

We think it’s OK to not add Concurrency to iOS 14 and before. We’ve choosen a static language like Swift and now we gotta live with it. There is no some support in iOS 11 either. It’s only a few more months and you’ll be able to deploy first apps using it.

Instead of wasting effort on a half-hearted backport, we’d prefer to see support for Custom Executors. So that the new concurrency features can be used in a meaningful way on servers using SwiftNIO. Thanks!

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu.

Want to support my work? Buy an app! You don’t have to use it! 😀

Hosting WebAssembly in Swift

Sun, 10 Jan 2021 00:00:00 +0100

Today we are going to embed and run WebAssembly (Wasm) modules in a Swift program. Using Wasmer, an embeddable runtime for Wasm, wrapped in a simple Swift API.

Note: 2023-09-23: This is probably outdated by now. API changes in Wasmer.

While it isn’t used that much in production just yet, you likely have heard about WebAssembly (Wasm) before. The technology is most commonly known for running programs written in compiled languages like C, Rust or Swift right within a web browser. Sandboxed, and without any native plugins.

That is not what we are going to do today. Instead of running Wasm programs inside of a web browser, we are going to run them inside of a Swift program.

For the impatient among us, this is what it looks like:

import Wasmer

let wasmData = try Data(contentsOf: URL(fileURLWithPath: "sum.wasm"))
let module   = try WebAssembly.Module(wasmData)
let instance = try WebAssembly.Instance(module)
print(instance.exports.sum(.i32(7), .i32(8)))

We are also not going to look at how to compile Swift itself to WebAssembly. Checkout the SwiftWasm project for that.

So what exactly is Wasm. We’ll look at that in more detail further down below, but essentially a developer can compile a, say Rust, program into a Wasm “binary”. In Rust it looks like this:

$ cargo build --target wasm32-wasi

The result is a .wasm file, for example sum.wasm - a Wasm binary. It doesn’t run natively on your host (it is built for a different platform), but it does run within a web browser, or: using embeddable runtimes like Wasmer.

The wasm32 in the target is like x86 or arm64 - the CPU architecture. The wasi is more like the operating system, what would be win32 or linux in other targets.

But let’s setup a first basic project to get a feel for the technology.

Installing Wasmer

Wasmer is pretty small and can be installed with a little script in like 30 seconds (manual install is fine too, check the docs for instructions):

$ curl https://get.wasmer.io -sSfL | sh

Afterwards you have the wasmer and wapm binaries (they install into ~/.wasmer by default). WAPM is a package manager like Homebrew and can be used to install and run Wasm packages:

$ wapm install -g fortune
[INFO] Installing _/fortune@0.2.0
$ wapm run fortune
The most exciting phrase to hear in science, the one that heralds new discoveries, is not "Eureka!" (I found it!) but "That's funny ..."
    -- Isaac Asimov

A more complex example, a JavaScript engine as a Wasm module: QuickJS:

$ wapm install -g quickjs
[INFO] Installing _/quickjs@0.0.3
Global package installed successfully!

$ wapm run qjs
QuickJS - Type "\h" for help
qjs > console.log("hello")
console.log("hello")
hello
undefined

Looks nice. Let’s compile a small program ourselves.

Compiling a Rust program

Arguably one of the languages which (as of today) support Wasm the best is Rust. We at the ARI think Rust is mostly wrong, but it always pays to watch over the fence. Since a few examples we are going to play with are in Rust, let’s install the toolchain.

Note: Do not install the rust Homebrew package! Instead we are going to use rustup, which can install both Rust compiler/env and the Wasm toolchain we need:

$ brew install rustup
$ rustup-init
$ source $HOME/.cargo/env
$ rustup target add wasm32-wasi

That’s all required to get going with Rust. We are going to compile the cowsay Rust program. Into a Wasm binary. First check out the repository:

$ git clone https://github.com/wapm-packages/cowsay
$ cd cowsay

Then compile it for Wasm:

$ cargo build --target wasm32-wasi --release
...
    Finished dev [unoptimized + debuginfo] target(s) in 35.68s

Just like with Swift Package Manager, this will pull down and compile all the dependencies, then the program itself. The result can be found in the target/wasm32-wasi/release folder:

$ du -sh target/wasm32-wasi/release/cowsay.wasm 
804K	target/wasm32-wasi/release/cowsay.wasm

We can run the module using wasmer:

$ wasmer target/wasm32-wasi/release/cowsay.wasm Swifty Cow!
 _____________
< Swifty Cow! >
 -------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
               ||----w |
                ||     ||

Excellent, we got Wasm cows!

The wasmer tool acts as the runtime for the compiled Wasm program, quite similar to how you invoke Java programs with java, Python programs with python and so on.
Actually it is a lot more similar to invoking a Docker container like docker run -it swift, but we’ll get to that later.

“Very nice” you say, but where is the promised Swift stuff? We ain’t here for the Rost!

SwiftyWasmer

Wasmer comes with quite a set of APIs to embed Wasmer into tools written in other programming languages. There is one for Go, one for C/C++, one for JavaScript and one for Rust. Bot none for Swift.

Thanks to Swift’s excellent C integration, we used that and produced: SwiftyWasmer.

To work, the Swift Package Manager requires a pkg-config file. Fortunately wasmer config can generate one for you:

$ wasmer config --pkg-config \
  > /usr/local/lib/pkgconfig/wasmer.pc

Unfortunately the generated file is a little b0rked in 1.0.0. Open up the file in your favorite editor:

$ emacs /usr/local/lib/pkgconfig/wasmer.pc

And adjust two little things:

remove the /wasmer from the Cflags line, it should then read:
Cflags: -I/Users/helge/.wasmer/include
add -lffi to the Libs line, it should then read:
Libs: -L/Users/helge/.wasmer/lib -lwasmer -lffi

To link statically, move libwasmer.dylib out of the way:

mv ~/.wasmer/lib/libwasmer.dylib \
   ~/.wasmer/lib/libwasmer.dylib-away

Let’s build something similar to the wasmer CLI tool above, but using Swift. The easiest way to get going it to use swift sh (brew install swift-sh), but feel free to setup an Xcode or SPM tool project:

#!/usr/bin/swift sh
import Wasmer // helje5/SwiftyWasmer

let path     = URL(fileURLWithPath: CommandLine.arguments[1])
let module   = try WebAssembly.Module(contentsOf: path)
let instance = try WebAssembly.Instance(module)

_ = try instance.exports._start()

You can put that into mytool.swift, run chmod +x mytool.swift and then run the tool itself:

$ echo "Hello Swift" | \
  ./mytool.swift target/wasm32-wasi/release/cowsay.wasm 
 _____________
< Hello Swift >
 -------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
               ||----w |
                ||     ||

Note: We cannot pass commandline arguments to cowsay for reasons, but cowsay reads from stdin as a fallback. Which is what the echo pipe does.

The code should be pretty self explanatory. We first build a URL for the file passed in argument[1]. We then create a WebAssembly.Module for that URL:

let module = try WebAssembly.Module(contentsOf: path)

A Module is essentially the compiled Wasm. It can’t be executed on its own, to do that, a WebAssembly.Instance needs to be setup:

let instance = try WebAssembly.Instance(module)

The Instance is the execution environment, the Sandbox. When the Instance is created, you provide the compiled Module and optionally a set of “imports” you want to make available to the module. After the Instance is created, the “exports” are available.
This is quite similar to how dynamic libraries work, they have a set of symbols they “import” and a set of symbols (functions, globals, classes, etc) they “export”.

The default entry point for “tool like” binaries is the _start function, again quite similar to the _main used in C/system executables. This is what we (and the wasmer tool) call to start the Wasm program:

_ = try instance.exports._start()

_start neither takes arguments nor returns values. An Error would be thrown if the module wouldn’t actually export the _start function. For example because it isn’t a commandline tool, but some other module, like a library or plugin.

Excellent, we can run tools compiled for Wasm right from within Swift! An advantage: those Wasm compilations work on all platforms, similar to how you can run a Java program on all platforms (write once, run anywhere). But in a little different way.

Building a Small Rust Lib and Call it from Swift

We are now going to dive a little deeper into what Wasm is and how it works. Let’s start by writing a tinsy Rust library which provides a function to add two numbers.

There is no need to know much about Rust here. What we need to do to setup a library project is similar to SwiftPM. The Rust package manager is called cargo:

$ cargo new --lib sum # create a new lib called `sum`
$ tree sum
sum
├── Cargo.toml
└── src
    └── lib.rs

Add this to the Cargo.toml, to tell Rust that we are creating a library with a “C” interface:

[lib]
crate-type = ["cdylib"]

Then replace the contents of the lib.rs file with:

#[no_mangle]
extern "C" fn sum(a: i32, b: i32) -> i32 {
  let s = a + b;
  println!("From WASM: Sum is: {:?}", s);
  s
}

The #[no_mangle] and extern "C" are similar to Swift’s @_cdecl. All the rest is really similar to Swift (almost like Rust stole all the best ideas from it 😉). We add two integer (32-bit) numbers, print it, and then return the result.

Like with cowsay before, our module can be compiled like this:

$ cargo build --target wasm32-wasi
   Compiling sum v0.1.0 (/tmp/sum)
    Finished dev [unoptimized + debuginfo] target(s) in 0.45s
$ du -sh target/wasm32-wasi/debug/sum.wasm 
1.7M	target/wasm32-wasi/debug/sum.wasm

Note that we didn’t define a _start function, this time we built a library with a single sum function.

Here is a small Swift tool which can load that module written in Rust and invoke the function:

#!/usr/bin/swift sh
import Wasmer // helje5/SwiftyWasmer

let path     = URL(fileURLWithPath: CommandLine.arguments[1])
let module   = try WebAssembly.Module(contentsOf: path)
let instance = try WebAssembly.Instance(module)

print(try instance.exports.sum(.i32(46), .i32(2)))

Calling it:

$ ./mytool.swift target/wasm32-wasi/debug/sum.wasm 
From WASM: Sum is: 48
[i32(48)]

Note how the Rust module prints the result, and our Swift side also prints the result(s).

An important thing: It doesn’t matter what language was used to produce the Wasm module. As long as it exports a sum function, we can call it using the very same from Swift.

Above we show running things using swift sh. Xcode can be used as well. Just create a new macOS “Tool” project and add this package https://github.com/helje5/SwiftyWasmer as a SwiftPM dependency (e.g. via “File / Swift Packages / Add Dependency”). When compiling in Xcode, make sure you compile for “Your Mac” is the target device (i.e. not an iOS device).

Functions which are no real Functions

Above we’ve seen that the sum call was invoked with two .i32 arguments and that it returns a single .i32 argument. It is a 32bit integer, obviously. Now the interesting part is that Wasm functions only allow for four different datatypes: .i32, .i64, .f32 and .f64. That is it! No strings, no structs, no arrays. Let alone methods or objects.

Disclaimer: we are no experts on this, please feel free to send corrections!

So let’s review what Wasm actually is, it is easy to get wrong, especially if you already have some smattering knowledge about Wasm. With all the talk about “functions” being imported and exported, you might think it is like embedding Python or Java using the JNI. Or maybe like COM or CORBA. That is not the case. It isn’t like JVM or CLR bytecode either.

The WebAssembly website says:

Wasm is a binary instruction format for a stack-based virtual machine.

Wasm itself is really nothing more than that. It specifies the binary machine code a Wasm “CPU” will run. And that machine code is kept very simple. Writing a Wasm program by hand is very much like writing an assembly program for the ARM or Intel CPUs. Besides the instructions to execute, the Wasm runtime also provides a linear memory block to the “machine”.

So what happens if you run a Wasm program is more similar to the process that happens when you run Intel binary code using Rosetta on an M1 Mac. Or some S/390 machine code on an Intel machine using QEmu.

How low level is it? Very, very low level. For example, let’s assume you want to pass a String from the host to the Wasm program. What you essentially have to do is:

copy the string into the memory of the Wasm instance, as bytes, e.g. UTF-8
call a function function with the position of the string in memory, and maybe its length

So consider Wasm like a computer. If you boot it up, it starts executing instructions for its CPU, the Wasm instructions.
Now (unless you are an embedded developer) you very rarely write programs that directly execute on a barebones computer. Instead you’d usually use an operating system, like Windows or Linux. This OS will provide userlevel programs much nicer abstractions for dealing with memory, handling I/O etc.

No different in Wasm “computers”. Currently there are two major Wasm “operating systems”: The older but very capable emscripten and the newer WASI (WebAssembly System Interface). Both provide user level library functionality to Wasm programs. For example in our sum example we used println! to print out a value. That calls into WASI to perform the actual printing (on the host).

This brings us back to “Functions which are no real Functions”. Considering the context, I found it more useful to think of the “Wasm functions” as system calls (i.e. calls going from userspace to kernelspace). If you call, say emscripten write, it’ll call a host provided function with something like _syscall(.i32(4), .i32(2727), .i32(12)). The 4 could be the file descriptor, the 2727 the position of the data in the memory and 12 its length.

Unlike the JVM or the CLR, Wasm has no concept of methods, dynamic dispatch, objects - or any such higher level concept. Both JVM and CLR do act as language bridges somewhat similar to COM (i.e. they allow integrating different languages compiled to their high level OO capable bytecode).

Wasmer is more like Docker

In summary Wasm is less like a scripting language runtime or language integration bridge, but way more like a Docker virtual machine. Or Virtualization.framework. Think in that direction when thinking about additional Wasm usecases. Yes, Wasm can be used to deal with compute intense tasks in web browsers by using compiled code, but it can also be used to host code in isolated environments on the server (or the client!).

Unlike Docker Wasm doesn’t need a Linux kernel to run. Or images for a specific instruction set. “Wasm images” can be run on any platform which have a runtime available. Yes, even in the browser if that is desirable.

The environment provided by WASI is also very much like the Docker environment. You can remap files, you can provide the files the sandbox can even access (by default none), etc.

As an example, this is how you run nginx in Wasmer (uses emscripten):

$ wapm run nginx -p example -c nginx.conf
2015/10/21 07:28:00 [notice] 73097#0: nginx/1.15.3
2015/10/21 07:28:00 [notice] 73097#0: built by clang 6.0.1  (emscripten 1.38.12 : 1.38.12)
2015/10/21 07:28:00 [notice] 73097#0: OS: Darwin

In the future you might able to run a Macro.swift server alongside your nginx frontend proxy, while connecting to some database written in Rust. Unlike with Docker, you don’t have to wrap each in a full Linux environment. We’d need something like compose for that, and SwiftyWasmer might be used to write such tooling 😉

We could also see that the tech might be used to offer very lightweight AWS Lambda like functions, without all the overhead required to boot up a Linux kernel. Yet still giving the user the choice what language to write the functions in.

Compiling Swift to Wasm

The original article didn’t talk about this, but we just gave it a try and it worked nicely: Compiling Swift itself to Wasm. And then running that Wasm Swift binary from within Swift ∞

To get going, one needs to download a Swift toolchain from the SwiftWasm project, for example: Swift Wasm 5.3.1. Install the package, and you’ll find the Swift Wasm toolchain in: /Library/Developer/Toolchains/.

Add it to your path when playing w/ SwiftWasm:

$ export PATH=/Library/Developer/Toolchains/swift-wasm-5.3.1-RELEASE.xctoolchain/usr/bin:$PATH

Let’s pull down a great Swift package, cows, and build it for Wasm:

$ git clone https://github.com/AlwaysRightInstitute/cows
$ cd cows
$ swift build --triple wasm32-unknown-wasi
[9/9] Linking vaca.wasm
$ du -sh .build/debug/vaca.wasm 
 25M	.build/debug/vaca.wasm

And yay, you can then run this in Wasmer:

$ wasmer .build/debug/vaca.wasm compiler
          (__)
        /  .\/.     ______
       |  /\_|     |      \
       |  |___     |       |
       |   ---@    |_______|
    *  |  |   ----   |    |
     \ |  |_____
      \|________|
CompuCow Discovers Bug in Compiler

Or in Swift (e.g. using the swasi-run tool included in SwiftyWasmer):

$ swift run swasi-run vaca.wasm 
        o
        | [---]
        |   |
        |   |                              |------========|
   /----|---|\                             | **** |=======|
  /___/___\___\                         o  | **** |=======|
  |            |                     ___|  |==============|
  |           |                ___  {(__)} |==============|
  \-----------/             [](   )={(oo)} |==============|
   \  \   /  /             /---===--{ \/ } |
-----------------         / | NASA  |====  |
|               |        *  ||------||-----^
-----------------           ||      |      |
  /    /  \   \             ^^      ^      |
 /     ----    \
  ^^         ^^           This cow jumped over the Moon

Wasm Swift running within a Swift host.

Closing Notes

All that technology, while in development for years, still seems very early. It is quite interesting and - if anything - a fun toy to play with!

It is definitely worth watching where this technology is going.

When some VC friend asked us what we think of the idea of running server side code using Wasm, we gave him like a set of reasons why this is utter nonsense. Except maybe for edgy edge cases. But we also pointed out that the JVM is big on the server, despite being invented for set-top boxes and phones.
So I guess we’ll see whether this is the next big thing after Docker 😉

Pro tip: To troll Wasm evangelists/fanboys, always use “WASM” (all uppercase) and “Web Assembly” (w/ a space) when referring to the technology. That’s always a winner.

What’s Missing in SwiftyWasmer

Quite a few things, an imcomplete list:

Import objects do not seem to fully work in the 1.0.0 C API yet, e.g. you can’t configure the WASI environment yet (commandline, env vars, file mappings).
The 1.0.0 C API also seems to have issues with executing different WASI versions, though we may be just holding it wrong
There is no neat way in SwiftyWasmer yet to export functions to Wasmer (the ABI is a little unfortunate the integrate other languages),
Many other things :-)

Contact

Feedback is warmly welcome: @helje5, me@helgehess.eu.

Want to support my work? Buy an app! You don’t have to use it! 😀

Helge Heß

@Model for CoreData

TL;DR

A Little Bit of History

SwiftData

ManagedModels

Differences to SwiftData

Explicit Superclass

@FetchRequest instead of @Query

Properties

Initializers

Example App

Northwind

Internals

Closing Notes

Links

Contact

The Lighter Swift Codegen for SQLite3

Overview

Small Example Database (stored in either a SQLite db or created from .sql files):

How does the code generation work?

Accessing a database using the higher level Lighter API

Dependency free SQLite3 API

Beautiful, autogenerated DocC API Comments

Who

Flutter for SwiftUI Developers (and 🔄)

Introduction

Setup

Basic Concepts

Comparing the HelloWorld App

App Setup

MyHomePage Top Level Widget

State

Page Layout

Intermission: Things that are great in Flutter.

Dart and Swift

Packages

Multiple Files in your Package

Platform Widgets

Advanced State Management

Navigation

Small Web Service App

Closing Notes

Links

Contact

Model View Controller for SwiftUI

The Problem

Master Detail

A Solution: Model View Controller

ViewController

NavigationController

Notes

Closing Notes

Links

Contact

🐮 iOS App w/ VisualStudio Code. Or not?

Installing VisualStudio Code w/ Swift

Setting up the App Package and Build

Running the App in the Simulator

🐮 A Cowtastic App 🐮

Closing Notes

Links

Contact

🐮 SwiftUI Tools w/ VisualStudio Code

Installing VisualStudio Code w/ Swift

Setting up the SwiftPM Boilerplate

Fixing the App Activation

🐮 A Cowtastic App 🐮

Closing Notes

Links

Contact

🐮 SwiftUI Tools w/ just SwiftPM

Setting up the SwiftPM Boilerplate

Fixing the App Activation

A Cowtastic App

Closing Notes

Links

Contact

DocC 📚 Archived and Analyzed

DocC Quick Usage Intro