Skip to content

Latest commit

 

History

History
100 lines (72 loc) · 5.88 KB

ConfigFile.md

File metadata and controls

100 lines (72 loc) · 5.88 KB
Raw

SwiftGen Configuration File

In order to avoid invoking SwiftGen manually multiple times — one for each subcommand — and having to remember each arguments to pass every time, you can instead use a YAML configuration file to configure everything.

Simply create a YAML file named swiftgen.yml at the root of your repository with the structure described below, then just run swiftgen (without any argument).

For more options (using a different file, checking your config file for errors…), see further below.

Configuration File Format

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

input_dir: Sources/Resources
output_dir: Sources/Generated/
strings:
  paths: Base.lproj/Localizable.strings
  templateName: structured-swift3
  output: L10n-Constants.swift
xcassets:
  - paths: Logos.xcassets
    templateName: swift3
    output: Logos-Constants.swift
    params:
      enumName: Logos
  - paths:
      - Colors.xcassets
      - Images.xcassets
    templatePath: customswift3
    output: Assets-Constants.swift

ℹ️ All relative paths specified in the configuration file (input_dir, output_dir, paths, 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._

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 paths keys used in the rest of the configuration file This is useful to avoid repeating any common subdirectory everywhere in each paths 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 subcommand See below for a detail of all the subkeys.
fonts Describe the parameters to run with the fonts subcommand See below for a detail of all the subkeys.
storyboards Describe the parameters to run with the storyboards subcommand See below for a detail of all the subkeys.
strings Describe the parameters to run with the strings subcommand See below for a detail of all the subkeys.
xcassets Describe the parameters to run with the xcassets subcommand See below for a detail of all the subkeys.

Each key corresponding to a SwiftGen subcommands (colors, fonts, storyboards, strings, xcassets) expects the corresponding value to be:

  • Either a dictionary, with the keys described below, if you want to invoke the corresponding SwiftGen subcommand only once (most common use case)
  • Or an array of those dictionaries, in the less common case where you need to invoke that SwiftGen subcommand multiple times (for example to use one template with some input files and another template for other input files…)
Subkey Type Description
paths 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 Localizable.strings file for the strings command, etc).
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 (similarly to --param in the CLI).

Similarly to when you invoke each subcommand of SwiftGen manually:

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

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

  • 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 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.