ObjectBox Swift
objectbox.ioBlogTwitterGitHub
Search…
ObjectBox Swift Database Docs
Installing ObjectBox
Getting started with ObjectBox Swift
Entity Annotations in ObjectBox
Queries
Relations
Transactions
ObjectBox Swift FAQ
Swift API Docs
Advanced
The Sandbox on macOS
Enums and Custom Types
Data Model Updates
Meta Model, IDs and UIDs
Manual Installation
The setup.rb Script
Customizing Code Generation
Data Sync
Android Database
Flutter Database
Powered By GitBook
Installing ObjectBox
ObjectBox is a NoSQL Swift database uniquely optimized for high-performance on smartphones. Learn how to set up ObjectBox Swift and persist objects in your iOS or macOS application.
Having problems installing ObjectBox using this guide? Please, let us know where we lost you. Thanks for your help!

Adding ObjectBox DB to your project

We recommend to setup ObjectBox using CocoaPods. We also offer prelimitary Swift Package Manager support, Carthage (experimental) or a manual setup in Xcode. Here's a quick setup (more details are below the tabs):
CocoaPods
Swift Package Manager (experimental)
Carthage (experimental / semi-deprecated)
On Apple Silicon (M1), ensure you have the latest gems for cocoapods:
1
gem update ffi ethon
Copied!
  1. 1.
    Add pod 'ObjectBox' to the Podfile in your Xcode project directory.
  2. 2.
    Run these two commands in Terminal: pod install --repo-update
    Pods/ObjectBox/setup.rb
  3. 3.
    Open your .xcworkspace in Xcode.
Due to technical limitations of SPM, we can only offer iOS support at this moment. We hope that the next major SPM version will also enable us to support macOS.
Two steps are required; the first is the standard SPM dependency. In your Package.swift manifest file, add this to your dependencies section:
1
.package(
2
url: "https://github.com/objectbox/objectbox-swift",
3
.exact("1.6.0")
4
)
Copied!
Alternatively, you may use the Xcode UI to add a package dependency.
The second step is to install the ObjectBox generator. The installation process requires Ruby and and the xcodeproj Ruby gem as a prerequisite. Locate the contents of ObjectBox package and run the contained setup script:
1
gem install xcodeproj # Ruby prerequisite
2
./setup.rb # from inside the ObjectBox package
Copied!
Note: a future version of SPM may allow us to get rid of that second step by providing a plugin mechanism.
Carthage support is experimental and only recommended for experienced users. Note: Carthage may falsely report incompatible Swift 5.1.x versions. This Carthage bug prevents the framework to be installed!
  1. 1.
    Add github "objectbox/objectbox-swift" to your Cartfile
  2. 2.
    Run carthage update to download ObjectBox.
  3. 3.
    Add either Carthage/Build/Mac/ObjectBox.framework or Carthage/Build/iOS/ObjectBox.framework to the appropriate targets of your project
  4. 4.
    In the "General" build settings tab, locate the "ObjectBox.framework" and sure one of "Embed Without Signing" or "Embed & Sign" is selected.
  5. 5.
    Run gem install xcodeproj and then run the ObjectBox setup script from Carthage/Build/Mac/OBXCodeGen.framework/setup.rb in your project directory.

Project settings

Some versions of ObjectBox do not include bitcode and thus you may need to adjust "Build Settings" in Xcode accordingly. In that tab, ensure "All" is active and search for "bitcode". You will find the "Enable Bitcode" setting which you set to "No".
Otherwise, for some build targets, you will get a build error like this: '.../ObjectBox.framework/ObjectBox' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target.
Still using Swift 5.0? ObjectBox 1.1 supports Swift 5.1+. If you want to give ObjectBox a try but are stuck with Swift 5.0, use the ObjectBox501 pod. We recommend Swift 5.1 though.

Detailed Instructions

CocoaPods

