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
This commit is contained in:
Matthew Raymer
273
docs/IOS_CODE_SIGNING.md
Normal file
273
docs/IOS_CODE_SIGNING.md
Normal file
@@ -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
|
||||
<key>CFBundleIdentifier</key>
|
||||
<string>com.yourcompany.yourapp</string>
|
||||
```
|
||||
- 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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user