Skip to content

Usage.md

Latest commit

 

History

History
140 lines (109 loc) · 5.37 KB

Usage.md

File metadata and controls

140 lines (109 loc) · 5.37 KB

Configuring build settings

There are various ways of configuring build settings

Xcode resolves a certain build setting for a configuration and target by looking up the different levels until it finds a value. This can be seen in Xcode when the Levels option is on in the Build Settings tab. The different levels of build settings are:

  • target
  • target xcconfig file
  • project
  • project xcconfig file
  • sdk defaults

XcodeGen will apply settings to a target or project level by merging different methods

The values from xcconfig files will then sit a level above this. Note that as a convenience, any settings in an xcconfig file will also overwrite any settings from Setting Presets

Note that when defining build settings you need to know the write name and value. In Xcode build settings are shown by default with a nicely formatted title and value. To be able to see what the actual build setting names and values are make sure you're in a Build Settings tab and go Editor -> Show Setting Titles and also Editor -> Show Definitions. This will then give you the actual names and values that XcodeGen expects.

Setting Presets

XcodeGen applies default settings to your project and targets similar to how Xcode creates them when you create a new project or target. Debug and Release settings will be applied to your project. Targets will also get specific settings depending on the platform and product type.

You can change or disable how these setting presets are applied via the options.settingPresets which you can find more about in Options

Settings

The project and each target have a settings object that you can define. This can be a simple map of build settings or can provide build settings per config via configs or base. See Settings for more details.

settings:
  DEVELOPMENT_TEAM: T45H45J
targets:
  App:
    settings:
      base:
        CODE_SIGN_ENTITLEMENTS: App/Entitlements.entitlements
      configs:
        Debug:
          DEBUG_MODE: YES
        Release:
          DEBUG_MODE: NO

Setting Groups

Each settings can also reference one or more setting groups which let you reuse groups of build settings across targets or configurations. See Setting Groups for more details. Note that each setting group is also a full Settings object, so you can reference other groups or define settings by config.

settingGroups:
  app:
    DEVELOPMENT_TEAM: T45H45J
targets:
  App:
    settings:
      groups: [app]

xcconfig files

The project and each target have a configFiles object that lets you reference .xcconfig files per configuration.

This is good guide to xcconfig files https://pewpewthespells.com/blog/xcconfig_guide

configFiles:
  Debug: debug.xcconfig
  Release: release.xcconfig
targets:
  App:
    configFiles:
      Debug: App/debug.xcconfig
      Release: App/release.xcconfig

xcodebuild environment variables

You can also always overide any build settings on CI when building by passing specific build settings to xcodebuild like so:

DEVELOPMENT_TEAM=XXXXXXXXX xcodebuild ...

Use dependencies

Each target can declare one or more dependencies. See Dependency in the ProjectSpec for more info about all the properties

Cocoapods

Use your podfile as normal. The pods themselves don't need to be referenced in the project spec. After you generate your project simply run pod install which will integrate with your project and create a workspace.

Carthage

XcodeGen makes integrating Carthage dependencies super easy!

You simply reference them in each target that requires them and XcodeGen does the rest by automatically linking and embedding the carthage frameworks where necessary.

targets:
  App:
    dependencies:
      - target: Framework
      - carthage: Kingfisher
  Framework:
    dependencies:
      - carthage: Alamofire

XcodeGen automatically creates the build phase that Carthage requires which lists all the files and runs carthage copy-frameworks. You can change the invocation of carthage to something different, for example if you are running it with Mint. This is then prepended to copy frameworks

options:
  carthageExecutablePath: mint run Carthage/Carthage carthage

By default XcodeGen looks for carthage frameworks in Carthage/Build. You can change this with the carthageBuildPath option

options:
  carthageBuildPath: ../../Carthage/Build

SDK

System frameworks and libs can be linked by using the sdk dependency type. You can either specify frameworks or libs by using a .framework or .tbd filename, respectively

targets:
  App:
    dependencies:
      - sdk: Contacts.framework
      - sdk: libc++.tbd