dbmrq/agent-skills/xcodegen

XcodeGen

Spec reference: ProjectSpec · Usage

New apps: use [ios-bootstrap](../ios-bootstrap/SKILL.md) first (starter project.yml, ai-rules-ios, SwiftLint/SwiftFormat/Periphery, SWIFT_TREAT_WARNINGS_AS_ERRORS). This skill is the deep XcodeGen reference.

Assume the agent knows YAML and that XcodeGen generates .xcodeproj from a spec. This skill covers behavior that is easy to get wrong.

Agent workflow

1. Read existing project.yml and any include: files before editing.
2. After changes, run xcodegen generate (add --use-cache only when the repo already uses caching hooks).
3. On unexpected output, run xcodegen dump --type json to inspect the resolved spec after includes/templates merge.
4. Build in Xcode or xcodebuild to confirm targets, schemes, and dependencies — generation succeeding does not prove linking is correct.

Required quality settings (Leio / ai-rules apps)

When the repo uses ai-rules-ios, every Swift target must include:

settings:
  base:
    SWIFT_TREAT_WARNINGS_AS_ERRORS: "YES"

The application target that runs the Quality Check script also needs:

settings:
  base:
    ENABLE_USER_SCRIPT_SANDBOXING: NO
preBuildScripts:
  - name: Quality Check
    basedOnDependencyAnalysis: false
    script: |
      set -euo pipefail
      cd "${SRCROOT}"
      ./scripts/check.sh

Snippets live under .ai-rules/quality/xcodegen/ after install. Do not invent a second lint stack inside project.yml.

Include merge semantics

Includes merge additively by default:

`:REPLACE` suffix — force wholesale replacement instead of merge:

include:
  - base.yml
targets:
  MyTarget:          # defined in base.yml
    sources:REPLACE:
      - only/these/sources

Other include gotchas:

• relativePaths: false on an include makes paths in that file relative to the root spec, not the included file.
• enable: ${ENV_VAR} can conditionally skip an include.
• Target names can be overridden by adding name: on a target entry.
• Comma-separated --spec a.yml,b.yml merges multiple root specs (same flags apply to all).

Settings traps

Silent ignore of simple maps

If settings uses groups, base, or configs, a flat key-value map at the same level is silently ignored:

# MARKETING_VERSION is IGNORED; only CURRENT_PROJECT_VERSION applies
settings:
  MARKETING_VERSION: 100.0.0
  base:
    CURRENT_PROJECT_VERSION: 100.0

Merge order within a Settings object: groups → base → configs.

Config name matching

configs: keys match case-insensitively and by substring — except exact matches, which apply only to that config:

settings:
  configs:
    staging:          # applies to "Staging Debug" AND "Staging Release"
      SWIFT_ACTIVE_COMPILATION_CONDITIONS: STAGING
    Release:          # applies ONLY to "Release", not "Staging Release"
      SWIFT_OPTIMIZATION_LEVEL: -O

Presets vs xcconfig hierarchy

XcodeGen layers settings: setting presets → groups/base/configs → xcconfig (highest). xcconfig values also overwrite preset defaults. Build setting keys must be the raw names (IPHONEOS_DEPLOYMENT_TARGET), not Xcode display titles.

options.settingPresets: none disables Xcode-like defaults — useful when xcconfig owns everything, but then you must set all required settings explicitly.

Custom configs drop preset build settings

Config types other than debug or release (e.g. none) receive no default Debug/Release build settings from XcodeGen:

configs:
  Debug: debug
  Beta: release      # gets release-type defaults
  Custom: none       # gets NO debug/release defaults

options.defaultConfig sets the CLI default; if unset, the first config alphabetically wins.

Sources — filtering and representation

excludes / includes paths

excludes and includes are relative to the source entry's path, not project.yml. Globstar ** is enabled (Bash 4 glob). When both are set, excludes win over includes.

Source type changes Xcode behavior

options.defaultSourceDirectoryType sets the default when a directory omits type.

Other source gotchas

