### Install Swift Bundler using Mint (macOS/Linux)

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Installs the latest version of Swift Bundler directly from the main branch using Mint. Ensure you have Mint installed.

```sh
mint install stackotter/swift-bundler@main
```

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

### Install Swift Bundler Pre-built (macOS)

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Downloads a universal build of Swift Bundler from releases, makes it executable, and moves it to /usr/local/bin. Replace X.X.X with the desired version.

```sh
# Replace X.X.X with desired version
curl -O https://github.com/moreSwift/swift-bundler/releases/download/vX.X.X/swift-bundler
chmod +x ./swift-bundler
sudo mv ./swift-bundler /usr/local/bin/
```

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

### Example Swift Bundler Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

This TOML snippet demonstrates a comprehensive configuration for a Swift Bundler application, including app metadata, dependencies, and Info.plist overrides.

```toml
format_version = 2

# `HelloWorld` here is the app's name. Use double quotes if your app's name
# contains special characters such as spaces.
[apps.HelloWorld]
# The app's identifier, used by bundlers which require reverse domain name
# identifiers.
identifier = "com.example.HelloWorld"
# The SwiftPM package executable product to bundle
product = "HelloWorld"
# The app's version. Displayed on macOS's automatic 'About HelloWorld' screen.
version = "0.1.0"
# The app's description. Displayed by some package managers.
description = "A basic app."
# The license used by the app. Using SPDX identifiers is recommended.
license = "MIT"
# Only used by the Darwin bundler at the moment. Corresponds to Apple's category
# identifiers. See https://developer.apple.com/documentation/bundleresources/information-property-list/lsapplicationcategorytype
category = "public.app-category.education" # Optional
# The app's icon.
# Can be any of the following formats:
# - 1024x1024px PNG file (`.png`)
# - ICNS file (`.icns`) (Apple platforms only)
# - Icon Composer file (`.icon`) (Apple platforms only)
icon = "icon.png" # Optional
# Custom URL schemes supported by the app (for deep linking). Swift Bundler
# sets up the required metadata to get such URL schemes redirected to your
# app. It's up to your app to handle the different ways that platforms deliver
# custom URL events, or to use a cross platform framework such as SwiftCrossUI
# that can handle those differences on your behalf.
url_schemes = ["hello"]
# Build dependencies (outside of those handled by SwiftPM). Dependencies without
# dots are interpreted as executable products to include from the root SwiftPM
# package as helper executables (placed next to the main executable). Dependencies
# with a dot are interpreted as either library or executable products to include
# from a subproject. This allows pulling cmake dependencies into Swift Bundler
# projects. This is often used to pull in libsentry. Pulling in external library
# products requires that your app imports a SwiftPM library target/product
# containing a 'module.modulemap' instructing SwiftPM what to link against.
# See https://github.com/moreSwift/swift-bundler/tree/main/Tests/SwiftBundlerTests/Fixtures/MakefileBuilder
# for a working example.
dependencies = ["Updater", "cmakeproj.hello"]

# Extra entries for your app's Info.plist file. Currently has no effect on
# Linux.
[apps.HelloWorld.plist]
# This could be any key-value pair, `CFBundleShortVersionString` is just an
# example. Patterns of the form `$(...)` get replaced with their corresponding
# values. See 'Variable substitutions' below.
CFBundleShortVersionString = "$(VERSION)_$(COMMIT_HASH)"

# Define platform-specific or bundler-specific configuration properties using
# conditional overlays.
[[apps.HelloWorld.overlays]]
condition = "platform(linux)"
# Generate a D-Bus service file for the app. This allows the app to handle URL
# schemes.
dbus_activatable = true
# You can also use overlays to provide platform-specific overrides for general
# configuration properties.
url_schemes = ["hello", "hello-linux"]

[[apps.HelloWorld.overlays]]
condition = "bundler(linuxRPM)"
# Specify external packages required by the app. This property is currently
# only available when using the linuxRPM bundler.
requirements = ["gtk3"]

[[apps.HelloWorld.overlays]]
condition = "platform(macCatalyst)"
# Specify the interface idiom used by the app when run under Mac Catalyst.
# Respected by UIKit. Value must be `ipad` (Scaled to Match iPad) or `mac`
# (Optimize for Mac).
interface_idiom = "mac"

# Subprojects are dependencies or constituent parts of a project that fall
# outside of the reign of SwiftPM. They can use custom builders and can build
# from either local or git sources.
[projects.cmakeproj]
# The subprojects source directory. Can be `local(...)` (a path) or
# `git(...)` (a git url). When using a `git` source, you must specify a
# revision via the separate `revision` config property.
source = "local(./cmakeproj)"
# Builder to use when building products of the project
builder = "CMakeBuilder"

# Projects can define as many products as they want. Library products are built
# and inserted into SwiftPM's build directory so that they can be found when
# the app's product gets built. All you need to do is include the header in your
# product and Swift Bundler makes sure that the linking just works. Executable
# products get included as helper executables next to the main executable
# (regardless of bundler). Overlays can be used to override `type` and
# `output_directory` depending on platform (see the overlay example for the
# HelloWorld app above).
[projects.cmakeproj.products.hello]

```

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

