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.

Initial DocC pass

Kabir Oberaiadb1a7c643b0
diff --git a/Sources/SupersignCLI/Documentation.docc/Documentation.md b/Sources/SupersignCLI/Documentation.docc/Documentation.md
new file mode 100644
index 0000000..4f7bb24
--- /dev/null
+++ b/Sources/SupersignCLI/Documentation.docc/Documentation.md
@@ -0,0 +1,20 @@
+# ``SupersignCLI``
+
+The `supersign` command line interface (CLI).
+
+## Overview
+
+You can use `supersign` to interact with iOS applications and Apple Developer Services, including
+
+- Building a Swift Package into an iOS app on **macOS or Linux**.
+- Managing Codesigning Certificates, Devices, App Identifiers, and Provisioning Profiles across both free and paid Apple Developer accounts.
+- Codesigning a `.ipa`.
+- Installing a `.ipa` on your iOS device.
+
+## Topics
+
+### Getting Started
+
+- <doc:Installation-Linux>
+- <doc:Installation-macOS>
+- <doc:First-app>
diff --git a/Sources/SupersignCLI/Documentation.docc/First-app.md b/Sources/SupersignCLI/Documentation.docc/First-app.md
new file mode 100644
index 0000000..62d7881
--- /dev/null
+++ b/Sources/SupersignCLI/Documentation.docc/First-app.md
@@ -0,0 +1,141 @@
+# Build Your First iOS App on Linux
+
+Use Supersign to build and deploy an iOS app from your Linux machine.
+
+## Prerequisites
+
+First, make sure you've set up Supersign. Follow the steps in <doc:Installation-Linux> or <doc:Installation-macOS>.
+
+## Overview
+
+Once you've set up Supersign, you can use it to build, package, and install iOS apps from either Linux or macOS.
+
+When building an iOS app on Linux, Supersign instructs SwiftPM to use the [Swift SDK for Cross Compilation](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) that we built during the setup process; specifically, `arm64-apple-ios` from `darwin.artifactbundle`. This SDK contains the necessary modules for building iOS apps, such as UIKit and SwiftUI, as well as tools for building and manipulating iOS binaries. Swift SDKs are quite powerful, and you may want to check out the documentation to better understand how they work.
+
+## Steps
+
+### 1. Create an iOS-capable Swift Package
+
+Supersign comes with a template for iOS-capable Swift Packages. To create a new package, run
+
+```bash
+supersign dev new Hello
+# Creating package: Hello
+# Creating Package.swift
+# Creating supersign.yml
+# Creating .gitignore
+# Creating .sourcekit-lsp/config.json
+# Creating Sources/Hello/HelloApp.swift
+# Creating Sources/Hello/ContentView.swift
+#
+# Finished generating project Hello.
+
+cd Hello
+```
+
+At this point, feel free to poke around. The package is structured just like a regular SwiftPM library, with the addition of two files:
+
+- `supersign.yml`: This file describes how to bundle the Swift library into an iOS app. At minimum, you need to provide a Bundle ID. This defaults to `com.example.<PackageName>`, in this case `com.example.Hello`.
+- `.sourcekit-lsp/config.json`: This file tells SourceKit to use the `arm64-apple-ios` Swift SDK. This allows IDEs like Visual Studio Code to understand how the package is built, and provide contextual IntelliSense/autocomplete suggestions related to iOS.
+
+## 2. Build and install the app
+
+From inside the package directory, run
+
+```bash
+supersign dev
+# Planning...
+# Building for debugging...
+# [8/8] Linking Hello-App
+# Build of product 'Hello-App' complete! (4.94s)
+```
+
+The first time you run this, SwiftPM might take a few minutes to build the app. This is because it needs to build the Swift Modules for the iOS SDK. Subsequent runs should be a lot faster since SwiftPM caches these modules globally.
+
+After the build is complete, Supersign will attempt to install it on your device. You should see a line like
+
+```bash
+# Waiting for device to be connected...
+```
+
+At this point, connect your iOS device to your computer via USB. If you installed `libimobiledevice-utils` during setup, you can verify that your device is connected by running `ideviceinfo`. Supersign will continue after automatically detecting that your device is connected.
+
+> Pairing:
+>
+> The first time you run `supersign dev`, you may see a "Trust" dialog on your iOS device to proceed with pairing. Tap **Trust** and enter your passcode on iOS. Supersign may throw an error after this: if so, just run `supersign dev` again.
+
+Supersign will now connect to Apple Developer Services, register your device with your Apple ID, generate a Certificate + App ID + Provisioning Profile, sign the app, and then install it.
+
+```bash
+# Installing to device: Kabir's iPhone (udid: *****)
+#
+# [Unpacking app] 100%
+# [Logging in] 100%
+# [Preparing device] 100%
+# [Provisioning] 100%
+# [Signing] 100%
+# [Packaging] 100%
+# [Connecting] 100%
+# [Installing] 100%
+# [Verifying] 100%
+```
+
+> Enable Development Mode:
+>
+> At this point, you may run into an error asking you to enable **Development Mode** on your iOS device. Follow [these instructions](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) and then run `supersign dev` again.
+
+## 3. Run the app
+
+You should now see the app on your iOS device's home screen / App Library. Tap it to launch the app. You should see a "Hello World" message!
+
+> Trust Your Certificate:
+>
+> The first time you launch the app, you might get an "Untrusted Developer" alert. To trust your developer identity, go to **Settings** > **General** > **VPN & Device Management** > _[your email]_ > **Trust**. You should now be able to launch the app.
+
+@Row(numberOfColumns: 2) {
+ @Column {
+ ![Hello world app](HelloWorld)
+ }
+}
+
+## 4. Edit the app
+
+Open the project folder in your favorite IDE. As long as it supports Swift [via SourceKit-LSP](https://github.com/swiftlang/sourcekit-lsp/blob/242609dcad55824d9eb23269c0aeead187fd0faa/Documentation/Editor%20Integration.md), it should be able to understand your iOS project thanks to the `.sourcekit-lsp/config.json` file in the template.
+
+For example, if you're using Visual Studio Code, this means you need to install the [Swift extension](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode).
+
+In `Sources/Hello/ContentView.swift`, let's update the "Hello, world!" text to be bold and purple:
+
+```diff
+ import SwiftUI
+
+ struct ContentView: View {
+ var body: some View {
+ VStack {
+ Image(systemName: "globe")
+ .imageScale(.large)
+ .foregroundStyle(.tint)
+ Text("Hello, world!")
++ .bold()
++ .foregroundStyle(.purple)
+ }
+ .padding()
+ }
+ }
+```
+
+While you do this, if you've correctly configured your editor with Swift support you should receive intelligent autocomplete suggestions.
+
+![Autocomplete](Autocomplete)
+
+## 5. Re-install the app
+
+Run `supersign dev` again to re-build and re-install. This should go a lot faster than the first time.
+
+Launch the app again to see the updated text!
+
+@Row(numberOfColumns: 2) {
+ @Column {
+ ![Modified hello world app](HelloWorld-Purple)
+ }
+}
diff --git a/Sources/SupersignCLI/Documentation.docc/Installation-Linux.md b/Sources/SupersignCLI/Documentation.docc/Installation-Linux.md
new file mode 100644
index 0000000..42d3a33
--- /dev/null
+++ b/Sources/SupersignCLI/Documentation.docc/Installation-Linux.md
@@ -0,0 +1,110 @@
+# Installation (Linux)
+
+Set up Supersign for iOS app development on Linux.
+
+## Overview
+
+This article outlines the steps to install `supersign` and begin developing iOS apps on Linux.
+
+## Steps
+
+### 1. Install Swift
+
+First, install the latest Swift toolchain for your Linux distribution from <https://swift.org/install/linux>.
+
+
+After following the steps there, confirm that Swift is installed correctly:
+
+```bash
+swift --version
+# should say something like:
+# Swift version 6.1 (swift-6.1-RELEASE)
+```
+
+### 2. Install libimobiledevice
+
+Supersign relies on [libimobiledevice](https://libimobiledevice.org), or more specifically its [usbmuxd](https://github.com/libimobiledevice/usbmuxd) subproject, to talk to your iOS device from Linux.
+
+Your Linux distro probably comes with a `usbmuxd` package, and it may be pre-installed. To check if it is, run:
+
+```bash
+file /var/run/usbmuxd
+# /var/run/usbmuxd: socket
+```
+
+If you instead get a "No such file or directory" error, you need to install `usbmuxd` yourself. On Ubuntu, for example, you can do this with
+
+```bash
+sudo apt-get install \
+ usbmuxd libimobiledevice6 libimobiledevice-utils
+```
+
+`libimobiledevice6` and `libimobiledevice-utils` aren't strictly needed but they provide tools like `ideviceinfo` that may be useful for interacting with other aspects of your iOS device.
+
+### 3. Download Supersign
+
+Next, download the [latest GitHub Release](https://github.com/SuperchargeApp/Supersign/releases/latest) of `Supersign.AppImage` for your architecture. Rename it to `supersign` and add it to a location in your `PATH`.
+
+```bash
+curl -fL \
+ "https://github.com/SuperchargeApp/Supersign/releases/latest/download/Supersign-$(uname -m).AppImage" \
+ -o supersign
+chmod +x supersign
+sudo mv supersign /usr/local/bin/
+```
+
+Confirm that Supersign is installed correctly:
+
+```bash
+supersign --help
+# OVERVIEW: The Supersign command line tool
+# ...
+```
+
+### 4. Download Xcode.xip
+
+From <http://developer.apple.com/download/all/?q=Xcode>, download **Xcode 16.3**. Note the path where `Xcode_16.3.xip` is saved.
+
+### 5. Configure Supersign
+
+Perform one-time setup with
+
+```bash
+supersign dev setup
+```
+
+You'll first be asked to log in:
+
+```
+Select login mode
+0: API Key (requires paid Apple Developer Program membership)
+1: Password (works with any Apple ID but uses private APIs)
+Choice (0-1):
+```
+
+> Choosing a login mode:
+>
+> **API Key:** If you have a paid [Apple Developer Program](https://developer.apple.com/programs/enroll/) membership, this is the recommended option. It relies on the public App Store Connect API. You'll want to follow the [instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api) to generate a **Team Key** with the **App Manager** role.
+>
+> **Password:** If you aren't enrolled in the paid developer program, you'll want to use password-based authentication. This relies on private Apple APIs to authenticate, so you may want to create a throwaway Apple ID to be extra cautious.
+
+Once you select a login mode, you'll be asked to provide the corresponding credentials (API key or email+password+2FA). Needless to say, *your credentials are only sent to Apple* and nobody else (feel free to build Supersign from source and check!)
+
+After you're logged in, you'll be asked to provide the path to the `Xcode.xip` file you downloaded earlier.
+
+```
+Path to Xcode.xip:
+```
+
+Enter the path (for example `~/Downloads/Xcode_16.3.xip`) and hit enter. Supersign will extract the Xcode XIP to generate and install an iOS Swift SDK for you.
+
+Confirm that it worked:
+
+```bash
+swift sdk list
+# darwin
+```
+
+## Next Steps
+
+You're now ready to use Supersign! See <doc:First-app>.
diff --git a/Sources/SupersignCLI/Documentation.docc/Installation-macOS.md b/Sources/SupersignCLI/Documentation.docc/Installation-macOS.md
new file mode 100644
index 0000000..2059c4c
--- /dev/null
+++ b/Sources/SupersignCLI/Documentation.docc/Installation-macOS.md
@@ -0,0 +1,7 @@
+# Installation (macOS)
+
+Set up Supersign for declarative, Xcode-free iOS app development on macOS.
+
+## Overview
+
+TBD
diff --git a/Sources/SupersignCLI/Documentation.docc/Resources/Autocomplete.png b/Sources/SupersignCLI/Documentation.docc/Resources/Autocomplete.png
new file mode 100644
index 0000000..0308c01
Binary files /dev/null and b/Sources/SupersignCLI/Documentation.docc/Resources/Autocomplete.png differ
diff --git a/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld-Purple.png b/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld-Purple.png
new file mode 100644
index 0000000..ce7dbff
Binary files /dev/null and b/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld-Purple.png differ
diff --git a/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld.png b/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld.png
new file mode 100644
index 0000000..ed993dd
Binary files /dev/null and b/Sources/SupersignCLI/Documentation.docc/Resources/HelloWorld.png differ
diff --git a/Sources/SupersignCLI/SupersignCLI.swift b/Sources/SupersignCLI/SupersignCLI.swift
index df3234f..fe75985 100644
--- a/Sources/SupersignCLI/SupersignCLI.swift
+++ b/Sources/SupersignCLI/SupersignCLI.swift
@@ -3,7 +3,9 @@ import Supersign
import SupersignCLISupport
import Dependencies
-@main enum SupersignCLIMain {
+@_documentation(visibility: private)
+@main
+enum SupersignCLIMain {
static func main() async throws {
prepareDependencies { dependencies in
#warning("Improve persistence mechanism")