• Info.plist is never added to any build phase, regardless of buildPhase.
• optional: true skips missing-path validation.
• inferDestinationFiltersByPath: true filters by **/ios/* and *_iOS.swift path patterns; ignored if destinationFilters is set.
• Overriding options.fileTypes for a built-in extension requires providing all fields for that extension.

Multiplatform and destinations

platform: [iOS, tvOS] (array)

Generates separate targets per platform with default suffix _${platform} (override via platformPrefix / platformSuffix). ${platform} in the spec is substituted. Shared PRODUCT_NAME defaults to the logical name so imports stay consistent.

supportedDestinations (Xcode 14+)

Single target, multiple destinations. platform becomes auto. Use destinationFilters on sources and dependencies.

watchOS apps — supportedDestinations does not support watchOS for app targets. Create a separate target with platform: watchOS.

inferDestinationFiltersByPath helps split shared source trees; explicit destinationFilters is more predictable.

Dependencies — integration specifics

Target / project reference

projectReferences:
  FooLib:
    path: path/to/FooLib.xcodeproj
targets:
  App:
    dependencies:
      - target: FooLib/SomeTarget   # ProjectName/TargetName

Carthage

• carthage: helper is for .framework in Carthage/Build/PLATFORM/ — not XCFrameworks. For XCFrameworks use framework:.
• findFrameworks: true (or global options.findCarthageFrameworks) reads Carthage .version files — Carthage must be built before xcodegen generate.
• The name in the spec must match the .version filename, which can differ from repo or framework name.
• Static Carthage frameworks live under PLATFORM/Static/; set linkType: static.
• directlyEmbedCarthageDependencies defaults true except for iOS/tvOS/watchOS applications (those use the copy-frameworks script).
• visionOS does not support Carthage.

Swift Packages

• Declared at project packages:; linked per-target via dependencies: - package: Name (optional product: or products:).
• Known limitation: SPM integration breaks when the project has configs beyond Debug/Release (SR-10927).
• Pin versions via ProjectName.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved.
• Local packages default to a Packages group; localPackagesGroup: "" puts them at project root. excludeFromProject: true omits from generated project.

Static library + bundle in another project

dependencies:
  - bundle: MyResourceBundle   # copies pre-built bundle into resources

Only for target types that can copy resources; pairs with static libs that vend bundles elsewhere.

Linking defaults worth overriding

SDK dependency root

dependencies:
  - sdk: Platforms/iPhoneOS.platform/Developer/Library/Frameworks/XCTest
    root: DEVELOPER_DIR

Default root is BUILT_PRODUCTS_DIR.

Schemes

Auto-generated target schemes (target.scheme)

configVariants creates one scheme per variant, matching configs whose names contain the variant string (e.g. Staging → Staging Debug / Staging Release).

Manual schemes

• schemePathPrefix defaults to "../../" (standalone .xcodeproj). Use "../" inside .xcworkspace — affects relative paths like StoreKit configs and GPX files.
• Custom GPX for simulateLocation must be listed in fileGroups to be found.
• Test plans are not generated — create .xctestplan in Xcode, check in, reference by path. Renaming test targets may require updating plans in Xcode.
• selectedTests overrides skippedTests when both are set.

Coverage / test target references

coverageTargets:
  - MyTarget
  - ExternalProj/OtherTarget
  - package: LocalPackage/TestTarget

Generated plists

info: and entitlements: rewrite files on every generation. Do not hand-edit generated plists without moving the source of truth into the spec. INFOPLIST_FILE in settings overrides auto-generated info: for that config.

Auto-generated Info.plist keys include bundle identifiers and version fields; CFBundleExecutable is not generated for bundle targets.

Cache and CLI behavior

xcodegen generate --spec path/to/project.yml --project output/dir
xcodegen generate --use-cache          # skip regen when spec unchanged
xcodegen cache                         # refresh cache without generating (for git hooks)
xcodegen dump --type json              # resolved spec after includes/templates

Recommended git hooks (from XcodeGen FAQ): post-checkout / post-merge / post-rewrite → xcodegen generate --use-cache; pre-commit → xcodegen cache.

Environment variables in spec strings: ${VAR_NAME}.

Validation toggles

When sharing YAML across projects or generating in CI without all files present:

options:
  disabledValidations:
    - missingConfigs
    - missingConfigFiles
    - missingTestPlans

Common failure modes

Templates

targetTemplates / schemeTemplates merge via templates: list. Placeholders:

• ${target_name} / ${scheme_name} — resolved name
• ${attributeName} — from templateAttributes on the referencing target/scheme