### Install patchelf on Debian/Ubuntu

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Installs the patchelf utility, which is required for dynamic library relocation during bundling on Linux.

```sh
sudo apt install patchelf
```

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

### Manual Installation of Swift Bundler

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Clones the repository, builds the release version of Swift Bundler, and copies the executable to a directory in your PATH. The SBUN_NO_SCHEMA_GEN environment variable can speed up builds.

```sh
git clone https://github.com/moreSwift/swift-bundler
cd swift-bundler

SBUN_NO_SCHEMA_GEN=1 swift build -c release
cp .build/release/swift-bundler /path/to/bin/
```

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

### Verify Swift Bundler Installation

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Checks the installed version of Swift Bundler after manual or pre-built installation.

```sh
swift bundler --version
```

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

### Install patchelf on Fedora

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Installs the patchelf utility on Fedora systems.

```sh
sudo dnf install patchelf
```

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

### Swift Builder Implementation

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Example implementation of a custom builder in Swift, using context to run CMake commands.

```swift
import SwiftBundlerBuilders

@main struct CMakeBuilder: Builder {
    static func build(_ context: some BuilderContext) async throws -> BuilderResult {
        try await context.run(
            "cmake",
            ["-B", context.buildDirectory.path]
        )
        try await context.run(
            "cmake",
            ["--build", context.buildDirectory.path, "--target", "hello"]
        )
        return BuilderResult()
    }
}
```

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

### Install rpmdevtools on Fedora

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Installs rpmdevtools, which includes rpmbuild for RPM bundling on Fedora systems.

```sh
sudo dnf install rpmdevtools
```

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

### Example Usage of withFixture

Source: https://github.com/moreswift/swift-bundler/blob/main/CONTRIBUTING.md

Demonstrates how to use the `withFixture` helper function to run Swift Bundler with a specific test fixture. The helper creates a temporary copy of the fixture and ensures a symlink to the Swift Bundler checkout is available.

```swift
withFixture("YourFixtureSubdirectoryName") { fixture in
  await SwiftBundler.main(["run", "-d", fixture.path])
}
```

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

### Install rpmbuild on Debian/Ubuntu

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/installation.md

Installs the rpm package, which provides rpmbuild for RPM bundling on Debian-based systems.

```sh
sudo apt install rpm
```

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

### Get Information About a Specific Template

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/package-templates.md

To understand the structure and purpose of a particular template, use this command. Replace `[template]` with the name of the template you are interested in.

```sh
swift bundler templates info [template]
```

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

### Create a New App from SwiftUI Template

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Use this command to initialize a new project using the SwiftUI template. Navigate into the newly created project directory afterwards.

```sh
swift bundler create HelloWorld --template SwiftUI
cd HelloWorld
```

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

### Build and Run the App

Source: https://github.com/moreswift/swift-bundler/blob/main/README.md

Build and run the current Swift Bundler application. This command compiles and launches your app.

