apple-native-dev

name

apple-native-dev

description

Build, sign, and deploy iOS/macOS apps using Zed Editor and CLI-only workflows without Xcode UI. Use when: (1) Setting up a new iOS/macOS project with XcodeGen, (2) Configuring secure credential management via xcconfig files, (3) Setting up Zed Editor with Swift LSP, (4) Building/deploying to physical devices via CLI, (5) Creating CI/CD pipelines for Apple apps, (6) Troubleshooting CLI build issues. Covers XcodeGen, xcode-build-server, justfile commands, devicectl, and GitHub Actions scaffolding following 2026 best practices.

Apple Native Development (CLI + Zed)

Build iOS/macOS apps without Xcode UI using XcodeGen, justfile, and Zed Editor.

Core Workflow

1. Project Setup

# Install tools
brew install xcodegen just xcode-build-server

# Generate Xcode project from project.yml
cd Apps/MyApp && xcodegen generate

2. Credential Management

Use xcconfig files to keep Team ID out of git. See references/credentials.md.

Apps/MyApp/Configs/
├── Project.xcconfig           # Committed (loads local + defaults)
├── Project.local.xcconfig     # Gitignored (your Team ID)
└── Project.local.xcconfig.example  # Committed template

Quick setup (auto-detects Team ID from keychain):

just ios::setup-credentials

3. Zed Editor LSP

Generate buildServer.json for code completion. See references/zed-setup.md.

just ios::setup-lsp
# Or manually:
xcode-build-server config -project Apps/MyApp/MyApp.xcodeproj -scheme MyApp

4. Build & Deploy

Simulator:

just ios::build      # Build for simulator
just ios::run        # Build + install + launch

Physical Device (iOS 17+):

just ios::device-deploy  # Build + install + launch on iPhone

See references/justfile.md for all commands.

5. CI/CD

GitHub Actions scaffold at .github/workflows/ios-build.yml.disabled. See references/ci-cd.md.

Key Files

File	Purpose
project.yml	XcodeGen project definition
Configs/Project.xcconfig	Base build settings (committed)
Configs/Project.local.xcconfig	Credentials (gitignored)
buildServer.json	LSP configuration (gitignored)
justfile or ios.just	Build commands

Gitignore Patterns

# Credentials
*.local.xcconfig
!*.local.xcconfig.example

# Editor integration
buildServer.json

# XcodeGen output
*.xcodeproj/

Templates

Copy from assets/templates/ when bootstrapping:

• Project.xcconfig - Base xcconfig (committed)
• Project.local.xcconfig.example - Credential template (committed)
• project.yml - XcodeGen project definition
• ios.just - Justfile module for iOS commands
• ios-build.yml.disabled - GitHub Actions scaffold

Troubleshooting

"Unable to find module dependency" in CLI builds: Disable hardened runtime during development:

# project.yml
settings:
  base:
    ENABLE_HARDENED_RUNTIME: NO
    ENABLE_ENHANCED_SECURITY: NO

No code completion in Zed: Regenerate after building: just ios::setup-lsp

Device install fails: Ensure device is trusted and connected: just ios::devices