Skip to content

armgit / xtool

Public Imported from GitHub
0

Cross-platform Xcode replacement. Build and deploy iOS apps with SwiftPM on Linux, Windows, macOS.

Docs on creating App Extensions (#139)

Kabir Oberai0a3c135b6fee
diff --git a/Documentation/xtool.docc/Appex.md b/Documentation/xtool.docc/Appex.md
new file mode 100644
index 0000000..db282ba
--- /dev/null
+++ b/Documentation/xtool.docc/Appex.md
@@ -0,0 +1,143 @@
+# Create App Extensions
+
+Add app extensions to your iOS app.
+
+## Overview
+
+iOS includes several [App Extension Points](https://developer.apple.com/documentation/technologyoverviews/app-extensions) to deeply integrate with system functionality: such as Widgets, Share Extensions, and Safari Extensions. With a little setup, you can create App Extensions with xtool.
+
+This guide will show you how to add a **Widget Extension** to your app. The steps are similar for other extensions as well.
+
+> Note: This guide assumes you already have an xtool-based application up and running. If you don't, create one first with <doc:First-app>.
+
+## Step 1: Add a new product
+
+Start by adding a new product declaration to your `Package.swift`.
+
+```diff
+ // swift-tools-version: 6.0
+
+ import PackageDescription
+
+ let package = Package(
+ name: "Hello",
+ platforms: [.iOS(.v17)],
+ products: [
+ .library(
+ name: "Hello",
+ targets: ["Hello"]
+ ),
++ .library(
++ name: "HelloWidget",
++ targets: ["HelloWidget"]
++ ),
+ ],
+ targets: [
+ .target(name: "Hello"),
++ .target(name: "HelloWidget"),
+ ]
+ )
+```
+
+## Step 2: Update xtool.yml
+
+Now that we have two products, we'll need to tell xtool which one corresponds to the _application_ and which one corresponds to the _extension_.
+
+You should already have a bare-bones `xtool.yml` file that describes metadata about your package (the bundle ID, at the bare minimum.) We'll add the new information to this file.
+
+```diff
+ version: 1
+ bundleID: com.example.Hello
++ product: Hello
++ extensions:
++ - product: HelloWidget
++ infoPath: HelloWidget-Info.plist
+```
+
+## Step 3: Add an Info.plist
+
+App extensions require an `Info.plist` file that tells the system what kind of extension they are, amongst other things. In the previous step, we promised xtool that this file will be located at `./HelloWidget-Info.plist` in your project. We'll now create this file.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>NSExtension</key>
+ <dict>
+ <key>NSExtensionPointIdentifier</key>
+ <string>com.apple.widgetkit-extension</string>
+ </dict>
+</dict>
+</plist>
+```
+
+> Note:
+>
+> The value `com.apple.widgetkit-extension` tells the system that this is a Widget Extension. If you're creating a different type of Extension, your `Info.plist` might look different.
+>
+> For a list of possible `NSExtensionPointIdentifier` values, see [Apple's documentation](https://developer.apple.com/documentation/bundleresources/information-property-list/nsextension/nsextensionpointidentifier) on the subject. You may also need other keys like `NSExtensionPrincipalClass`: refer to Apple's ~better~ legacy [documentation library](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/AppExtensionKeys.html) for details.
+>
+> Finally, note that the above refers to the old paradigm of **Foundation Extensions**. Apple has started moving towards a newer framework called **ExtensionKit** for recent extension types. The main difference for extension consumers is that you replace `NSExtension -> EXAppExtensionAttributes`, and `NSExtensionPointIdentifier -> EXExtensionPointIdentifier`. xtool doesn't support ExtensionKit yet, but it's [planned](https://github.com/xtool-org/xtool/issues/138).
+
+## Step 4: Code your widget
+
+We can finally write the code for the widget. Create a new file at `Sources/HelloWidget/Widget.swift` with these contents:
+
+```swift
+import WidgetKit
+import SwiftUI
+
+@main struct Bundle: WidgetBundle {
+ var body: some Widget {
+ HelloWidget()
+ }
+}
+
+struct HelloWidget: Widget {
+ var body: some WidgetConfiguration {
+ StaticConfiguration(
+ kind: "HelloWidget",
+ provider: Provider()
+ ) { entry in
+ VStack {
+ Text(entry.date, style: .date)
+ }
+ .containerBackground(.fill.tertiary, for: .widget)
+ }
+ .configurationDisplayName("HelloWidget")
+ .description("This is an example widget.")
+ }
+
+ struct Entry: TimelineEntry {
+ var date = Date()
+ }
+
+ struct Provider: TimelineProvider {
+ func placeholder(in context: Context) -> Entry {
+ Entry()
+ }
+
+ func getSnapshot(
+ in context: Context,
+ completion: @escaping (Entry) -> Void
+ ) {
+ completion(Entry())
+ }
+
+ func getTimeline(
+ in context: Context,
+ completion: @escaping (Timeline<Entry>) -> Void
+ ) {
+ completion(Timeline(
+ entries: [Entry()],
+ policy: .after(.now + 3600)
+ ))
+ }
+ }
+}
+```
+
+> Note: Blindly refreshing once an hour isn't a great strategy in practice but it makes for a short snippet. I never said this was a tutorial on writing _good_ WidgetKit code; there's plenty of other resources online if that's your goal, including Apple's own [documentation](https://developer.apple.com/documentation/widgetkit).
+
+Finally, build and run with `xtool dev`. You should be able to locate the widget in your widget library and add it to your home screen!
diff --git a/Documentation/xtool.docc/xtool.md b/Documentation/xtool.docc/xtool.md
index 1dcda6f..fea4352 100644
--- a/Documentation/xtool.docc/xtool.md
+++ b/Documentation/xtool.docc/xtool.md
@@ -31,3 +31,4 @@ xtool is a cross-platform (Linux/WSL/macOS) tool that replicates Xcode functiona
### Common tasks
- <doc:Control>
+- <doc:Appex>