obsidian-vault/work/wiki/apple-browsers/development-commands.md

source, confidence, namespace, last_synced, alwaysApply

source	confidence	namespace	last_synced	alwaysApply
~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/development-commands.mdc	0.9	work	2026-04-28	true

Development Commands & Build Instructions

📋 When to Use This Document

Use these instructions when you need to:

• Build the iOS Browser app for testing or development
• Build the macOS Browser app for testing or development
• Verify that code changes compile successfully
• Prepare the app for testing or debugging
• Understand build failures and how to fix them

🚦 Golden Rules for Building

✅ ALWAYS DO THESE

1. Use the full shell wrapper: /bin/sh -c 'set -e -o pipefail && xcodebuild ... | xcbeautify'
2. Detect environment first: Never hardcode paths or simulator IDs
3. Check exit codes: Ensure the build succeeded before proceeding
4. Use absolute paths: Always use full paths for workspace files
5. Include xcbeautify: Output is unreadable without it

❌ NEVER DO THESE

1. Never use -jobs flag: It's been removed from all commands
2. Never skip xcbeautify: Raw xcodebuild output is nearly impossible to parse
3. Never use .xcodeproj files: Always use .xcworkspace
4. Never hardcode simulator IDs: They change between systems
5. Never ignore build failures: Always check and handle errors

🔍 Phase 1: Environment Detection

Pre-Flight Checks

Before building, validate your environment.

Example: See pre-flight-checks.sh

Required Variables to Detect

Variable	Purpose	Detection Command	Expected Format
WORKSPACE_PATH	Full path to .xcworkspace	pwd + find . -name "DuckDuckGo.xcworkspace"	/Users/.../DuckDuckGo.xcworkspace
SIMULATOR_ID	iOS Simulator UUID	xcrun simctl list devices | grep iPhone	XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
ARCHITECTURE	Mac CPU type	uname -m	arm64 or x86_64

Detection Commands

Example: See environment-detection.sh

🏗️ Phase 2: Build Execution

iOS Build Command Template

Replace the placeholders with your detected values.

Example: See ios-build-template.sh

macOS Build Command Template

Replace the placeholders with your detected values.

Example: See macos-build-template.sh

Complete Working Examples

iOS Build (Real Values)

Example: See ios-build-example.sh

macOS Build (Real Values)

Example: See macos-build-example.sh

✅ Phase 3: Build Verification

Signs of Success

• Command exits with code 0
• Last line contains "BUILD SUCCEEDED"
• No error messages in red
• Build time is within expected range (see performance table below)

Signs of Failure

• Command exits with non-zero code
• Output contains "BUILD FAILED"
• Red error messages appear
• Build hangs for more than 15 minutes

Performance Expectations

Build Type	Expected Duration	Action if Exceeded
First build	5-10 minutes	Normal - downloading dependencies
Subsequent build	1-3 minutes	Check for errors in output
Clean build	3-5 minutes	Normal - rebuilding everything
Incremental	10-30 seconds	Normal for small changes
Hanging >15 min	Abnormal	Cancel and check for issues

🔧 Error Recovery

If Build Fails - Immediate Actions

1. Check the error message - Last few red lines usually indicate the issue
2. Clean and retry: See error-recovery-clean.sh
3. If "No such module" errors: See error-recovery-derived-data.sh
4. If simulator issues: See error-recovery-simulator.sh

Common Problems and Solutions

Problem	Diagnosis Command	Solution
No workspace found	ls *.xcworkspace	Ensure you're in project root directory
Simulator not found	xcrun simctl list devices	Pick a different simulator ID from the list
"Command not found: xcbeautify"	which xcbeautify	Install: brew install xcbeautify
Build hangs	Check Activity Monitor	Kill xcodebuild process and retry
"No such module"	Check package resolution	Clean DerivedData and rebuild
Provisioning errors	Check Xcode account	May need manual Xcode intervention

🤖 Complete Automation Script

Use this script for reliable, automated builds.

Example: See complete-automation-script.sh

📊 Build Flag Reference

Understanding what each flag does:

Flag	Purpose	Impact
ONLY_ACTIVE_ARCH=YES	Build only for current architecture	50% faster builds
DEBUG_INFORMATION_FORMAT=dwarf	Use DWARF debug symbols	Smaller build size
COMPILER_INDEX_STORE_ENABLE=NO	Skip code indexing	Faster builds
-allowProvisioningUpdates	Auto-update certificates	Prevents signing failures
-disableAutomaticPackageResolution	Skip package updates	Faster, more stable
-parallelizeTargets	Build targets in parallel	Uses all CPU cores
-scheme	Which app to build	Selects iOS or macOS
-configuration	Debug or Release	Debug = faster, Release = optimized
-destination	Where to run	Simulator/device/Mac

📚 Additional Resources

Available Schemes

• iOS Browser - Main iOS app
• macOS Browser - Main macOS app (sometimes called "DuckDuckGo")

Useful Commands

Example: See useful-commands.sh

✅ Task Completion Checklist

Before considering the build task complete, verify:

• Build command executed without errors
• "BUILD SUCCEEDED" message appeared
• Exit code was 0
• Build time was within expected range
• No unresolved errors in output
• If requested, both iOS and macOS builds completed

🚨 Critical Warnings

For Release Builds

If building for release/production, change -configuration Debug to -configuration Release

For Device Builds

If building for a physical iOS device (not simulator), you'll need:

• Device UUID instead of simulator ID
• Valid provisioning profiles
• Device connected and trusted

For CI/Automation

• Always check exit codes
• Implement timeouts (15 minutes max)
• Log full output for debugging
• Clean build environment between runs