Skip to content

Latest commit

 

History

History
154 lines (111 loc) · 10.4 KB

ConfigFile.md

File metadata and controls

154 lines (111 loc) · 10.4 KB
Raw

SwiftGen Configuration File

SwiftGen expects you to have a swiftgen.yml configuration file at the root of your repository, to specify which files to parse, what template to use, and where to write the generated files.

Creating a Config file

To create your configuration file, you can use the swiftgen config init command.

This will create (and open) an example configuration file that you can use for inspiration, with some typical entries commented out. All you have to do is to then uncomment the parts of the config that you need, adapt them to your project, and/or copy&paste the examples to add configuration for additional parsers.

You can of course also create the swiftgen.yml configuration file manually from scratch, using the text editor of your choice. The file just has to be in YAML format (note: JSON, being a subset of YAML, is also supported) and provide the keys described below.

For more options (like using a file at another path or with another name, checking your config file for errors, …), see further below.

Configuration File Format

Global Structure

The configuration file is a YAML file structured like this (example):

input_dir: Sources/Resources
output_dir: Sources/Generated/
strings:
  inputs: Base.lproj
  filter: .+\.strings$
  outputs:
    - templateName: structured-swift5
      output: L10n-Constants.swift
xcassets:
  - inputs: Logos.xcassets
    outputs:
      - templateName: swift5
        output: Logos-Constants.swift
        params:
          enumName: Logos
  - inputs:
      - Colors.xcassets
      - Images.xcassets
    outputs:
      - templatePath: Resources/my-assets-custom-template.stencil
        output: Assets-Constants.swift

ℹ️ All relative paths specified in the configuration file (input_dir, output_dir, inputs, templatePath, output) are relative to the location of the configuration file itself.

💡 We advise against using absolute paths — starting with / — in the configuration file, so that they won't rely on where the project was cloned on your machine.

Keys details

Here's a quick description of all the possible root keys. All of them are optional.

Key Description Intended usage
input_dir If present, it is prepended to all input inputs keys used in the rest of the configuration file This is useful to avoid repeating any common subdirectory everywhere in each inputs key, when all your input paths are all in subdirectories of a common parent folder.
output_dir If present, it is prepended to all output keys used in the rest of the configuration file This is useful if, like most people, you want all files generated by SwiftGen to be generated in a common directory like Sources/Generated/ for example.
colors Describe the parameters to run with the colors parser See below for a detail of all the subkeys.
coredata Describe the parameters to run with the coredata parser See below for a detail of all the subkeys.
fonts Describe the parameters to run with the fonts parser See below for a detail of all the subkeys.
ib Describe the parameters to run with the ib parser See below for a detail of all the subkeys.
json Describe the parameters to run with the json parser See below for a detail of all the subkeys.
plist Describe the parameters to run with the plist parser See below for a detail of all the subkeys.
strings Describe the parameters to run with the strings parser See below for a detail of all the subkeys.
xcassets Describe the parameters to run with the xcassets parser See below for a detail of all the subkeys.
yaml Describe the parameters to run with the yaml parser See below for a detail of all the subkeys.

Each key corresponding to a SwiftGen parser (colors, coredata, fonts, ib, json, plist, strings, xcassets, yaml) expects the corresponding value to be:

  • Either a dictionary, with the keys described below, if you want to invoke the corresponding SwiftGen parser only once (most common use case)
  • Or an array of those dictionaries, in the less common case where you need to invoke that SwiftGen parser multiple times (for example to use one template with some input files and another template for other input files…)
