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

> Learn how to build vorssaint-utils without Xcode using our complete CLI guide. Compile the Swift package directly with build.sh and swiftc for a streamlined development workflow.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-08

---

**You can build vorssaint-utils on macOS using only the Xcode Command-Line Tools and the provided [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```bash
xcode-select --install

```

Verify installation by checking that `swiftc` is available:

```bash
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)](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)](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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift)), now-playing XPC service ([`Sources/NowPlayingAdapter/NowPlayingAdapter.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/NowPlayingAdapter/NowPlayingAdapter.swift)), and icon generator ([`Tools/MakeIcon.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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**

   ```bash
   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`:

   ```bash
   ./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

   ```bash
   open build/stage/Vorssaint.app
   ```

## Build Options and Variants

The [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```bash
./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:

```bash
./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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)](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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/./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.