Key Build Artifacts for vorssaint-utils: Complete macOS Build Pipeline

The vorssaint-utils repository produces seven distinct build artifacts: the main executable binary (Vorssaint or VorssaintDeveloper), a privileged fan-control XPC helper, the libVorssaintNowPlaying.dylib dynamic library, compiled AppIcon.icns resources, staged intermediate and final signed .app bundles, and an optional /Applications installer copy.

vorssaint-utils is a macOS-specific Swift utility project distributed as a fully signed application bundle. The build pipeline, orchestrated by the build.sh script at the repository root, compiles multiple specialized binaries and resources into a cohesive distributable product. Understanding these key build artifacts is essential for developers contributing to the codebase, debugging build failures, or creating customized distribution packages.

Main Executable Binary

The primary runtime artifact is the command-line executable produced from all Swift sources under Sources/Vorssaint/**/*.swift. According to the source code in build.sh, the compiler invocation occurs at lines 42‑53, using swiftc to generate either the release Vorssaint binary or the VorssaintDeveloper variant when building with the --dev flag. The entry point resides in Sources/Vorssaint/main.swift, which implements the application's core runtime logic and menu-bar interface.

Privileged Fan-Control Helper

A separate privileged helper binary named <bundle-id>.fan-control (typically com.vorssaint.utils.fan-control) handles low-level system management controller (SMC) access and fan speed control. This component is compiled at lines 61‑70 of build.sh from sources in Sources/FanControlHelper/main.swift. Because it requires elevated privileges to modify hardware settings, this binary runs as a launch daemon and communicates with the main application via XPC (Inter-Process Communication), ensuring the main app remains sandboxed while the helper operates with root privileges.

Now-Playing Dynamic Library

The build process generates libVorssaintNowPlaying.dylib, a dynamic library that implements the "Now Playing" media control plugin. Built at lines 72‑77, this artifact is loaded by the main executable at runtime to expose media-control information to other system processes. The source implementation lives in Sources/NowPlayingAdapter/NowPlayingAdapter.swift, providing the bridge between the app's media state and macOS system APIs.

Compiled Icon Assets

Resource artifacts include the AppIcon.icns file, generated from source SVGs stored in Resources/Brand/AppIcon.icon. The build.sh script handles this conversion at lines 78‑85, utilizing the Tools/MakeIcon.swift helper script to create the properly formatted icon set before compilation with actool (when available). This asset bundle provides both the application icon and the menu-bar status icons required by the user interface.

Staged Application Bundle

Before final packaging, the build creates an intermediate staged .app bundle in a temporary directory (assembled at lines 110‑123). This bundle aggregates the main executable, the fan-control helper, the Now-Playing adapter, all localization resources, images, GIFs, and the cryptographically signed Info.plist. The staging process at lines 124‑138 applies the initial code signature to ensure all embedded binaries are properly signed before bundling.

Final Signed Bundle

The final distributable artifact is the clean, verified .app bundle copied to build/stage/<App>.app (lines 706‑718). This stage strips all extended attributes and performs strict validation using codesign --verify --deep --strict to ensure the bundle meets macOS Gatekeeper requirements. This artifact represents the production-ready application that can be distributed to users or uploaded to notarization services.

Optional Installation Artifact

When invoked with the --install flag, the build pipeline produces a final artifact at /Applications/<App>.app (lines 720‑739). This copy is re-signed after installation to ensure a stable code signature that preserves permissions across system restarts. This artifact is functionally identical to the final signed bundle but positioned for immediate user access without manual drag-and-drop installation.

Build Automation and Orchestration

While Package.swift defines the base executable target (lines 19‑22), the build.sh script serves as the master orchestrator that coordinates compilation, resource processing, code signing, and packaging. The script handles conditional logic for developer builds, manages signing identities, and ensures all seven artifacts are produced in the correct dependency order.

# Build release version with all artifacts

./build.sh

# Build developer variant (coexists with official app)

./build.sh --dev

# Build, sign, and install to /Applications

./build.sh --install

After building, verify the final artifacts using macOS security tools:

# Verify code signature depth and strictness

codesign --verify --deep --strict build/stage/Vorssaint.app

# Assess Gatekeeper acceptance

spctl --assess --type exec --verbose=4 build/stage/Vorssaint.app

# Test the fan-control helper independently

build/com.vorssaint.utils.fan-control --selftest

Summary

• Main executable: Vorssaint or VorssaintDeveloper binary compiled from Sources/Vorssaint/**/*.swift at lines 42‑53 of build.sh.
• Fan-control helper: Privileged XPC daemon built at lines 61‑70 from Sources/FanControlHelper/main.swift.
• Now-Playing library: libVorssaintNowPlaying.dylib constructed at lines 72‑77.
• Icon assets: AppIcon.icns generated via Tools/MakeIcon.swift at lines 78‑85.
• Staged bundle: Intermediate $APP_NAME.app assembled and signed at lines 110‑138.
• Final bundle: Production-ready build/stage/<App>.app verified at lines 706‑718.
• Installation copy: Optional /Applications/<App>.app created at lines 720‑739 when using --install.

Frequently Asked Questions

What distinguishes the staged bundle from the final signed bundle?

The staged bundle is an intermediate assembly created in a temporary directory containing all binaries and resources but may retain build-time extended attributes. The final signed bundle at build/stage/<App>.app is a sanitized copy with all extended attributes stripped and subjected to strict codesign verification, making it suitable for distribution.

How do I build the developer variant that coexists with the official release?

Execute ./build.sh --dev to produce the VorssaintDeveloper executable and corresponding bundle. This variant uses distinct bundle identifiers and file paths, allowing it to run alongside the standard Vorssaint.app without conflicts, as implemented in the conditional logic at the beginning of the build script.

Why is the fan-control functionality separated into a distinct binary?

The fan-control helper requires root privileges to access the System Management Controller (SMC) and modify hardware fan speeds. Isolating this capability into a separate launch daemon (built from Sources/FanControlHelper/main.swift) follows macOS security best practices, allowing the main GUI application to remain unprivileged while communicating with the privileged helper via XPC.

How can I verify that all build artifacts were signed correctly?

Run codesign --verify --deep --strict build/stage/Vorssaint.app to validate deep code signatures across all embedded binaries including the fan-control helper and Now-Playing library. For Gatekeeper compliance assessment, use spctl --assess --type exec --verbose=4 on the final bundle path.

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