Subkey Type Description
inputs Path or Array of Paths The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the xcassets command, or your .lproj or Localizable.strings file for the strings command, etc).
options Dictionary Any optional list of settings for the parser, to change its behaviour. See the commands' specific documentation for available options.
filter Regular Expression The regular expression to apply to each input path; only paths matching the given filter will be used. Filters are applied to actual (relative) paths, not just the filename. Note that each command has a default built-in filter (based on expected file extensions), so you generally don't need to specify this subkey in your config file; but it is useful if you want to override it with a custom filter.
outputs Array A list of output descriptions, composed of a template and a file output.
paths Path or Array of Paths Deprecated The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the xcassets command, or your Localizable.strings file for the strings command, etc).
templateName String Deprecated The name of the template to use. If you provide a value for this, you shouldn't also provide a value for templatePath.
templatePath Path Deprecated The path to the template to use. If you provide a value for this, you shouldn't also provide a value for templateName.
output Path Deprecated The path of the output file to generate. (Note: Any intermediate directory up to this file must already exist.)
params Dictionary Deprecated Any optional parameter you want to pass to the template (similarly to --param in the CLI).

💡 Tip: For custom file filters, use .+ to match multiple characters (at least one), and don't forget to escape the dot (\.) if you want to match a literal dot like for an extension. Add $ at the end to ensure the path ends with the extension you want. Regular expressions will be case sensitive by default, and not anchored to the start/end of a path. For example, use .+\.xib$ to match files with a .xib extension. Use a tool such as RegExr to ensure you're using a valid regular expression.

The outputs parameter accepts either a dictionary, or an array of dictionaries, with the keys described below. Each such "output" will take the input files, and use the output template to generate a file at the given output path. This allows you to generate multiple outputs for the same input files (which will only be parsed once).

Subkey Type Description
templateName String The name of the template to use. If you provide a value for this, you shouldn't also provide a value for templatePath.
templatePath Path The path to the template to use. If you provide a value for this, you shouldn't also provide a value for templateName.
output Path The path of the output file to generate. (Note: Any intermediate directory up to this file must already exist.)
params Dictionary Any optional parameter you want to pass to the template. See the template documentation in GitHub (or using swiftgen template doc command) for the list of available params each template supports.

Note that:

  • inputs and outputs are mandatory.
  • You must specify either templateName or templatePath, but not both, nor neither.
  • params is optional.

Environment Variables

You can use environment variables in your config file, by using the ${VARNAME} syntax. Those environment variables will be expanded when SwiftGen parses the config file.

If you're running swiftgen as part of a Script Build Phase in Xcode, this especially allows you to inject values coming from Xcode's build settings (as Xcode expose those as env vars) into your config file. For example:

strings:
  inputs: ${PROJECT_DIR}/${TARGET_NAME}/Resources/
  outputs:
    templateName: structured-swift5
    output: ${PROJECT_DIR}/${TARGET_NAME}/Constants/Strings-${TARGET_NAME}.swift

Advanced options for running the config file

Running swiftgen without any subcommand or argument is actually a shortcut invocation which is equivalent to running swiftgen config run.

If you need more control when using a configuration file, you can use some advanced features by using the full swiftgen config run command to specify more options. In particular you can:

  • Ask to use a different config file — instead of the default swiftgen.yml — using the --config flag.

    swiftgen config run --config tools/swiftgen/swiftgen-config.yml

  • When you want to create a new config file, you can also provide an alternate path where to create the file with a similar --config flag.

    swiftgen config init --config tools/swiftgen/swiftgen-config.yml

  • Enable the verbose mode, which will print every command being executed when executing it, using the --verbose flag. This allows your to:

    • control what is being run, by logging what happens during execution
    • know the equivalent command to type if you were to run each swiftgen command manually instead of using the config file — which can be useful if you need to debug or tweak a particular command in isolation for example
    swiftgen config run --verbose

Linting the configuration file

You can also use swiftgen config lint (or Pods/SwiftGen/bin/swiftgen config lint if you installed it using CocoaPods) to lint the configuration file.

Without any additional option this will lint the default swiftgen.yml configuration file, but you can specify a different configuration file using the --config flag, similarly to swiftgen config run

swiftgen config lint will ensure that:

  • the YAML file is a valid YAML
  • each mandatory key in the YAML is present
  • each key is of the expected type.

It will print a descriptive error in case there's something wrong, and describe the interpretation of the content of the configuration file if everything is valid.