Guide:Adding Couchbase Lite To Your App

TABLE OF CONTENTS

3. Adding Couchbase Lite To Your App

Assuming you're ready to start using Couchbase Lite, here's how to get started.

iOS or Mac OS

Adding the frameworks

1. Obtain the CouchbaseLite.framework:
2. Download the latest release.
3. Move the downloaded Couchbase Lite folder wherever you'd like to keep it.
4. Open the subfolder for your platform — iOS or Mac OS.
5. Drag CouchbaseLite.framework from that subfolder into the file list of your app's project window. (I recommend adding it to the "Frameworks" group, but it's not necessary.)
6. In the window that appears, make sure the checkbox next to your app's target is checked.
7. For an iOS target:
8. Go to the "Build Settings" tab of your app target's settings.
9. Find the "Other Linker Flags" row in the "Linker" section, and add the flag -ObjC. (Note the capitalization.)
10. Go to the "Build Phases" tab of the app target's settings.
11. In the "Link Binary with Libraries" section, click the plus button and add CFNetwork.framework, Security.framework, SystemConfiguration.framework, libsqlite3.dylib and libz.dylib.
12. Or for a Mac OS target, you'll need to make sure the framework is copied into your app's bundle:
13. To to the "Build Settings" tab of your app target's settings.
14. In the "Linker" section, edit "Runpath Search Paths" and add the path "@loader_path/../Frameworks".
15. Now switch to to the "Build Phases" tab.
16. Press the "Add Build Phase" button at the bottom of the window and create a new "Copy Files" phase.
17. Set the phase's destination to "Frameworks".
18. Press the "+" button below the phases' file list and choose CouchbaseLite.framework from the list that pops up.
19. Build your app to make sure there are no errors.

(For more details, and for a description of how to check out and build Couchbase Lite from source, consult the wiki page.)

Initializing Couchbase Lite in your app

Now you're ready to write code. The first step is to initialize Couchbase Lite, probably in your application delegate's applicationDidFinishLaunching method. First add the necessary import directive:

#import <CouchCocoa/CouchCocoa.h>

Then add the following to the applicationDidFinishLaunching method:

CBLManagerServer* server = [CBLManagerServer sharedInstance];
if (server.error) [self failed: server.error];
self.database = [server databaseNamed: @"my-database"];  // db name must be lowercase!
NSError* error;
if (![self.database ensureCreated: &error]) [self failed: error];

• The call to [self failed:] is a placeholder for your actual error handling/reporting code -- if Couchbase Lite is crucial to your app, you may have no option but to put up a fatal-error alert and then exit.
• This code creates a database named my-database. The name's not very important, but you'll probably want to personalize it anyway. Be aware that Couchbase Lite does not allow uppercase letters in database names: legal characters are lowercase letters, digits, and any of _$()+-/.
• The CBLDatabase object representing the database is stored into a database property of the app delegate. You'll need to declare and synthesize this property in the usual way.

Android

(TBD)

NEXT: Working With Documents