ObjectBox Swift
objectbox.ioBlogTwitterGitHub
  • ObjectBox Swift Database Docs
  • Install ObjectBox Swift
  • Get 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
On this page
  • CocoaPods
  • Troubleshoot setup issues
  • Update to a new version
  • Swift Package
  • Set up an Xcode project
  • Set up a Swift Package Manager manifest
  • Carthage
  • Recommended Xcode project settings

Was this helpful?

Export as PDF

Install ObjectBox Swift

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.

PreviousObjectBox Swift Database DocsNextGet Started with ObjectBox Swift

Last updated 5 months ago

Was this helpful?

Having problems installing ObjectBox using this guide? Please, . Thanks for your help!

ObjectBox Swift is available as a:

  • pod

  • framework

Alternatively, a is possible.

CocoaPods

If you are new to CocoaPods, for an introduction and installation instructions.

To add the ObjectBox Swift dependency, add the following line to your Podfile:

pod 'ObjectBox'

Then install the pod and run the ObjectBox setup script:

pod install --repo-update
Pods/ObjectBox/setup.rb

The setup.rb script will configure your Xcode project to run ObjectBox generator on every build by adding a build phase (called [OBX] Update Sourcery Generated Files) for every target with an executable.

Disable the User Script Sandboxing option to run the ObjectBox generator in recent Xcode versions:

The ObjectBox code generator needs to run in the project directory and will generate files there. If this is executed in a sandbox, the build phase will fail.

Then, open your Xcode workspace (.xcworkspace) instead of the Xcode project (.xcodeproj).

Troubleshoot setup issues

If installing the pod or configuring the project failed, try to update the xcodeproj and cocoapods gem:

gem update xcodeproj && gem update cocoapods && pod repo update

On Apple Silicon (M1), ensure you have the latest gems for CocoaPods:

gem update ffi ethon

Update to a new version

After a new version of ObjectBox Swift is released, update the ObjectBox pod and run the setup script again:

pod repo update
pod update ObjectBox
Pods/ObjectBox/setup.rb

Swift Package

Instructions depend on whether you want to set up an Xcode project or a Swift Package Manager manifest.

Set up an Xcode project

https://github.com/objectbox/objectbox-swift-spm

Finally, when asked, add the ObjectBox.xcframework to your app target.

Set up a Swift Package Manager manifest

In your Swift.package file, add the ObjectBox Swift Package repository to the dependencies block:

.package(url: "https://github.com/objectbox/objectbox-swift-spm.git", from: "4.1.0-beta.1"),

Add the ObjectBox.xcframework to the dependencies of the desired target in targets:

.product(name: "ObjectBox.xcframework", package: "objectbox-swift-spm")

Your Swift.package file should then contain sections similar to this:

dependencies: [
    .package(url: "https://github.com/objectbox/objectbox-swift-spm.git", from: "<version>"),
],
targets: [
  .executableTarget(
    name: "YourApp",
    dependencies: [
        .product(name: "ObjectBox.xcframework", package: "objectbox-swift-spm")
    ],
]

Carthage

Carthage support is deprecated and this section is out of date.

  1. Add github "objectbox/objectbox-swift" to your Cartfile

  2. Run carthage update to download ObjectBox.

  3. Add either Carthage/Build/Mac/ObjectBox.framework or Carthage/Build/iOS/ObjectBox.framework to the appropriate targets of your project

  4. In the "General" build settings tab, locate the "ObjectBox.framework" and sure one of "Embed Without Signing" or "Embed & Sign" is selected.

  5. Run gem install xcodeproj and then run the ObjectBox setup script from Carthage/Build/Mac/OBXCodeGen.framework/setup.rb in your project directory.

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

github "objectbox/objectbox-swift"

Then open Terminal, cd into the folder containing your project and run

carthage update
gem install xcodeproj
Carthage/Build/Mac/OBXCodeGen.framework/setup.rb

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.

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.

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:

$(inherited) $(PROJECT_DIR)/Carthage/Build/iOS

For macOS targets:

$(inherited) $(PROJECT_DIR)/Carthage/Build/macOS

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:

carthage update
Carthage/Build/Mac/OBXCodeGen.framework/setup.rb

Recommended Xcode project settings

Disable Bitcode

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.

Now, you are all set to define your first ObjectBox entities! To continue check the or .

The Swift Package is currently in preview, we !

In Xcode, and search for the package URL:

For the Dependency Rule, we recommend to use "Up to Next Major Version" and version 4.1.0-beta.1. To find the latest version to use view the .

Now, you are all set to define your first ObjectBox entities. To continue check the or .

Now, you are all set to define your first ObjectBox entities! To continue check the or .

Note: Carthage may falsely report incompatible Swift 5.1.x versions. prevents the framework to be installed!

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! 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)."

You can now open your project's Xcode workspace as usual and .

Getting Started guide
the example project
welcome your feedback
add a package dependency
tags of the objectbox-swift-spm repository
Getting Started guide
the example project
Getting Started guide
the example project
This Carthage bug
Track this Carthage issue for updates.
follow the tutorial
let us know where we lost you
manual setup in Xcode
check out their website
CocoaPods
Swift Package
Carthage
Search for "sandbox" in your projects build settings and set User Script Sandboxing to No.