# Vorssaint-Utils Development Workflow: Complete Guide to Building, Testing, and Contributing > Learn the vorssaint-utils development workflow. This guide covers building, testing, and contributing using a single build script for efficiency and CI validation. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: how-to-guide - Published: 2026-09-05 --- **The vorssaint-utils development workflow uses a single [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) script to handle cloning, code signing, development builds, self-testing, unit tests, and local installation, with CI validation on every push.** This article walks through the complete vorssaint-utils development workflow based on the actual source code in the [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) repository. Whether you're fixing a bug or adding features, these steps will get you from zero to a working build on macOS. ## Prerequisites and Initial Setup Before building, ensure you have **Apple Command-Line Tools** and **Swift 6.0.3** installed. The project uses SwiftPM for dependency resolution but relies on a custom shell script for the full build pipeline. Clone the repository and enter the project directory: ```bash git clone https://github.com/vorssaint/vorssaint-utils.git cd vorssaint-utils ``` ## Code Signing Setup (Optional but Recommended) macOS requires code-signed binaries for proper execution. If you lack an Apple Developer ID, run the helper script at [[`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): ```bash ./Tools/setup-signing.sh ``` This creates a local "Vorssaint Utils Signing" certificate. The build script invokes this automatically when needed, but running it upfront prevents interruptions. ## Building a Development Version The core of the vorssaint-utils development workflow is [[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh). Use the `--dev` flag (lines 29-38) to create a **Developer variant** that coexists with release builds: ```bash ./build.sh --dev ``` **What `--dev` changes:** - **Bundle identifier** switches to `com.vorssaint.utils.dev` (prevents conflicts with `/Applications/Vorssaint.app`) - **Optimization disabled** (`-Onone`) for faster compile times during iteration - **Output location** is `./build/Vorssaint (Developer).app` This side-by-side installation lets you test changes without affecting your production instance. ## Verifying Your Build with Self-Tests After any successful build, validate the binary launches correctly: ```bash ./build/Vorssaint --selftest ``` A functioning build prints `SELFTEST OK` and exits. This check appears in [[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh#L35-L37) at lines 35-37 and runs automatically during CI. ## Running Unit Tests Execute the standalone test harness with: ```bash ./build.sh --test ``` The test path (lines 45-84) performs these operations: 1. Compiles `metrics-tests` via a direct `swiftc` invocation with all dependencies 2. Runs the executable 3. Cleans test-generated preference files via `discard_test_preferences` (around line 20) The test source lives at [[`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift)](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift). ## Installing Locally for Real-World Testing To replace or install the app in `/Applications`: ```bash ./build.sh --install ``` The install logic (lines 99-117) handles: - Stopping any running Vorssaint instance - Removing legacy bundle versions - Copying via `ditto` to `/Applications` - Re-signing so macOS permissions survive rebuilds The install path assembly appears at lines 99-101, with copy operations following at lines 99-117. ## Understanding the CI Validation Pipeline Every push to `main` triggers the workflow defined in [[`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml)](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml). The CI runner (macOS 15) performs: ```yaml - name: Verify Swift toolchain - name: Build run: ./build.sh - name: Selftest run: ./build/Vorssaint --selftest - name: Unit tests run: ./build.sh --test ``` This ensures the vorssaint-utils development workflow produces working artifacts before any merge. The CI uses the same [[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) you run locally, eliminating "works on my machine" discrepancies. ## Release Process (Maintainers) For official releases, tag a version: ```bash git tag vX.Y.Z git push origin vX.Y.Z ``` The [`release.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/release.yml) workflow (referenced but not detailed in source) handles: - Developer ID signing - Notarization - DMG publication This remains separate from the daily vorssaint-utils development workflow. ## Complete Developer Cycle Example Here's the full sequence for typical contribution work: ```bash # 1. Clone and enter directory git clone https://github.com/vorssaint/vorssaint-utils.git cd vorssaint-utils # 2. (Optional) Set up local signing ./Tools/setup-signing.sh # 3. Build development version ./build.sh --dev # 4. Verify binary health ./build/Vorssaint --selftest # 5. Install for manual testing ./build.sh --install # 6. Run unit test suite ./build.sh --test # 7. Commit and push — CI validates automatically git add . git commit -m "feat: your change description" git push origin feature-branch ``` ## Key Files in the Development Workflow | File | Purpose | |------|---------| | [[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) | Central build orchestrator; handles `--dev`, `--install`, `--test` flags | | [[`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) | Local certificate creation for unsigned builds | | [[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) | SwiftPM manifest for editor indexing | | [[`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml)](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) | Automated validation on every push/PR | | [[`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift)](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) | Unit test implementation | | [[`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md)](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md) | Extended contributor guidelines | ## Summary - **Single-script workflow**: All build, sign, and test operations flow through [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) with no external dependencies - **Side-by-side development**: The `--dev` flag creates isolated Developer variants that won't conflict with release installs - **Multiple validation layers**: Self-tests verify launch capability; `metrics-tests` provide unit coverage; CI enforces both on every change - **Flexible signing**: [`setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/setup-signing.sh) enables local development without Apple Developer ID; production releases use proper notarization - **Deterministic cleanup**: Test runs automatically clear preference files to maintain reproducible environments ## Frequently Asked Questions ### Do I need an Apple Developer ID to build vorssaint-utils? No. Run [`./Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./Tools/setup-signing.sh) to create a local "Vorssaint Utils Signing" certificate. The build script detects and uses this automatically. Developer ID is only required for distribution releases. ### What's the difference between [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) and `./build.sh --dev`? Plain [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) creates an optimized release build with the standard bundle identifier `com.vorssaint.utils`. The `--dev` flag (lines 29-38) switches to `com.vorssaint.utils.dev`, disables optimization, and outputs to `./build/Vorssaint (Developer).app` so you can test alongside an installed release. ### How do I run tests without installing anything? Execute `./build.sh --test` directly. This compiles and runs the standalone test executable without touching `/Applications`. The script cleans up test preferences automatically after completion. ### What happens if CI fails on my pull request? The CI pipeline in [`.github/workflows/ci.yml`](https://github.com/vorssaint/vorssaint-utils/blob/main/.github/workflows/ci.yml) repeats your local build steps: toolchain verification, build, self-test, and unit tests. Failures typically indicate environment differences (Swift version) or test regressions. Fix locally by running the same commands, then push again.