CouchCocoa is a medium-level Objective-C API for working with CouchDB on iOS and Mac OS. By "medium-level" we mean:
- It doesn't require knowledge of the HTTP API, only of CouchDB's architecture. You won't have to remember special paths or URL query parameters.
- But it doesn't provide a full-fledged model layer like CoreData or ActiveRecord. You're still working with CouchDB documents as, basically, NSDictionaries, and you'll need your own mapping between those and your app's object model.
This API is not the only way to access CouchDB on iOS and Mac OS. There are other Objective-C APIs available, such as Trundle, or you can go down to the metal and talk to the HTTP API yourself using NSURLConnection.
- You can discuss this API or ask questions at the Couchbase Mobile Google Group.
- You might also want to look at the issue tracker to see known problems and feature requests.
Xcode 4.1 or later, with the SDK for iOS 4 or later. (It's possible the project might still work with Xcode 3, but we're not testing or supporting this.)
If you cloned the CouchCocoa Git repository, aso opposed to downloading a precompiled framework, then you'll next need to initialize Git "submodules". This will clone the dependency JSONKit into the "vendor" subfolder:
cd CouchCocoa
git submodule init
git submodule update
There are two simple Mac demo apps included in the Demo/ subfolder. One lets you edit a simple list of names and email addresses, the other is a shopping list. (They actually share most of the same source code; all the differences are in their model classes and .xib files, thanks to the magic of Cocoa bindings.) To run them:
- Start a CouchDB server (such as Couchbase Server) on localhost.
- Open CouchDemo.xcodeproj (in Xcode 4.0.2 or later)
- Select "Demo-Addresses" or "Demo-Shopping" from the scheme pop-up in the toolbar
- Press the Run button
(You only need to do this if you checked out the CouchCocoa source code and want to build it yourself. If you downloaded a precompiled framework, just go onto the next section.)
- Open CouchDemo.xcodeproj
- Select "Mac Framework" or "iOS Framework" from the scheme pop-up in the toolbar
- Product > Build
If you want to run the unit tests, first make sure a CouchDB server is running on localhost, then choose Product > Test.
The framework will be located at:
- Mac: build/CouchCocoa/Build/Products/Debug/CouchCocoa.framework
- iOS: build/CouchCocoa/Build/Products/Debug-universal/CouchCocoa.framework
- Build the Mac framework (see above).
- Copy CouchCocoa.framework somewhere, either into your project's folder or into a location shared between all your projects.
- Open your Xcode project.
- Drag the copied framework into the project window's file list.
- Add the framework to your target (if you weren't already prompted to in the previous step.)
- Edit your target and add a new Copy Files build phase.
- Set the build phase's destination to Frameworks, and drag CouchCocoa.framework into its list from the main project file list.
- Build the iOS framework (see above).
- Copy CouchCocoa.framework somewhere, either into your project's folder or into a location shared between all your projects.
- Open your Xcode project.
- Drag the copied framework into the project window's file list.
- Add the framework to your target (if you weren't already prompted to in the previous step.)
You'll probably want to run a local database server on your iOS device, since it'll allow your app to work offline (and improves performance.) CouchCocoa.framework doesn't contain CouchDB itself, so you should also add the Couchbase Mobile framework to your app. Using the two together is very simple: when the CouchbaseMobile object calls your delegate method to tell you the server's up and running, just use the URL it gives you to instantiate a CouchServer object.
Released under the Apache license, version 2.0.
Contributors: Jens Alfke, J Chris Anderson, David Venable, Alex McArthur, Jonathon Mah, Pierre Metrailler, Sven A. Schmidt, Katrin Apel.
Copyright 2011, Couchbase, Inc.