Skip to main content

​
Prerequisites

RequirementMinimum
macOS14.0 (Sonoma)
Xcode15.0+
Swift5.9+
SwiftLintLatest (via Homebrew)
SwiftFormatLatest (via Homebrew)
# Install linting tools
brew install swiftlint swiftformat

​
Clone the Repository

git clone https://github.com/LocNguyenHuu/Rockxy.git
cd Rockxy
Xcode resolves SPM dependencies automatically on first open. If packages fail to resolve, go to File > Packages > Resolve Package Versions.

​
Building

​
Debug Build (Command Line)

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy -configuration Debug build

​
Release Build

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy -configuration Release build

​
Clean Build

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy clean

​
Building in Xcode

Open Rockxy.xcodeproj and press Cmd+B to build, or Cmd+R to build and run.
The first build takes longer as Xcode compiles SwiftNIO and other SPM dependencies. Subsequent builds are incremental.

​
Running Tests

​
All Tests

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy test

​
Specific Test Class

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy test \
  -only-testing:RockxyTests/TestClassName

​
Specific Test Method

xcodebuild -project Rockxy.xcodeproj -scheme Rockxy test \
  -only-testing:RockxyTests/TestClassName/testMethodName

​
In Xcode

Press Cmd+U to run all tests, or click the diamond icon next to a test method to run it individually.

​
Linting and Formatting

Run both before every commit: 
# Lint — reports violations, fails on warnings in strict mode
swiftlint lint --strict

# Format — auto-fixes formatting issues
swiftformat .
Always run swiftlint lint --strict before committing. CI will reject PRs with lint violations.
See the Code Style page for the full rule set and configuration details.

​
Project Structure

Rockxy uses Xcode 16+‘s file system synchronized groups — files added to directories are automatically discovered by Xcode. There is no need to manually add file references to project.pbxproj. SPM dependencies are declared in the Xcode project (not a top-level Package.swift). The dependency graph:
PackagePurpose
swift-nioNon-blocking proxy server event loop
swift-nio-sslTLS handling for HTTPS interception
swift-certificatesX.509 cert generation (root CA + per-host)
swift-cryptoCryptographic primitives
SQLite.swiftSession and log persistence

​
Entitlements

Rockxy requires specific entitlements to function as a network proxy:
  • Network Server — listens on a local port for proxy connections
  • Network Client — forwards requests to upstream servers
  • Keychain Access — stores the root CA private key
App Sandbox is disabled because macOS sandbox restrictions prevent binding to arbitrary ports and modifying system proxy settings.

​
Sample Data (Debug Only)

Rockxy includes a sample data generator for development. It creates realistic HTTP transactions, log entries, error groups, performance metrics, and session trends so you can work on the UI without running a live proxy. Three ways to load sample data:
  1. Launch argument — pass -RockxySampleData to auto-load on startup (set in Xcode scheme under Arguments Passed On Launch)
  2. Menu — Debug builds add a Help > Load Sample Data menu item (Cmd+Shift+D)
  3. Toolbar — a flask icon button in the toolbar toggles sample data on/off
All sample data code is compiled only in Debug builds (#if DEBUG) and is stripped from release archives.

​
Troubleshooting

​
SPM Dependencies Won’t Resolve

  1. Close Xcode
  2. Delete the DerivedData folder: rm -rf ~/Library/Developer/Xcode/DerivedData/Rockxy-*
  3. Reopen the project and let Xcode re-resolve

​
Build Fails with Missing Module

Ensure SPM packages are resolved: File > Packages > Resolve Package Versions. If the issue persists, reset the package cache: File > Packages > Reset Package Caches.

​
Certificate Trust Issues at Runtime

If HTTPS interception doesn’t work after building, the root CA certificate needs to be trusted in Keychain Access. See the Installation guide for certificate setup steps.

​
Next Steps

Architecture

Understand the actor model, coordinator pattern, and data flow

Code Style

SwiftLint rules, formatting standards, and naming conventions