```bash
# Build and run the app.
swift bundler run
```

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

### Generate Xcode Support Files

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Run this command to create the necessary files for using Xcode as your IDE. This command only needs to be executed once unless the .swiftpm directory is deleted.

```sh
swift bundler generate-xcode-support
```

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

### Run the App Locally

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Build and execute your application using the 'run' command. This is useful for local development and testing.

```sh
swift bundler run
```

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

### Create a New SwiftUI App

Source: https://github.com/moreswift/swift-bundler/blob/main/README.md

Create a new Swift Bundler project using the SwiftUI template. Navigate into the newly created project directory.

```bash
# Create a new app from the SwiftUI template.
swift bundler create HelloWorld --template SwiftUI
cd HelloWorld
```

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

### Basic Bundler Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Defines the product type and output directory for a Swift Bundler project.

```toml
type = "dynamicLibrary"
output_directory = "."
```

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

### Open Package in Xcode

Source: https://github.com/moreswift/swift-bundler/blob/main/README.md

Open the Swift Bundler project's Package.swift file in Xcode to begin development.

```bash
# Open the package in Xcode
open Package.swift
```

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

### List Available Package Templates

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/package-templates.md

Use this command to see all the package templates that Swift Bundler provides by default. This helps you choose the right template for your new project.

```sh
swift bundler templates list
```

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

### Bundle App for Distribution

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Create a distributable app bundle using the 'bundle' command. For macOS, it's recommended to use '-c release -u' for an optimized universal binary.

```sh
swift bundler bundle -c release
```

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

### Create a New Package from a Template

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/package-templates.md

Generate a new project using a chosen template. You need to specify the application name, a unique identifier, and the template name.

```sh
swift bundler create [app-name] --identifier [app-identifier] --template [template]
```

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

### Create Project with Custom Template

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/custom-templates.md

Use the `swift bundler create` command to generate a new project using a custom template. Specify the project name, identifier, template name, and the path to your template repository.

```sh
swift bundler create MyApp --identifier com.example.MyApp --template MyTemplate --template-repository /path/to/TemplateRepository
```

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

### Configure Multiple Apps in Swift Package

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Define multiple applications within a single Swift package using TOML configuration. Each app requires an identifier, product name, and version.

```toml
[apps.Example]
identifier = "com.example.Example"
product = "Example"
version = "0.1.0"

[apps.Updater]
identifier = "com.example.Updater"
product = "Updater"
version = "1.0.1"
```

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

### Generate Xcode Support Files

Source: https://github.com/moreswift/swift-bundler/blob/main/README.md

Generate the necessary files for Xcode to recognize and run the Swift Bundler package as an app. This is typically a one-time operation unless the .swiftpm directory is removed.

```bash
# Creates the files necessary to get xcode to run the package as an app.
# Only needs to be run once unless you delete the ".swiftpm" directory.
swift bundler generate-xcode-support
```

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

### Load Metal Shader Library

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/metal-shaders.md

Load a Metal shader library by constructing a custom bundle URL and then finding the .metallib file within it. Replace 'Product_Product' with your app's product name.

```swift
// Replace 'Product_Product' according to the name of your app's product 
guard
  let bundle = Bundle(url: Bundle.main.bundleURL.appendingPathComponent("Contents/Resources/Product_Product.bundle")),
  let libraryURL = bundle.url(forResource: "default", withExtension: "metallib")
else {
  // Handle error
}

let library = try device.makeLibrary(URL: libraryURL)
```

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

### Run App on iOS Simulator

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Specify a target platform and simulator to run your app. If no simulator is specified, Swift Bundler will attempt to use the first compatible booted simulator.

```sh
swift bundler run --platform iOSSimulator --simulator "iPhone 16"
```

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

### Specify App for Swift Bundler Commands

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

When multiple apps are defined, commands like `run` and `bundle` require an app name to specify the target application.

```sh
# Run the main app.
swift bundler run Example
# Run the updater.
swift bundler run Updater
```

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

### Info.plist Customization with Variables

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Customizes the app's Info.plist by appending dynamic values like version and commit hash.

