Then execute pod install --repo-update (or pod update SwiftGen if you want to update an existing SwiftGen installation) to download and install the SwiftGen binaries and dependencies in Pods/SwiftGen/bin/swiftgen next to your project.

Given that you can specify an exact version for SwiftGen in your Podfile, this allows you to ensure all coworkers will use the same version of SwiftGen for this project.

You can then invoke SwiftGen in your Script Build Phase using:

$PODS_ROOT/SwiftGen/bin/swiftgen …

Similarly, be sure to use Pods/SwiftGen/bin/swiftgen instead of just swiftgen where we mention commands with swiftgen in the rest of the documentation.

Note: SwiftGen isn't really a pod, as it's not a library your code will depend on at runtime; so the installation via CocoaPods is just a trick that installs the SwiftGen binaries in the Pods/ folder, but you won't see any swift files in the Pods/SwiftGen group in your Xcode's Pods.xcodeproj. That's normal: the SwiftGen binary is still present in that folder in the Finder.

This will install SwiftGen system-wide. The same version of SwiftGen will be used for all projects on that machine, and you should make sure all your coworkers have the same version of SwiftGen installed on their machine too.

You can then invoke swiftgen directly in your Script Build Phase (as it will be in your $PATH already):

swiftgen …

Note: SwiftGen needs Xcode 8.3 to build, so installing via Homebrew requires you to have Xcode 8.3 installed (which in turn requires macOS 10.12). If you use an earlier version of macOS, you'll have to use one of the other installation methods instead.

Compile from source(only recommended if you need features from master or want to test a PR)

This solution is when you want to build and install the latest version from master and have access to features which might not have been released yet.

If you have homebrew installed, you can use the following command to build and install the latest commit:

brew install swiftgen --HEAD

Alternatively, you can clone the repository and use rake cli:install to build the tool and install it from any branch, which could be useful to test SwiftGen in a fork or a Pull Request branch.

Some Ruby tools are used in the build process, and the system Ruby works well if you are running a recent macOS. However, if you are using rbenv you can run rbenv install to make sure you have a matching version of Ruby installed.

You can now install to the default locations (no parameter) or to custom locations:

# Binary is installed in `./build/swiftgen/bin`, frameworks in `./build/swiftgen/lib` and templates in `./build/swiftgen/templates`
$ rake cli:install
# - OR -# Binary will be installed in `~/swiftgen/bin`, frameworks in `~/swiftgen/fmk` and templates in `~/swiftgen/tpl`
$ rake cli:install[~/swiftgen/bin,~/swiftgen/fmk,~/swiftgen/tpl]

You can then invoke SwiftGen using the path to the binary where you installed it:

~/swiftgen/bin/swiftgen …

Or add the path to the bin folder to your $PATH and invoke swiftgen directly.

Usage

SwiftGen is provided as a single command-line tool which uses a configuration file to run various actions (subcommands).

Each action described in the configuration file (strings, fonts, ib, …) typically corresponds to a type of input resources to parse (strings files, IB files, Font files, JSON files, …), allowing you to generate constants for each types of those input files.

To use SwiftGen, simply create a swiftgen.yml YAML file to list all the subcommands to invoke, and for each subcommand, the list of arguments to pass to it. For example:

Then you just have to invoke swiftgen config run, or even just swiftgen for short, and it will execute what's described in the configuration file

To learn more about the configuration file — its more detailed syntax and possibilities, how to pass custom parameters, using swiftgen config lint to validate it, how to use alternate config files, and other tips — see the dedicated documentation.

There are also additional subcommands you can invoke from the command line to manage and configure SwiftGen:

The swiftgen config subcommand to help you with the configuration file, especially swiftgen config lint to validate that your Config file is valid and has no errors

Lastly, you can use --help on swiftgen or one of its subcommand to see the detailed usage.

Directly invoking a subcommand

