# How vorssaint-utils Configures SwiftPM for Editor Indexing with System Library Support

> Learn how vorssaint-utils configures SwiftPM for fast editor indexing with system library support. Discover explicit manifests and module maps for IDE efficiency.

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

---

**`vorssaint-utils` achieves instant editor indexing across SwiftPM-aware IDEs through explicit package manifests, system-library module maps, and strict project hygiene conventions.**

`vorssaint-utils` is a macOS system-utility package designed for immediate IDE integration without custom build scripts. By leveraging standard Swift Package Manager constructs in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) and companion module maps, the repository enables robust code navigation, autocompletion, and go-to-definition for C-based system frameworks within any SwiftPM-compatible editor.

## Explicit SwiftPM Manifest Structure

The foundation of editor indexing lies in the root [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift), which declares the package name as **Vorssaint**, enforces a macOS 14 platform minimum, and defines three distinct targets. This explicit declaration allows SwiftPM to generate accurate module interfaces that editors parse for symbol tables.

The manifest configures two **system library targets** for C-headers and one executable target for Swift source:

```swift
// Package.swift
let package = Package(
    name: "Vorssaint",
    platforms: [.macOS(.v14)],
    targets: [
        .systemLibrary(name: "HIDEventSystem", path: "Sources/HIDEventSystem"),
        .systemLibrary(name: "VMStatisticsCompat", path: "Sources/VMStatisticsCompat"),
        .executableTarget(
            name: "Vorssaint",
            dependencies: ["VMStatisticsCompat", "HIDEventSystem"],
            path: "Sources/Vorssaint"
        )
    ]
)

```

By specifying `path:` arguments for each target, SwiftPM resolves source locations deterministically, ensuring that Language Server Protocol (LSP) implementations can map symbols back to the correct file offsets in `Sources/Vorssaint`, `Sources/HIDEventSystem`, and `Sources/VMStatisticsCompat`.

## System-Library Module Maps

For editors to index low-level macOS APIs written in C, `vorssaint-utils` provides **module map** files that expose headers as importable Swift modules. This eliminates the need for manual bridging headers and generates the `.swiftmodule` metadata that powers autocompletion.

### HIDEventSystem Mapping

The file `Sources/HIDEventSystem/module.modulemap` exposes HID subsystem headers to SwiftPM:

```

module HIDEventSystem {
    header "include/hid_system.h"
    export *
}

```

### VMStatisticsCompat Mapping

Similarly, `Sources/VMStatisticsCompat/module.modulemap` wraps mach kernel statistics headers:

```

module VMStatisticsCompat {
    header "include/vm_statistics_compat.h"
    export *
}

```

Once these maps are present, Swift code in dependent targets imports them as ordinary Swift modules, triggering the compiler to build indexable interfaces:

```swift
import HIDEventSystem        // Low-level HID event APIs
import VMStatisticsCompat    // mach/vm_statistics compatibility layer

// Example usage indexed by editors:
let stats = vorssaint_read_vm_statistics64()

```

## Editor Hygiene and Git Configuration

The repository maintains deterministic indexing through a carefully managed `.gitignore`. By excluding Xcode and SwiftPM user-state files—including derived data and scheme management directories—the project prevents stale index caches from contaminating the working copy.

Additionally, [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md) explicitly documents that "SwiftPM aware editors can index the code," confirming the package's compatibility with Xcode, VS Code's Swift extension, AppCode, and other LSP-based tools. This convention-driven approach means developers can open the folder in any compliant IDE and receive immediate symbol resolution without running preliminary build scripts.

## Consuming vorssaint-utils with Full Indexing

Downstream projects add `vorssaint-utils` as a dependency and instantly benefit from indexed system-library symbols. The package exposes its executable and system-library products through standard SwiftPM mechanisms.

To include the package in another project, declare the dependency and target linkage:

```swift
// Downstream Package.swift
let package = Package(
    dependencies: [
        .package(
            url: "https://github.com/vorssaint/vorssaint-utils.git",
            .upToNextMajor(from: "3.1.4")
        )
    ],
    targets: [
        .executableTarget(
            name: "MyApp",
            dependencies: ["Vorssaint"]
        )
    ]
)

```

For developers preferring generated Xcode projects, the standard SwiftPM CLI provides indexing-compatible project files:

```bash
swift package generate-xcodeproj   # Optional: for legacy Xcode workflows

swift build                        # Compiles modules and updatesEditor indexes

```

Running `swift build` is sufficient for most editors (including VS Code with SourceKit-LSP) to populate symbol databases, as SwiftPM automatically resolves dependencies and builds the module graphs for `HIDEventSystem` and `VMStatisticsCompat`.

## Summary

- **[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)** explicitly declares system-library targets with filesystem paths, enabling SwiftPM to generate complete module interfaces for editor consumption.
- **`module.modulemap` files** in `Sources/HIDEventSystem/` and `Sources/VMStatisticsCompat/` expose C headers as Swift modules without bridging headers, allowing direct `import` statements that editors can resolve.
- **`.gitignore` conventions** exclude Xcode user-state files to prevent index corruption, while [`CONTRIBUTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CONTRIBUTING.md) documents SwiftPM editor compatibility.
- **Zero-configuration workflow**: Developers open the repository in any SwiftPM-aware editor and receive immediate code navigation for both Swift and C system symbols.

## Frequently Asked Questions

### Do I need to generate an Xcode project to index vorssaint-utils?

No. While `swift package generate-xcodeproj` creates a legacy `.xcodeproj` for Xcode users, most modern editors—including VS Code with the Swift extension—index the package directly through SourceKit-LSP by simply opening the repository root. The [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) manifest provides all necessary metadata for symbol resolution without intermediate project files.

### Which system libraries does vorssaint-utils expose to SwiftPM?

The package exposes **HIDEventSystem** and **VMStatisticsCompat** as system-library targets. These map to low-level macOS C APIs for HID event processing and virtual memory statistics, respectively. The corresponding `module.modulemap` files in `Sources/HIDEventSystem/` and `Sources/VMStatisticsCompat/` make these headers accessible via standard Swift `import` statements.

### Why does vorssaint-utils use system-library targets instead of standard targets?

System-library targets are required when wrapping C system headers that exist outside the package repository, such as `<IOKit/hid/IOHIDEventSystemClient.h>` or `<mach/mach_vm.h>`. The `.systemLibrary` declaration in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) paired with a `module.modulemap` tells SwiftPM where to find these headers and how to compile them, enabling the Swift compiler to generate module interfaces that editors index for autocompletion.

### Can I build vorssaint-utils on platforms other than macOS 14?

No. The [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) explicitly declares `platforms: [.macOS(.v14)]`, and the system libraries wrap macOS-specific kernel interfaces. Attempting to build on Linux or earlier macOS versions will fail during dependency resolution because the required system headers and frameworks are unavailable on those platforms.