# How to Set Up a Local Development Environment for Vorssaint-Utils: Complete Guide

> Set up your local vorssaint-utils development environment on macOS 14 Sonoma with Apple Silicon. Follow our guide for a streamlined setup using a single build script.

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

---

**Setting up a local development environment for vorssaint-utils requires macOS 14 Sonoma on Apple Silicon, Xcode Command-Line Tools, and a single build script—no external package managers needed.**

Vorssaint-utils is a self-contained macOS Swift utility suite that compiles with `swiftc` and ships with its own build orchestration. This guide walks through the exact steps derived from the repository's [`README.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md), including optional code signing setup for persistent macOS permissions.

## Prerequisites for Vorssaint-Utils Development

Before cloning the repository, verify your system meets these requirements:

- **macOS 14 Sonoma or newer** – The source code in `Sources/Vorssaint/` uses APIs introduced in macOS 14
- **Apple Silicon (M1/M2/M3)** – The build scripts assume ARM64 architecture
- **Xcode Command-Line Tools** – Provides `swiftc`, `codesign`, and other build utilities

Install the command-line tools if missing:

```bash
xcode-select --install

```

No additional package managers (Homebrew, Mint, etc.) are required. The [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) file exists only for IDE support and is not used during compilation.

## Clone and Build Vorssaint-Utils

Start by pulling the source and entering the project directory:

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

```

The repository follows a flat structure with source files under `Sources/Vorssaint/` and helper scripts in `Tools/`.

## Optional: Configure Stable Code Signing

To prevent macOS from revoking **Accessibility** and **Screen Recording** permissions after every rebuild, create a persistent self-signed identity:

```bash
./Tools/setup-signing.sh

```

This script generates a certificate named **"Vorssaint Utils Signing"** in your login keychain. According to the [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md) guidelines, stable signing is strongly recommended for contributors who will iterate frequently.

## Build the Application

Run the core build script:

```bash
./build.sh

```

The [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) script in the repository root performs several operations:

1. Compiles Swift sources using `swiftc` directly (no SwiftPM build)
2. Creates the app bundle structure
3. Codesigns the binary with the configured identity
4. Outputs to `./build/Vorssaint.app`

Verify the compiled binary works correctly:

```bash
./build/Vorssaint --selftest

```

Expect output: `SELFTEST OK`. This self-test is **mandatory for CI compliance**—pull requests must pass this check.

## Install and Run Locally

To test the full UI experience, install the app to `/Applications`:

```bash
./build.sh --install

```

This copies the signed bundle and launches it immediately. Alternatively, run without installing:

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

```

## Managing macOS Permissions

After initial builds, macOS may cache stale permission grants. Reset them to force fresh prompts:

```bash
tccutil reset Accessibility com.vorssaint.utils.dev
tccutil reset ScreenRecording com.vorssaint.utils.dev

```

The bundle identifier `com.vorssaint.utils.dev` is used for development builds. Production releases use `com.vorssaint.utils`.

## Project Structure Key Files

Understanding these files accelerates contribution:

- **[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)** – Core build orchestration; handles compilation, signing, and installation
- **[`Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh)** – Creates the persistent signing identity for stable permissions
- **[`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh)** – Complete cleanup: removes app, login item, and all privacy grants
- **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** – Application entry point; initializes the menu-bar status item
- **[`Sources/Vorssaint/Core/Localization.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Localization.swift)** – Central string catalog for multilingual support
- **`Sources/Vorssaint/UI/`** – SwiftUI views; pure presentation layer with no business logic

## Development Workflow Summary

```bash

# Complete setup from scratch

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./Tools/setup-signing.sh    # Optional but recommended

./build.sh
./build/Vorssaint --selftest
./build.sh --install        # Optional

```

Open any source file in Xcode, VS Code, or another Swift-aware editor to begin modifying features. The project intentionally avoids external dependencies to maintain build simplicity.

## Summary

- **No package manager required** – Swift sources compile directly with `swiftc` via [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)
- **macOS 14 + Apple Silicon mandatory** – Hard requirements from the codebase
- **Stable signing prevents permission fatigue** – Use [`Tools/setup-signing.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/setup-signing.sh) for iterative development
- **Self-test is mandatory** – `./build/Vorssaint --selftest` must pass for CI acceptance
- **Clean uninstall available** – [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) resets all state for fresh testing

## Frequently Asked Questions

### Do I need Xcode installed to build vorssaint-utils?

No. Only the **Xcode Command-Line Tools** are required, which provide `swiftc` and `codesign`. Run `xcode-select --install` to obtain them. The full Xcode IDE is optional—any Swift-aware editor works for development.

### Why does the build script use `swiftc` instead of `swift build`?

The vorssaint-utils project is deliberately self-contained. The [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) file exists solely for IDE indexing and autocomplete support. The actual build in [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) invokes `swiftc` directly, avoiding SwiftPM dependency resolution entirely.

### What happens if I skip the signing setup script?

The build will still succeed using ad-hoc signing, but macOS will treat each rebuild as a different application. This causes **previously granted Accessibility and Screen Recording permissions to become invalid**, requiring manual re-approval in System Settings after every compile.

### How do I completely reset my development environment?

Run [`./Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./Tools/uninstall.sh) to remove the app from `/Applications`, delete the login item, and clear all stored privacy grants. For permission resets without full uninstall, use `tccutil reset` with the development bundle identifier `com.vorssaint.utils.dev`.