If you don't have CocoaPods already, install it by typing sudo gem install cocoapods in Terminal. If you don't have a Podfile yet, cd into your Xcode project folder and create one using pod init as usual. Now find the # Pods for MyTargetName comment for each target and add the following below it:
1
pod 'ObjectBox'
Copied!
Then run:
1
pod repo update
2
pod install
3
Pods/ObjectBox/setup.rb
Copied!
The first call will ensure your local copy of the list of available CocoaPods is current, the second call is your usual procedure when adding a new pod to your Podfile that will download the newest release of ObjectBox to your Pods directory and install the pod in your Xcode workspace.
Once you have ObjectBox downloaded, setup.rb will set up the ObjectBox preprocessor in your project for every target with an executable.
You can now open your project's Xcode workspace as usual and follow the rest of this tutorial.

Troubleshooting

Something doesn't work yet (e.g. pod install fails)? Try updating CocoaPods related things using:
1
gem update xcodeproj && gem update cocoapods && pod repo update
Copied!

Updating

After a new ObjectBox version is released, you need to get the new pod and run the setup script again:
1
pod repo update
2
pod update ObjectBox
3
Pods/ObjectBox/setup.rb
Copied!

Carthage

If you don't have Carthage yet, install it e.g. using Homebrew brew install carthage. If you do not have a Cartfile yet, create a text file named just Cartfile (no .txt suffix) in your project's folder and write the following text into it
1
github "objectbox/objectbox-swift"
Copied!
Then open Terminal, cd into the folder containing your project and run
1
carthage update
2
gem install xcodeproj
3
Carthage/Build/Mac/OBXCodeGen.framework/setup.rb
Copied!
The first call is the typical way to make Carthage download a dependency specified in your Cartfile. Once you have ObjectBox downloaded, setup.rb will set up the ObjectBox preprocessor in your project for every target with an executable. The gem install xcodeproj line installs a helper tool needed by the setup script.
Carthage has a bug preventing the Swift pre-built framework from working. It falsely reports that Swift 5.1.x versions are incompatible. This will cause the setup to fail! Track this Carthage issue for updates. The error looks like this: Skipped installing objectbox-swift.framework binary due to the error: "Incompatible Swift version - framework was built with 5.1.2 (swiftlang-1100.0.278 clang-1100.0.33.9) and the local version is 5.1 (swiftlang-1100.0.270.13 clang-1100.0.33.7)."
Like for all Carthage projects, you now need to open your project in Xcode and add the framework to your target. You do this by dragging either the Carthage/Build/iOS/ObjectBox.framework or Carthage/Build/Mac/ObjectBox.framework (depending on whether your project is for iOS or macOS) to the "Frameworks, Libraries and Embedded Content" list of the "General" tab of your target's settings. Make sure you choose "Embed and Sign" to its right.
You can now open your project's Xcode workspace as usual and follow the tutorial.
Ignore the OBXCodeGen.framework that you'll also see in Carthage/Build. It is not intended to be linked into your application and only exists to hold the code generator and setup script so you have them while you build.

Secondary targets, e.g. unit tests

If your unit test target does not find the ObjectBox library, please verify that the "Framework Search Paths" build settings of that secondary target are set up. Check the screenshot how to find the setting, and compare the value to the one from your main target. To fix it, press enter and ensure that the following values are present.
For iOS targets:
1
$(inherited) $(PROJECT_DIR)/Carthage/Build/iOS
Copied!
For macOS targets:
1
$(inherited) $(PROJECT_DIR)/Carthage/Build/macOS
Copied!
Otherwise, you may get errors like this: ld: warning: Could not find or use auto-linked framework 'ObjectBox' Undefined symbols for architecture x86_64: "type metadata accessor for ObjectBox.ToManyProperty" ...

Updating

After a new ObjectBox version is released, you need to update via Carthage and run the setup script again:
1
carthage update
2
Carthage/Build/Mac/OBXCodeGen.framework/setup.rb
Copied!
Previous
ObjectBox Swift Database Docs
Next
Getting started with ObjectBox Swift
Last modified 7mo ago
Export as PDF
Copy link
Contents
Adding ObjectBox DB to your project
Project settings
Detailed Instructions
CocoaPods
Carthage