Sourcery is a code generator for Swift projects. ObjectBox uses Sourcery to generate boilerplate code that passes information about your objects to the library. We chose code generation over fat inheritance trees so you can write plain Swift objects and just use these.

1. You can install Sourcery via CocoaPods, SwiftPM, as a binary download, via Homebrew, or build it from scratch. Please refer to the Sourcery README for instructions.

2. ​Add the Sourcery configuration​

3. ​Add the template files for generating code

4. ​Use the generated code in your project

Adding the Sourcery Build Phase to Your Project

In your Xcode project, add a "New Run Script Phase" and execute it before compiling your code. The code generator needs to generate the code you want to compile first.

We call the Build Phase "Update Sourcery Generated Files".

The template for this build phase is this:

set -e
​
sourcery="PATH/TO/SOURCERY"
​
if [ -f "$sourcery" ]; then
  "$sourcery"
else
  echo "error: Cannot find Sourcery in the expected location at '$sourcery'"
  exit -1
fi

Depending on how you install Sourcery, the program location (line 3) has to be changed.

We'll show a couple of examples how you locate and use the Sourcery program.

Homebrew

Install Sourcery via Homebrew, locate the binary, and then put the path into your Build Phase:

$ brew install sourcery
...
$ which sourcery
/usr/local/bin/sourcery

Results in:

set -e
​
sourcery="/usr/local/bin/sourcery"
​
if [ -f "$sourcery" ]; then
  "$sourcery"
else
  echo "error: Cannot find Sourcery in the expected location at '$sourcery'"
  exit -1
fi

CocoaPods

When you use CocoaPods, the Pods/ObjectBox/setup.rb script will have already set up the build phase for you.

SwiftPM

The Swift Package Manager compiles Sourcery from code into a .build directory next to your Package.swift file. The binary will be located at .build/release/sourcery once you compile the packages using swift build -c release. Your Build Phase will then read:

set -e
​
sourcery="$SRCROOT/../.build/release/sourcery"
​
if [ -f "$sourcery" ]; then
  "$sourcery"
else
  echo "error: Cannot find Sourcery in the expected location at '$sourcery'"
  exit -1
fi

Git Submodule

Just like SwiftPM, you download the code and build it with:

$ swift build --c release

The binary will be located at .build/release/sourcery. Assuming you put your submodules into a directory called "External" in your project root directory, your Build Phase has to read:

set -e
​
sourcery="$SRCROOT/../External/Sourcery/.build/release/sourcery"
​
if [ -f "$sourcery" ]; then
  "$sourcery"
else
  echo "error: Cannot find Sourcery in the expected location at '$sourcery'"
  exit -1
fi

Adding the Sourcery Configuration

Create a .sourcery.yml in your project root directory and paste in the following configuration, replacing the placeholder parts with your real project file name.

project:
  file: PROJECT_FILE.xcodeproj
  target:
    name: TARGET_NAME
    module: TARGET_OR_MODULE_NAME
templates:
  - ./templates/
output:
  path: ./generated/

Adding the Code Generator Template

Please download the built framework and copy the templates/ directory from that ZIP archive into your project root, as per the configuration above.

Adding the Generated Files to Your Project

Run Sourcery in your project directory once so it can create the generated/EntityInfo.generated.swift file for you. It will not contain much of interest, yet, but you can already drag & drop the "generated/" directory into your Xcode project so you are prepared (make sure you add folders as "groups", not as "folder references").