Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
295 lines (217 loc) · 6.33 KB

DEVELOPMENT.md

File metadata and controls

295 lines (217 loc) · 6.33 KB

Development Guide

Quick Start

macOS Development Workflow

The fastest way to get started:

# Build, install, and test in one command
make dev

Or step by step:

# 1. Build debug version
make build

# 2. Install to /Applications and register protocol
make install

# 3. Test the protocol handler
make test-protocol

Why You Need to Install for Development

The protocol handler only works when the app is installed in /Applications/.

During development:

  • Each build creates a bundle at src-tauri/target/debug/bundle/macos/Sorcery Desktop.app
  • macOS only recognizes protocol handlers from /Applications/ or ~/Applications/
  • You must copy the app to /Applications/ and register it with LaunchServices

This is different from production, where:

  • Users install via DMG (drag to /Applications)
  • Protocol registration happens automatically on first launch

Development Commands

Build Commands

# Debug build (faster, includes logging)
make build
cargo tauri build --debug

# Release build (optimized, smaller)
make build-release
cargo tauri build

Installation Commands

# Build and install
make install

# Install existing build (no rebuild)
make install-quick
./scripts/quick-install-macos.sh

# Full install script (builds + installs)
./install-dev.sh

Testing Commands

# Test protocol handler from command line
make test-protocol
open "srcuri:///etc/hosts@L1"

# Test from browser
# Paste this in Chrome/Safari/Firefox address bar:
# srcuri:///etc/hosts@L1

Troubleshooting

Protocol Handler Not Working

Symptom: Clicking srcuri:// links in browser does nothing or shows an error.

Solution:

# 1. Check if app is installed
ls -la /Applications/Sorcery\ Desktop.app

# 2. Re-register with LaunchServices
make install-quick

# 3. Force rebuild LaunchServices database
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user

# 4. Re-register app
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/Sorcery\ Desktop.app

# 5. Test
open "srcuri:///etc/hosts@L1"

App Won't Launch

Symptom: App crashes immediately or shows Gatekeeper warning.

Solution:

# Remove quarantine attribute
xattr -dr com.apple.quarantine /Applications/Sorcery\ Desktop.app

# Or right-click app in Finder → Open → Open anyway (first time only)

Multiple Protocol Handlers

Symptom: Wrong app opens when clicking srcuri:// links.

Solution:

# List all handlers for srcuri://
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump | grep -B 5 -A 5 srcuri

# Remove old versions
rm -rf /Applications/Sorcery\ Desktop.app
rm -rf ~/Applications/Sorcery\ Desktop.app

# Reinstall
make install

Build Errors

Symptom: cargo tauri build fails.

Common causes:

# Missing Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Outdated dependencies
cd src-tauri
cargo update

# Clean build
cargo clean
cargo tauri build --debug

How Protocol Registration Works

macOS Architecture

Browser/Terminal
    ↓
    srcuri:// link clicked
    ↓
macOS LaunchServices
    ↓
    Checks HKEY_CLASSES_ROOT (Windows) or Info.plist (macOS)
    ↓
    Launches /Applications/Sorcery Desktop.app
    ↓
    Passes URL as argument OR fires deep-link event
    ↓
Sorcery processes URL
    ↓
    Opens file in configured editor

Registration Files

macOS: /Applications/Sorcery Desktop.app/Contents/Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>srcuri</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.srcuri.app</string>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
    </dict>
</array>

Linux: /usr/share/applications/sorcery.desktop or ~/.local/share/applications/sorcery.desktop

[Desktop Entry]
MimeType=x-scheme-handler/srcuri;
Exec=/usr/bin/sorcery %u

Windows: Registry key HKEY_CLASSES_ROOT\srcuri

Two Launch Modes

Mode 1: Command-line (fast, exits immediately)

open "srcuri:///etc/hosts@L1"
# macOS passes URL as argv[1]
# App handles URL, opens editor, exits
# No GUI, no background process

Mode 2: Deep-link event (browser, stays running)

User clicks link in browser
# macOS launches app without args
# Tauri fires "deep-link://new-url" event
# App handles URL, opens editor, stays running
# Background process for subsequent links

See src-tauri/src/main.rs:325-347 for command-line handling and main.rs:369-414 for deep-link event handling.

Running Tests

# Unit tests
cd src-tauri
cargo test

# Integration tests (requires Docker)
cd tests/docker
./run-tests.sh

# Protocol handler tests
cd tests/docker
./run-protocol-tests.sh

Production Builds

macOS

# Build universal binary (Intel + Apple Silicon)
cd src-tauri
cargo tauri build --target universal-apple-darwin

# Output: target/release/bundle/dmg/Sorcery_0.1.0_universal.dmg

Linux

# Build DEB package
cargo tauri build

# Output: target/release/bundle/deb/sorcery_0.1.0_amd64.deb

Windows

# Build MSI installer
cargo tauri build

# Output: target/release/bundle/msi/Sorcery_0.1.0_x64_en-US.msi

Development Tips

  1. Use make dev for rapid iteration - builds, installs, and tests in one command

  2. Check logs - the app logs to stdout/stderr when run from terminal:

    /Applications/Sorcery\ Desktop.app/Contents/MacOS/sorcery

  3. Test both launch modes:

    • Command-line: open "srcuri://..."
    • Browser: paste URL in address bar

  4. Kill background instances before testing:

    pkill -9 sorcery

  5. Verify protocol registration:

    defaults read /Applications/Sorcery\ Desktop.app/Contents/Info CFBundleURLTypes

See Also