While we highly recommend the use a configuration file for performance reasons (especially if you have multiple outputs, but also because it's more flexible), it's also possible to directly invoke the available subcommands to parse various resource types:

swiftgen colors [OPTIONS] DIRORFILE1 …

swiftgen coredata [OPTIONS] DIRORFILE1 …

swiftgen fonts [OPTIONS] DIRORFILE1 …

swiftgen ib [OPTIONS] DIRORFILE1 …

swiftgen json [OPTIONS] DIRORFILE1 …

swiftgen plist [OPTIONS] DIRORFILE1 …

swiftgen strings [OPTIONS] DIRORFILE1 …

swiftgen xcassets [OPTIONS] DIRORFILE1 …

swiftgen yaml [OPTIONS] DIRORFILE1 …

One rare cases where this might be useful — as opposed to using a config file — is if you are working on a custom template and want to quickly test the specific subcommand you're working on at each iteration/version of your custom template, until you're happy with it.

Each subcommand generally accepts the same options and syntax, and they mirror the options and parameters from the configuration file:

--output FILE or -o FILE: set the file where to write the generated code. If omitted, the generated code will be printed on stdout.

--templateName NAME or -n NAME: define the Stencil template to use (by name, see here for more info) to generate the output.

--templatePath PATH or -p PATH: define the Stencil template to use, using a full path.

Note: you should specify one and only one template when invoking SwiftGen. You have to use either -t or -p but should not use both at the same time (it wouldn't make sense anyway and you'll get an error if you try)

--filter REGEX or -f REGEX: the filter to apply to each input path. Filters are applied to actual (relative) paths, not just the filename. Each command has a default filter that you can override with this option.

Note: 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.

You can always use the --help flag to see what options a command accept, e.g. swiftgen xcassets --help.

Choosing your template

SwiftGen is based on templates (it uses Stencil as its template engine). This means that you can choose the template that fits the Swift version you're using — and also the one that best fits your preferences — to adapt the generated code to your own conventions and Swift version.

Bundled templates vs. Custom ones

SwiftGen comes bundled with some templates for each of the subcommand (colors, coredata, fonts, ib, json, plist, strings, xcassets, yaml), which will fit most needs. But you can also create your own templates if the bundled ones don't suit your coding conventions or needs. Simply either use the templateName output option to specify the name of the template to use, or store them somewhere else (like in your project repository) and use templatePath output option to specify a full path.

💡 You can use the swiftgen templates list command to list all the available templates (both custom and bundled templates) for each subcommand, list the template content and dupliate them to create your own.

Templates bundled with SwiftGen:

As explained above, you can use swiftgen templates list to list all templates bundled with SwiftGen. For most SwiftGen subcommands, we provide, among others:

A swift3 template, compatible with Swift 3

A swift4 template, compatible with Swift 4

Other variants, like flat-swift3/4 and structured-swift3/4 templates for Strings, etc.

You can find the documentation for each bundled template here in the repo, with documentation organized as one folder per SwiftGen subcommand, then one MarkDown file per template.
Each MarkDown file documents the Swift Version it's aimed for, the use case for that template (in which cases you might favor that template over others), the available parameters to customize it on invocation (using the params: key in your config file), and some code examples.

Don't hesitate to make PRs to share your improvements suggestions on the bundled templates 😉

Additional documentation

Playground

The SwiftGen.playground available in this repository will allow you to play with the code that the tool typically generates, and see some examples of how you can take advantage of it.

This allows you to have a quick look at how typical code generated by SwiftGen looks like, and how you will then use the generated constants in your code.

Dedicated Documentation in Markdown

There is a lot of documentation in the form of Markdown files in this repository, and in the related StencilSwiftKit repository as well.

Especially, in addition to the previously mentioned Migration Guide and Configuration File documentation, the Documentation/ folder in the SwiftGen repository also includes:

A templates subdirectory that details the documentation for each of the templates bundled with SwiftGen (when to use each template, what the output will look like, and custom parameters to adjust them, …)

A SwiftGenKit Contexts subdirectory that details the structure of the "Stencil Contexts", i.e. the Dictionary/YAML representation resulting of parsing your input files. This documentation is useful for people wanting to write their own templates, so that they know the structure and various keys available when writing their template, to construct the wanted generated output accordingly.

Various articles to provide best practices & tips on how to better take advantage of SwiftGen in your projects:

Usage Example

// You can create new images with the convenience constructor like this:let bananaImage =UIImage(asset: Asset.Exotic.banana) // iOSlet privateImage =NSImage(asset: Asset.private) // macOS// Or as an alternative, you can refer to enum instance and call .image on it:let sameBananaImage = Asset.Exotic.banana.imagelet samePrivateImage = Asset.private.image

Colors

This will generate a enum ColorName with one case per color listed in the text file passed as argument.

The input file is expected to be either:

a plain text file, with one line per color to register, each line being composed by the Name to give to the color, followed by ":", followed by the Hex representation of the color (like rrggbb or rrggbbaa, optionally prefixed by # or 0x) or the name of another color in the file. Whitespaces are ignored.

a JSON file, representing a dictionary of names -> values, each value being the hex representation of the color

a XML file, expected to be the same format as the Android colors.xml files, containing tags <color name="AColorName">AColorHexRepresentation</color>

Usage Example

// You can create colors with the convenience constructor like this:let title =UIColor(named: .articleBody) // iOSlet footnote =NSColor(named: .articleFootnote) // macOS// Or as an alternative, you can refer to enum instance and call .color on it:let sameTitle = ColorName.articleBody.colorlet sameFootnote = ColorName.articleFootnote.color

This way, no need to enter the color red, green, blue, alpha values each time and create ugly constants in the global namespace for them.

Core Data

This will parse the specified core data model(s), generate a class for each entity in your model containing all the attributes, and a few extensions if needed for relationships and predefined fetch requests.

Fonts

This will recursively go through the specified directory, finding any typeface files (TTF, OTF, …), defining a struct FontFamily for each family, and an enum nested under that family that will represent the font styles.

JSON and YAML

This will parse the given file, or when given a directory, recursively search for JSON and YAML files. It will define an enum for each file (and documents in a file where needed), and type-safe constants for the content of the file.

Unlike other subcommands, this parser is intended to allow you to use more custom inputs (as the formats are quite open to your needs) to generate your code. This means that for these subcommands (and the plist one), you'll probably be more likely to use custom templates to generate code properly adapted/tuned to your inputs, rather than using the bundled templates. To read more about writing your own custom templates, see see the dedicated documentation.

Plists

This will parse the given file, or when given a directory, recursively search for Plist files. It will define an enum for each file (and documents in a file where needed), and type-safe constants for the content of the file.

Unlike other subcommands, this parser is intended to allow you to use more custom inputs (as the format is quite open to your needs) to generate your code. This means that for this subcommand (and the json and yaml ones), you'll probably be more likely to use custom templates to generate code properly adapted/tuned to your inputs, rather than using the bundled templates. To read more about writing your own custom templates, see see the dedicated documentation.

Strings

This will generate a Swift enum L10n that will map all your Localizable.strings (or other tables) keys to a static let constant. And if it detects placeholders like %@,%d,%f, it will generate a static func with the proper argument types instead, to provide type-safe formatting. Note that all dots within the key are converted to dots in code.

Reminder: Don't forget to end each line in your *.strings files with a semicolon ;! Now that in Swift code we don't need semi-colons, it's easy to forget it's still required by the Localizable.strings file format 😉