How to Build vorssaint-utils Without Xcode: Complete CLI Guide

You can build vorssaint-utils on macOS using only the Xcode Command-Line Tools and the provided build.sh script, which invokes swiftc directly to compile the Swift package without opening the Xcode IDE.

vorssaint-utils is a pure-Swift macOS utility project hosted at vorssaint/vorssaint-utils. While it includes a standard Swift Package Manager structure defined in Package.swift, the repository ships with a self-contained build script that eliminates the need for the full Xcode application. This makes it possible to build vorssaint-utils without Xcode using only freely available command-line tools.

Prerequisites: Command-Line Tools Only

To build vorssaint-utils without Xcode, you only need the Xcode Command-Line Tools (CLT) installed. These provide the Swift compiler (swiftc), SDK location utilities (xcrun), and code signing tools (codesign) that the build script requires.

Install the tools by running:

xcode-select --install

Verify installation by checking that swiftc is available:

swiftc --version

Understanding the Build Architecture

The project uses a hybrid Swift Package Manager and custom script approach. According to the source code, the [Package.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) defines the package structure targeting macOS 14+, including two system-library targets (HIDEventSystem and VMStatisticsCompat) and one executable target (Vorssaint).

However, the actual compilation orchestration happens in [build.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) at the repository root. This script handles:

• SDK Detection – Prefers the macOS 26 SDK if present, otherwise defaults to xcrun --show-sdk-path
• Direct Compilation – Invokes swiftc with specific target triples (arm64-apple-macosx14.0) and optimization flags (-O for release, -Onone for development)
• Auxiliary Binaries – Builds the fan-control helper (Sources/FanControlHelper/main.swift), now-playing XPC service (Sources/NowPlayingAdapter/NowPlayingAdapter.swift), and icon generator (Tools/MakeIcon.swift)
• Bundle Assembly – Constructs the .app bundle structure using ditto and plutil
• Code Signing – Attempts Developer ID first, then falls back to ad-hoc signing

Step-by-Step: Build vorssaint-utils Without Xcode

Follow these steps to compile the project entirely from the terminal:

1. Clone the repository

   git clone https://github.com/vorssaint/vorssaint-utils.git
   cd vorssaint-utils

2. Execute the build script

   The default invocation creates a release-optimized bundle in build/stage:

   ./build.sh

   During execution, the script performs these actions:

   • Compiles the main executable to build/Vorssaint
   • Builds the fan-control helper to build/com.vorssaint.utils.fan-control
   • Generates the now-playing library to build/libVorssaintNowPlaying.dylib
   • Creates the adaptive app icon using Tools/MakeIcon.swift → build/AppIcon.icns
   • Assembles the final bundle at build/stage/Vorssaint.app
   • Signs the bundle (ad-hoc if no Developer ID is present)

3. Run the application

   Launch the freshly built app without installing it system-wide:

   open build/stage/Vorssaint.app

Build Options and Variants

The build.sh script supports several flags to customize the build vorssaint-utils without Xcode for different scenarios:

Install System-Wide

To replace any existing installation in /Applications and restart the service:

./build.sh --install

This command stops running instances using the bundle identifier, copies the new bundle to /Applications, and re-signs it after the copy operation using the available identity.

Development Build

Create a parallel "Developer" build that coexists with the stable release by using the --dev flag:

./build.sh --dev

This variant modifies the bundle identifier in Resources/Info.plist, changes the executable name, and embeds the current Git commit hash, allowing you to test changes without affecting your production installation.

Technical Implementation Details

When you run build.sh, the script executes a specific compilation pipeline defined in the source code:

SDK Resolution – The script queries the SDK path using xcrun --show-sdk-path to ensure compatibility with macOS 14.0+ (arm64-apple-macosx14.0).

Compiler Flags – The script passes include paths for system library headers:

• -I Sources/VMStatisticsCompat
• -I Sources/HIDEventSystem

Code Signing Strategy – According to the implementation in build.sh, the script attempts three signing methods in order:

1. Developer ID identity (for distribution)
2. Legacy self-signed identity
3. Ad-hoc signing (for local builds)

If no suitable identity exists, the script can generate a stable local signing identity via [Tools/setup-signing.sh](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh).

Source Organization – Production code resides in Sources/Vorssaint/**/*.swift, while helper binaries compile from separate entry points to create the complete utility suite.

Summary

• vorssaint-utils requires only the Xcode Command-Line Tools, not the full Xcode IDE, thanks to the custom build.sh script.
• The build process uses direct swiftc invocation with xcrun for SDK detection, compiling both the main executable and auxiliary XPC services.
• Run ./build.sh to create a release bundle in build/stage/Vorssaint.app.
• Use ./build.sh --install to deploy to /Applications or ./build.sh --dev for side-by-side development builds.
• All build steps rely on standard Unix utilities (ditto, plutil, codesign) available in the Command-Line Tools.

Frequently Asked Questions

Do I need the full Xcode application to build vorssaint-utils?

No. The repository is specifically designed to build vorssaint-utils without Xcode using only the Command-Line Tools. The build.sh script handles compilation directly via swiftc and xcrun, requiring no IDE interaction or .xcodeproj files.

Which macOS versions are supported?

According to Package.swift in the repository root, the project targets macOS 14.0 and later. The build script uses the arm64-apple-macosx14.0 target triple and detects the appropriate SDK using xcrun --show-sdk-path, ensuring compatibility with macOS 14 and newer systems.

What if code signing fails during the build?

The script implements a three-tier fallback strategy: it first tries Developer ID, then legacy self-signed identities, and finally ad-hoc signing. If all methods fail, run Tools/setup-signing.sh to create a stable local signing identity specifically for development builds.

Can I run the app without installing it to /Applications?

Yes. After running ./build.sh, you can launch the application directly from the build directory with open build/stage/Vorssaint.app. The --install flag is only required if you want the utility available system-wide in your Applications folder.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}