Skip to content

Installation.md

Latest commit

 

History

History
175 lines (120 loc) · 2.76 KB

Installation.md

File metadata and controls

175 lines (120 loc) · 2.76 KB

Installation Guide

Prerequisites

  • macOS: 14.0 (Sonoma) or later
  • Swift: 6.0 or later
  • Xcode: 16.0 or later (includes Swift compiler)
  • Architecture: ARM64 (Apple Silicon)

Verify Prerequisites

# Check macOS version
sw_vers

# Check Swift version
swift --version

# Check Xcode version
xcodebuild -version

Building from Source

1. Clone the Repository

git clone https://github.com/sadopc/machscope.git
cd MachScope

2. Build Debug Version

swift build

The debug binary is located at .build/debug/machscope.

3. Build Release Version

swift build -c release

The release binary is located at .build/release/machscope.

4. Run Tests

swift test

Installation Options

Option 1: Run from Build Directory

# Run directly with swift run
swift run machscope parse /bin/ls

# Or use the built binary
.build/debug/machscope parse /bin/ls

Option 2: Install to /usr/local/bin

# Build release version
swift build -c release

# Copy to /usr/local/bin
sudo cp .build/release/machscope /usr/local/bin/

# Verify installation
machscope --version

Option 3: Create Alias

Add to your ~/.zshrc or ~/.bashrc:

alias machscope='/path/to/MachScope/.build/release/machscope'

Enabling Debugging Features

To use the debug command, MachScope needs the debugger entitlement.

1. Sign with Entitlements

# Build first
swift build

# Sign with debugger entitlement
codesign --force --sign - \
  --entitlements Resources/MachScope.entitlements \
  .build/debug/machscope

2. Enable Developer Tools

  1. Open System Settings
  2. Go to Privacy & Security > Developer Tools
  3. Enable Terminal (or your terminal app)
  4. Restart Terminal

3. Verify Permissions

swift run machscope check-permissions

You should see:

Debugger              ✓ Ready

Uninstallation

If Installed to /usr/local/bin

sudo rm /usr/local/bin/machscope

Remove Build Artifacts

swift package clean
rm -rf .build

Troubleshooting Installation

Swift Not Found

Install Xcode Command Line Tools:

xcode-select --install

Build Fails with Module Errors

Clean and rebuild:

swift package clean
swift build

Permission Denied Errors

Ensure you have read access to the repository:

ls -la

Code Signing Fails

Make sure you have a valid signing identity:

security find-identity -v -p codesigning

For ad-hoc signing (no certificate needed), use - as the identity:

codesign --force --sign - ...

Next Steps