From 09a3d5159c73a990d0f17de6ba992ed5d9d4f375 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 11 Nov 2025 19:09:45 -0800 Subject: [PATCH] docs(ios): add comprehensive iOS code signing guide Created iOS code signing documentation: Signing Scenarios: - Simulator builds (signing disabled - faster) - Device builds with automatic signing (recommended) - Device builds with manual signing (advanced) Configuration: - Command-line build flags for each scenario - Xcode project settings - Environment variables Troubleshooting: - Common signing errors and solutions - Certificate and provisioning profile issues - Bundle identifier conflicts - Verification commands Quick Reference: - Simulator: CODE_SIGNING_REQUIRED=NO - Device (auto): CODE_SIGN_STYLE=Automatic + DEVELOPMENT_TEAM - Device (manual): CODE_SIGN_STYLE=Manual + PROVISIONING_PROFILE Updated SETUP.md: - Added code signing section - Quick reference for simulator vs device builds - Link to comprehensive guide Result: Complete signing guide for all iOS build scenarios --- docs/IOS_CODE_SIGNING.md | 273 ++++++++++++++++++++++++++++++++ test-apps/ios-test-app/SETUP.md | 45 ++++++ 2 files changed, 318 insertions(+) create mode 100644 docs/IOS_CODE_SIGNING.md diff --git a/docs/IOS_CODE_SIGNING.md b/docs/IOS_CODE_SIGNING.md new file mode 100644 index 0000000..397e3df --- /dev/null +++ b/docs/IOS_CODE_SIGNING.md @@ -0,0 +1,273 @@ +# iOS Code Signing Guide + +**Author**: Matthew Raymer +**Date**: 2025-11-12 +**Status**: Active + +## Overview + +iOS apps require code signing to run on devices or simulators. This guide explains how to handle signing for different scenarios. + +## Signing Scenarios + +### 1. Simulator Builds (Development) + +**For simulator builds, signing can be disabled:** + +```bash +xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,name=iPhone 15' \ + CODE_SIGN_IDENTITY="" \ + CODE_SIGNING_REQUIRED=NO \ + CODE_SIGNING_ALLOWED=NO \ + clean build +``` + +**Why this works:** +- Simulator doesn't require valid code signatures +- Faster builds (no signing overhead) +- No need for Apple Developer account + +### 2. Device Builds (Development) + +**For physical devices, you need proper signing:** + +#### Option A: Automatic Signing (Recommended) + +1. **Open Xcode project:** + ```bash + open App.xcworkspace + ``` + +2. **Configure in Xcode:** + - Select project in navigator + - Select target "App" + - Go to "Signing & Capabilities" tab + - Check "Automatically manage signing" + - Select your Team (Apple Developer account) + - Xcode will create provisioning profile automatically + +3. **Build from command line:** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk iphoneos \ + -configuration Debug \ + -destination 'generic/platform=iOS' \ + DEVELOPMENT_TEAM="YOUR_TEAM_ID" \ + CODE_SIGN_STYLE=Automatic \ + clean build + ``` + +#### Option B: Manual Signing + +1. **Get your Team ID:** + ```bash + # List available teams + security find-identity -v -p codesigning + ``` + +2. **Create provisioning profile** (via Apple Developer Portal or Xcode) + +3. **Build with explicit signing:** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk iphoneos \ + -configuration Debug \ + -destination 'generic/platform=iOS' \ + DEVELOPMENT_TEAM="YOUR_TEAM_ID" \ + CODE_SIGN_STYLE=Manual \ + PROVISIONING_PROFILE_SPECIFIER="Your Profile Name" \ + CODE_SIGN_IDENTITY="iPhone Developer" \ + clean build + ``` + +### 3. Command-Line Build Scripts + +**Update build scripts to handle both scenarios:** + +```bash +#!/bin/bash + +# Detect if building for simulator or device +SDK="${1:-iphonesimulator}" +DESTINATION="${2:-'platform=iOS Simulator,name=iPhone 15'}" + +if [ "$SDK" = "iphonesimulator" ]; then + # Simulator: Disable signing + xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk "$SDK" \ + -destination "$DESTINATION" \ + CODE_SIGN_IDENTITY="" \ + CODE_SIGNING_REQUIRED=NO \ + CODE_SIGNING_ALLOWED=NO \ + clean build +else + # Device: Use automatic signing + xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk "$SDK" \ + -configuration Debug \ + -destination 'generic/platform=iOS' \ + CODE_SIGN_STYLE=Automatic \ + DEVELOPMENT_TEAM="${DEVELOPMENT_TEAM:-}" \ + clean build +fi +``` + +## Common Signing Issues + +### Issue 1: "No signing certificate found" + +**Solution:** +```bash +# Check available certificates +security find-identity -v -p codesigning + +# If none found, create one in Xcode: +# Xcode > Preferences > Accounts > Select Team > Download Manual Profiles +``` + +### Issue 2: "Provisioning profile not found" + +**Solution:** +```bash +# List provisioning profiles +ls ~/Library/MobileDevice/Provisioning\ Profiles/ + +# Or use automatic signing (recommended) +# Xcode will create profiles automatically +``` + +### Issue 3: "Code signing is required for product type" + +**Solution:** +- For simulator: Add `CODE_SIGNING_REQUIRED=NO` +- For device: Configure signing in Xcode or provide `DEVELOPMENT_TEAM` + +### Issue 4: "Bundle identifier conflicts" + +**Solution:** +- Change bundle identifier in `Info.plist`: + ```xml + CFBundleIdentifier + com.yourcompany.yourapp + ``` +- Or use unique identifier for test apps + +## Project Configuration + +### Automatic Signing (Recommended) + +In Xcode project settings (`project.pbxproj` or Xcode UI): + +``` +CODE_SIGN_STYLE = Automatic; +DEVELOPMENT_TEAM = YOUR_TEAM_ID; +``` + +### Manual Signing + +``` +CODE_SIGN_STYLE = Manual; +CODE_SIGN_IDENTITY = "iPhone Developer"; +PROVISIONING_PROFILE_SPECIFIER = "Your Profile Name"; +``` + +## Environment Variables + +**Set these for command-line builds:** + +```bash +# For device builds +export DEVELOPMENT_TEAM="YOUR_TEAM_ID" +export CODE_SIGN_STYLE="Automatic" + +# For simulator builds (optional) +export CODE_SIGNING_REQUIRED="NO" +export CODE_SIGNING_ALLOWED="NO" +``` + +## Quick Reference + +### Simulator Build (No Signing) +```bash +xcodebuild ... \ + CODE_SIGN_IDENTITY="" \ + CODE_SIGNING_REQUIRED=NO \ + CODE_SIGNING_ALLOWED=NO +``` + +### Device Build (Automatic Signing) +```bash +xcodebuild ... \ + CODE_SIGN_STYLE=Automatic \ + DEVELOPMENT_TEAM="YOUR_TEAM_ID" +``` + +### Device Build (Manual Signing) +```bash +xcodebuild ... \ + CODE_SIGN_STYLE=Manual \ + CODE_SIGN_IDENTITY="iPhone Developer" \ + PROVISIONING_PROFILE_SPECIFIER="Profile Name" +``` + +## Testing Signing Configuration + +**Test if signing works:** + +```bash +# Check code signature +codesign -dv --verbose=4 /path/to/App.app + +# Verify signature +codesign --verify --verbose /path/to/App.app + +# Check entitlements +codesign -d --entitlements - /path/to/App.app +``` + +## Troubleshooting + +### Check Current Signing Status + +```bash +# In Xcode project directory +xcodebuild -showBuildSettings -workspace App.xcworkspace -scheme App | grep CODE_SIGN +``` + +### Clean Derived Data + +```bash +# Sometimes signing issues are cached +rm -rf ~/Library/Developer/Xcode/DerivedData +``` + +### Reset Signing in Xcode + +1. Open project in Xcode +2. Select target +3. Signing & Capabilities tab +4. Uncheck "Automatically manage signing" +5. Re-check "Automatically manage signing" +6. Select team again + +## Best Practices + +1. **Use Automatic Signing** for development (easiest) +2. **Disable signing for simulator** builds (faster) +3. **Use unique bundle IDs** for test apps +4. **Keep certificates updated** in Keychain +5. **Use environment variables** for team IDs in CI/CD + +## References + +- [Apple Code Signing Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/) +- [Xcode Signing Documentation](https://developer.apple.com/documentation/xcode/managing-your-team-s-signing-assets) +- [Capacitor iOS Setup](https://capacitorjs.com/docs/ios/configuration) + diff --git a/test-apps/ios-test-app/SETUP.md b/test-apps/ios-test-app/SETUP.md index 43842fd..c618a03 100644 --- a/test-apps/ios-test-app/SETUP.md +++ b/test-apps/ios-test-app/SETUP.md @@ -252,6 +252,51 @@ iOS handles background execution differently than Android: - **UserDefaults**: For schedules and configuration (like Android's SharedPreferences) - **Core Data**: For content cache and history (like Android's Room database) +## Code Signing + +### Simulator Builds (Default) + +**No signing required** - The build scripts automatically disable signing for simulator builds: + +```bash +CODE_SIGN_IDENTITY="" +CODE_SIGNING_REQUIRED=NO +CODE_SIGNING_ALLOWED=NO +``` + +This is handled automatically by the build scripts. + +### Device Builds + +**For physical devices, you need proper signing:** + +1. **Open project in Xcode:** + ```bash + cd test-apps/ios-test-app/App + open App.xcworkspace + ``` + +2. **Configure signing:** + - Select project in navigator + - Select target "App" + - Go to "Signing & Capabilities" tab + - Check "Automatically manage signing" + - Select your Team (Apple Developer account) + +3. **Build for device:** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme App \ + -sdk iphoneos \ + -configuration Debug \ + -destination 'generic/platform=iOS' \ + CODE_SIGN_STYLE=Automatic \ + DEVELOPMENT_TEAM="YOUR_TEAM_ID" \ + clean build + ``` + +**See `docs/IOS_CODE_SIGNING.md` for complete signing guide.** + ## Troubleshooting ### Plugin Not Found