DOCSEARCHbyAlgolia
Submit Docs

XcodeGen Documentation

repository·master·Indexed 27 days ago

https://github.com/yonaskolb/xcodegen

A Swift-based command line tool that generates Xcode projects from YAML or JSON project specifications. It enables developers to manage project files via code, reducing merge conflicts in .xcodeproj files and keeping Xcode groups synchronized with the disk structure. Features include support for multiple spec files via includes, custom build settings, target definitions, and integration with CocoaPods and Git hooks.

Tokens
12.3K
Snippets
41
Records
58
Agent score
86%

What's inside XcodeGen

  1. Simulate Location in Schemes

    master

    Enable location simulation for the run action using the simulateLocation key.

    • allow: Set to true to enable simulation.
    • defaultLocation: Set a predefined location (e.g., San Francisco, CA, USA) or a path to a custom .gpx file.

    Note: If using a custom .gpx file, you must add it to the target's fileGroups so Xcode can access it.

    targets:
  MyTarget:
    fileGroups:
      - location.gpx

  3. Automate project generation with Git hooks

    master

    To ensure your Xcode project stays in sync with your file system when switching branches, merging, or rebasing, you can automate xcodegen using Git hooks.

    • For post-checkout, post-rewrite, and post-merge hooks: Run xcodegen generate --use-cache to update the project file.
    • For the pre-commit hook: Run xcodegen cache to ensure the cache is updated with any local changes or new files before committing.
    # Example commands for git hooks
xcodegen generate --use-cache
xcodegen cache

  4. Use Swift Package Build Tool Plugins

    master

    To use Swift Package plugins, you must define the package at the project level and then connect the plugin to your target using buildToolPlugins.

    packages:
  Prefire:
    url: https://github.com/BarredEwe/Prefire
    from: 1.3.0
targets:
  App:
    buildToolPlugins:
      - plugin: PrefirePlaybookPlugin
        package: Prefire

  5. Use Target Templates for reusable target configurations

    master

    Target Templates allow you to define a base configuration that can be referenced by multiple targets using the templates property.

    Key features:

    • Variable Substitution: Use ${target_name} within a template to automatically inject the name of the target referencing it.
    • Template Attributes: Use templateAttributes on a target to provide values for custom placeholders (e.ical ${attribute_name}) defined within the template.

    This reduces duplication when multiple targets share similar platforms, types, or source structures.

    targets:
  MyFramework:
    templates: 
      - Framework
    templateAttributes:
      frameworkName: AwesomeFramework
    sources:
      - SomeSources
targetTemplates:
  Framework:
    platform: iOS
    type: framework
    sources:
      - ${frameworkName}/${target_name}

  7. Install XcodeGen

    master

    XcodeGen can be installed using several different package managers. Ensure you have the latest stable version of Xcode installed before proceeding.

    Mint

    mint install yonaskolb/xcodegen

    Homebrew

    brew install xcodegen

    Make

    git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
make install

    Swift Package Manager

    As a CLI tool:

    git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
swift run xcodegen

    As a dependency: Add the package to your Package.swift and import XcodeGenKit in your code.

    .package(url: "https://github.com/yonaskolb/XcodeGen.git", from: "2.46.0"),

  8. Integrate CocoaPods with XcodeGen

    master

    You can use CocoaPods with XcodeGen by running pod install immediately after generating the project.

    To optimize this workflow, it is recommended to use the --use-cache flag combined with the postGenCommand option in your project.yml. This configuration ensures that pod install is only executed if the project actually required regeneration.

  9. Setup code signing in XcodeGen

    master
    XcodeGen does not have dedicated high-level options for code signing. Instead, code signing must be configured using standard Xcode build settings within your configuration. To enable code signing, you must define the DEVELOPMENT_TEAM and, if necessary, the CODE_SIGN_STYLE build settings.

  10. Include and merge multiple specification files

    master

    You can split your project specification into multiple files using the include key. This allows for modularity and sharing between specs.

    Included specs are merged in order, with the current spec's values applied on top. By default, merging is additive:

    • Dictionaries: Merged recursively.
    • Arrays: New values are appended to the end.
    • Other types: The new value replaces the old one.

    To force a replacement of an entire dictionary or array instead of merging, append :REPLACE to the key.

    An include can be a simple string (path) or an object for more control.

    include:
  - includedFile.yml
  - path: path/to/includedFile.yml
    relativePaths: false
    enable: ${INCLUDE_ADDITIONAL_YAML}

name: CustomSpec
targets:
  MyTarget: # target lives in base.yml
    sources:REPLACE:
      - my_new_sources

  11. Integrate Carthage dependencies

    master

    XcodeGen automates the linking and embedding of Carthage frameworks. It also automatically creates the build phase to run carthage copy-frameworks.

    Key Options:

    • options.findCarthageFrameworks: If true, XcodeGen automatically finds all frameworks vendored by a dependency (e.g., finding both ReactiveCocoa and ReactiveMapKit when only ReactiveCocoa is listed). Requires Carthage to have already built the frameworks so .version files exist in Carthage/Build.
    • options.carthageExecutablePath: Allows overriding the carthage command (e.g., using mint).
    • options.carthageBuildPath: Changes the directory where XcodeGen looks for frameworks (defaults to Carthage/Build).
    options:
  findCarthageFrameworks: true
targets:
  App:
    dependencies:
      - carthage: ReactiveCocoa
      - carthage: OtherCarthageDependency
        findFrameworks: false # disables the global option

  12. Configure Swift Package Dependencies

    master

    To use Swift Packages, first define them in the top-level packages section, then reference them in your target's dependencies.

    packages:
  Yams:
    url: https://github.com/jpsim/Yams
    majorVersion: 2.0.0
  SwiftPM:
    url: https://github.com/apple/swift-package-manager
    branch: swift-5.0-branch
targets:
  App:
    dependencies:
      - package: Yams 
      - package: SwiftPM
        product: SPMUtility