Building Couchbase Lite

Building The Framework

Checking Out The Code

1. Use Git to clone the Couchbase Lite repository to your local disk. For example: "git clone git://github.com/couchbase/couchbase-lite-ios.git"
2. In that directory run "git submodule init" and then "git submodule update". This will clone some external Git repositories into the vendor/ subdirectory.

In the future, you can update to the latest sources by running "git pull" in the Couchbase Lite directory, then git submodule update.

Building

3. Open CouchbaseLite.xcodeproj.
4. Select the "CBL iOS" or "CBL Mac" scheme.
5. The next step depends on whether you want an optimized or a debug build:
   • For an optimized build, choose "Archive" from the "Product" menu. Then use the Organizer window's Archives tab to find the archive and the CouchbaseLite.framework it contains.
   • For a debug build, choose the "Build" command instead. Finding the framework can be tricky as it's buried deep in the build directory, whose location varies depending on your Xcode preferences. Look at the build log in the log navigator pane and the last line of output should include its path.

64-Bit iOS

The regular iOS build does not include a 64-bit ARM binary, because we couldn't figure out a way to add that while retaining Xcode 4 compatibility in the project. So until we drop Xcode 4, you have to build a separate 64-bit framework for your 64-bit iOS apps.

1. Open the project and select the "CBL iOS" scheme, as above.
2. Choose "Edit Scheme" from the scheme pop-up.
3. Choose "Archive" from the list on the left of the scheme sheet.
4. Change the "Build Configuration" pop-up from "Release" to "Release 64bit".
5. Press "OK".
6. Choose "Archive" from the "Product" menu.

Note: The configuration change you make in step 4 is persistent, so if you want to build a 32-bit framework later on you'll have to follow similar steps to change the configuration back to "Release".

Building The Demo Apps

The "Grocery Sync iOS Demo" and "CBL Mac Demo" targets build some simple demo apps.

Linking Couchbase Lite Into Your Own App

1. Drag CouchbaseLite.framework into the file list of your app's project window.
2. An alternate trick, if you want to always use the latest self-built version of CouchbaseLite.framework, is to symbolic-link (symlink) it. 1. Either, into your project folder directly:
   $ cd ~/dev/myProject/
$ ln -s ~/dev/couchbase-lite-ios/DerivedData/CouchbaseLite/Build/Products/Debug-ios-universal/CouchbaseLite.framework CouchbaseLite.framework 2. Or, into your project's Framework folder if it has a real mapping to the Frameworks group inside Xcode:
   $ cd ~/dev/myProject/Frameworks
$ ln -s ~/dev/couchbase-lite-ios/DerivedData/CouchbaseLite/Build/Products/Debug-ios-universal/CouchbaseLite.framework CouchbaseLite.framework 3. Then do the drag & drop of the CouchbaseLite.framework symlink from the Finder window into your Xcode project window's Framework group and follow rest of the instructions below as usual. The Copy items into destination group's folder (if needed) and Create groups for any added folders can/should stay selected and it will work properly. NO it will NOT follow the reference of the symlink to make a copy ... that won't happen, so relax.
3. In the window that appears, make sure the checkbox next to your app's target is checked.
4. For an iOS target:
5. Go to the "Build Settings" tab of your app target's settings.
6. Find the "Other Linker Flags" row in the "Linker" section, and add the flag -ObjC. (Note the capitalization.)
7. Go to the "Build Phases" tab of the app target's settings.
8. In the "Link Binary with Libraries" section, click the plus button and add CFNetwork.framework, Security.framework, SystemConfiguration.framework, libsqlite3.dylib and libz.dylib.
9. For a Mac OS target, you'll need to make sure the framework is copied into your app's bundle:
10. To to the "Build Settings" tab of your app target's settings.
11. In the "Linker" section, edit "Runpath Search Paths" and add the path "@loader_path/../Frameworks".
12. Now switch to to the "Build Phases" tab.
13. Press the "Add Build Phase" button at the bottom of the window and create a new "Copy Files" phase.
14. Set the phase's destination to "Frameworks".
15. Press the "+" button below the phases' file list and select CouchbaseLite.framework to add it.

Next: Using Couchbase Lite