ObjectBox uses a code generator 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.

The setup.rb script does the following things to ensure the code generator is run transparently whenever you build your project:

1. ​Adds a build phase that runs the code generator to your project.​

2. ​Adds the generated source files to your project​

Adding the Sourcery Build Phase to Your Project

In your Xcode project, add a "New Run Script Phase" and make sure it comes above the Compile Sources phase of your project. The code generator needs to generate the code you want to compile first.

We call the Build Phase "[OBX] Update Sourcery Generated Files".

Enter the following script into this build phase:

"${PROJECT_DIR}/ObjectBox/generate_sources.sh"

The above example assumes you've extracted the files from the ObjectBox release on Github into a folder named ObjectBox next to your project. If you had a folder named external for all external dependencies next to a myproject folder that contains your project, that line might read:

"${PROJECT_DIR}/../external/generate_sources.sh"

You get the picture. In general, it is a good idea to use project-relative paths, so anyone checking out your project can run it, no matter where they keep their checkouts, or what their username.

Adding the Generated Files to Your Project

Build your project once, so it can create the generated/EntityInfo.generated.swift file for you. It will not contain much of interest, yet, but now that the generated/ directory and its contents exist, you can drag them into your Xcode project so they get compiled as well (make sure you add folders as "groups", not as "folder references").

You now have a working ObjectBox setup in your project and should be able to follow the rest of the instructions in our Getting Started section.

Passing options to the code generator

Although you should generally not need to, you can adjust the behaviour of ObjectBox's code generator by passing it additional arguments.

For example, if you have several different targets in your project that use different models, you can customize the names and paths for the model.json and EntityInfo.generated.swift files by changing the script build phase's line

"${PODS_ROOT}/ObjectBox/generate_sources.sh"

into one telling the script to forward the --output and --model-json arguments to the code generator:

"${PODS_ROOT}/ObjectBox/generate_sources.sh" -- --output "${PROJECT_DIR}/generated/EntityInfo-${TARGET_NAME}.generated.swift"
                                                --model-json "${PROJECT_DIR}/model-${TARGET_NAME}-iOS.json"

Note the extra two dashes, which help the script distinguish arguments to be forwarded from arguments directly to the script.

Or if you wanted to control the module name under which the generated source code should end up, you would do this by telling the script to forward that option to the code generator:

"${PODS_ROOT}/ObjectBox/generate_sources.sh" -- --xcode-module JennasModule

Where JennasModule would be the module name to use.

If you are writing a framework and want to export your entity classes from it, you will need to make the generated code public. You do this similarly, by adding the --visibility option:

"${PODS_ROOT}/ObjectBox/generate_sources.sh" -- --visibility public

If you wanted to pass both options, you would only need the double-dash once.

"${PODS_ROOT}/ObjectBox/generate_sources.sh" -- --xcode-module JennasModule --visibility public

It is not recommended to customize any other options, as they are subject to change, but should you need to do so, you can obtain a list by asking the code generator directly by typing the following into Terminal:

/path/to/ObjectBox/Sourcery.app/Contents/MacOS/Sourcery --help

Which will print syntax description for the code generator.

Note that some of the options described above may only be available in the newest version of the code generator.