Vorssaint-utils Project Structure: Complete Guide to the macOS Swift Package

TLDR: Vorssaint-utils is a macOS-only Swift package containing three SPM targets—two system libraries (HIDEventSystem, VMStatisticsCompat) and one executable (Vorssaint)—organized under Sources/ with supporting tools, tests, and documentation at the repository root.

The vorssaint-utils repository delivers a single macOS utility application through a clean Swift Package Manager structure. Understanding this layout is essential for contributors, maintainers, and developers looking to extend or debug the codebase. This guide breaks down every directory, target, and key file based on the actual source implementation.

SPM Package Architecture

The project defines its build configuration in Package.swift at the repository root. This file declares three distinct targets that work together to produce the final Vorssaint app.

Target	Type	Purpose
HIDEventSystem	System library	Low-level HID event wrappers required by input handling services
VMStatisticsCompat	System library	Compatibility layer for macOS VM statistics APIs
Vorssaint	Executable	Main application containing UI, services, and entry point

These targets follow SwiftPM conventions with source files located under Sources/<TargetName>/.

Directory Structure Breakdown

Sources Directory

The Sources/ folder contains all compilable code organized by target.

Sources/
├── HIDEventSystem/          # System library: HID event abstractions

├── VMStatisticsCompat/      # System library: VM stats compatibility

└── Vorssaint/               # Executable: main application

    ├── main.swift           # Application entry point

    ├── UI/                  # Cocoa interface components

    │   └── WindowGestureControls.swift
    ├── Services/            # Feature implementations

    │   └── Audio/
    │       └── BoostLimiter.swift
    └── Core/                # Models, defaults, strings, feature catalog

The executable's Sources/Vorssaint/main.swift performs critical initialization: it registers user defaults, parses command-line arguments, and launches NSApplication for the Cocoa event loop.

Supporting Directories

• .github/workflows/ — GitHub Actions CI pipelines for automated builds and tests
• Docs/ — Project documentation including README.md, CHANGELOG.md, PRIVACY.md, and PERMISSIONS.md
• Resources/ — Localized strings (.lproj directories), Info.plist, and Vorssaint.entitlements
• Tests/ — XCTest suite with MetricsTests.swift for metric utility validation
• Tools/ — Bash automation scripts:
  • build.sh — compiles, signs, and packages the app
  • uninstall.sh — cleanup utility
  • make-dmg.sh — distribution packaging

Building and Running the Project

Compile the release binary using standard SwiftPM commands:

# Clone and enter the repository

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

# Build release executable

swift build -c release

Output appears at ./.build/release/Vorssaint.

Command-Line Modes

The executable supports several runtime flags defined in main.swift:

# Launch full GUI application

./.build/release/Vorssaint

# Run self-test and exit

./.build/release/Vorssaint --selftest

# Dump hardware sensor data

./.build/release/Vorssaint --sensors

Extending the Vorssaint-utils Project Structure

To add a new service feature:

1. Create a Swift file under Sources/Vorssaint/Services/ (e.g., Sources/Vorssaint/Services/Display/NightMode.swift)
2. Register the service in Sources/Vorssaint/Core/FeatureCatalog.swift
3. Rebuild with swift build

This pattern maintains the clean separation between system libraries and application logic that defines the vorssaint-utils architecture.

Summary

• Three SPM targets: two system libraries plus one executable
• Entry point: Sources/Vorssaint/main.swift bootstraps Cocoa app lifecycle
• Feature code: organized under Sources/Vorssaint/UI/, Services/, and Core/
• Build automation: Tools/build.sh handles compilation, signing, and packaging
• Single test file: Tests/MetricsTests.swift for XCTest validation

Frequently Asked Questions

What build system does vorssaint-utils use?

The project uses Swift Package Manager defined in Package.swift at the repository root. No Xcode project file is required; builds use swift build commands.

Where is the application entry point located?

The main entry point is Sources/Vorssaint/main.swift, which initializes defaults, processes command-line flags like --selftest and --sensors, and starts the NSApplication run loop.

How are system-level dependencies handled?

Two dedicated system library targets—HIDEventSystem and VMStatisticsCompat—wrap low-level macOS APIs. These isolate platform-specific code from the main application logic.

Can I build vorssaint-utils without Xcode?

Yes. The repository includes Tools/build.sh, a Bash script that compiles the project using swift build, creates the app icon, signs the bundle, and optionally installs it. CI pipelines in .github/workflows/ also build without Xcode interaction.

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