```toml
# ...
[apps.HelloWorld.plist]
CFBundleShortVersionString = "$(VERSION)_$(COMMIT_HASH)"
```

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

### App Icon Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Specifies an app icon file for the application.

```toml
[apps.Example]
icon = "AppIcon.png"
```

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

### Create Universal Binary for macOS

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/creating-an-app.md

Add the '--universal' flag when targeting macOS to generate a build that runs on both arm64 and x86_64 architectures.

```sh
swift bundler bundle --universal
```

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

### Verify App Code Signing and Provisioning Profile

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/troubleshooting.md

Troubleshoot application verification failures on physical devices by checking Info.plist, embedded.mobileprovision, entitlements, and code signing certificates. Ensure consistency across all.

```bash
codesign -dvvvv --extract-certificates path/to/Your.app
```

```bash
codesign -d --entitlements - path/to/Your.app
```

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

### App Icon Overlay Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Applies a platform-specific icon overlay for Apple platforms.

```toml
[[apps.Example.overlays]]
condition = "platform(macOS)"
icon = "AppIcon.icon"
```

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

### Configure Mac Catalyst Interface Idiom

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/mac-catalyst.md

Use a Mac Catalyst specific configuration overlay to set the interface idiom to 'mac'. This option is only available when targeting Mac Catalyst.

```toml
[[apps.YourApp.overlays]]
condition = "platform(macCatalyst)"
interface_idiom = "mac" # default: "ipad"
```

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

### CMake Builder Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Configures a CMake builder for subprojects, specifying the product and kind.

```toml
[builders.CMakeBuilder]
product = "CMakeBuilder"
kind = "wholeProject"
```

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

### Update Default Package Templates

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/package-templates.md

If you encounter issues with templates or want to ensure you have the latest versions, run this command to update the default templates downloaded from the repository.

```sh
swift bundler templates update
```

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

### Template TOML Configuration

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/custom-templates.md

Define the description and supported platforms for your custom template. Adjust platforms to 'macOS' and/or 'iOS' as needed.

```toml
description = "My first package template."
platforms = ["macOS", "iOS"]
```

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

### Add Metal Shaders Directory as Resource

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/metal-shaders.md

Add the directory containing your Metal shaders to the app's target resources in Package.swift. Ensure all shader files are siblings within this directory.

```swift
// ...
resources: [
  .process("Render/Shader/"),
]
// ...
```

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

### TOML Type Disambiguation for Data

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Demonstrates how to disambiguate a TOML value as base64 encoded data.

```toml
MyKey = { type = "data", value = "b3R0ZXIncyBpbiBhIHN0YWNrPw==" }
```

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

### Bundle Identifier Registration Error

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/troubleshooting.md

This error indicates that the chosen bundle identifier is already in use by another developer. To resolve this, change the bundle identifier to a unique string.

```text
The app identifier "xxx.xxxxxx.xxxxxxxxx" cannot be registered to your development team because it is not available. Change your bundle identifier to a unique string to try again.
```

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

### TOML Type Disambiguation for Dictionary

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Demonstrates how to disambiguate a TOML value as a dictionary type.

```toml
MyKey = { type = "dict", value = { type = 1, tag = 0 } }
```

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

### TOML Type Disambiguation for Date

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/configuration.md

Demonstrates how to disambiguate a TOML value as a date type.

```toml
MyKey = { type = "date", value = "2024-12-02T10:08:00Z" }
```

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

### Xcodebuild Error: Developer Disk Image Mount Failure

Source: https://github.com/moreswift/swift-bundler/blob/main/Sources/swift-bundler/SwiftBundler.docc/troubleshooting.md

This error occurs when the developer disk image cannot be mounted on a device, often seen with beta Xcode versions and new devices. Updating to the latest stable Xcode version may resolve this.

```bash
Previous preparation error: The developer disk image could not be mounted on this device.; Error mounting image: 0xe800010f (kAMDMobileImageMounterPersonalizedBundleMissingVariantError: The bundle image is missing the requested variant for this device.)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.