Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Building TouchDB

snej edited this page · 28 revisions

Not Building TouchDB

If you'd rather, you can download pre-built libraries. This is probably the best path unless you want to troubleshoot by stepping into TouchDB code, or want to make changes to TouchDB itself.

  • The easiest way to go, if you're starting a new iOS project, is to download Hello TouchDB, a complete buildable Xcode project folder already set up with TouchDB 1.0 and CouchCocoa. If you use this you can skip all the stuff about adding libraries and configuring targets, and just start coding.
  • Or, if you want to integrate TouchDB into an existing project: stable releases can be found on the Github Downloads page.
  • Or, if you're brave: our build-bot runs hourly, 24/7/365, and generates builds of the latest commits. These have not been QA'd at all: if it compiles and links, it goes up there. Caveat Emptor.

Once you've got the library, skip down to "Linking TouchDB Into Your Own App".

If you'd rather be l33t and build it yourself, read on...

Building The Framework

  1. Use Git to clone the TouchDB repository to your local disk. For example: "git clone 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.
  3. Open TouchDB.xcodeproj, and build the "Mac Framework" and/or "iOS Framework" schemes. (Or to build an optimized but less-debuggable version, use the Xcode "Archive" command instead of "Build".)
  4. You should now have a "TouchDB.framework" in your build output directory. (You can find this directory by looking at the last line of output of the build log in Xcode)

In the future you can update to the latest TouchDB by running "git pull" in the TouchDB directory, then building the project again.

Building The Demo Apps

The demo apps use the CouchCocoa framework, which you'll need to check out and build separately:

  1. Clone the CouchCocoa repository to your local disk.
  2. Run "git submodule init" and then "git submodule update".
  3. Open CouchCocoa.xcodeproj and build the appropriate scheme ("Mac Framework" and/or "iOS Framework").
  4. Copy or symlink the built "CouchCocoa.framework" into the "Frameworks" subdirectory of the appropriate TouchDB demo subdirectory.
    1. TouchDB-iOS/Demo-iOS/Frameworks/
    2. TouchDB-iOS/Demo-Mac/Frameworks/
  5. In TouchDB.xcodeproj, select and build the "Mac Demo" or "iOS Demo" scheme.

Note: Until recently (5/2012) TouchDB used a different branch of CouchCocoa, naturally called touchdb. This has been merged into the default master branch, so if you have an existing CouchCocoa clone, make sure you've checked out master.

Linking TouchDB Into Your Own App

  1. Drag TouchDB.framework into the file list of your app's project window.
    1. An alternate trick, if you want to always use the latest self-built version of TouchDB.framework, is to symbolic-link (symlink) it.
      1. Either, into your project folder directly:
        $ cd ~/dev/myProject/
        $ ln -s ~/dev/TouchDB-iOS/DerivedData/TouchDB/Build/Products/Debug-ios-universal/TouchDB.framework TouchDB.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/TouchDB-iOS/DerivedData/TouchDB/Build/Products/Debug-ios-universal/TouchDB.framework TouchDB.framework
      3. Then do the drag & drop of the TouchDB.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.
  2. In the window that appears, make sure the checkbox next to your app's target is checked.
  3. Repeat the above with CouchCocoa.framework
  4. For an iOS target:
    1. Go to the "Build Settings" tab of your app target's settings.
    2. Find the "Other Linker Flags" row in the "Linker" section, and add the flag -ObjC. (Note the capitalization.)
    3. Go to the "Build Phases" tab of the app target's settings.
    4. In the "Link Binary with Libraries" section, click the plus button and add CFNetwork.framework, Security.framework, SystemConfiguration.framework, libsqlite3.dylib and libz.dylib.
  5. For a Mac OS target, you'll need to make sure the framework is copied into your app's bundle:
    1. To to the "Build Settings" tab of your app target's settings.
    2. In the "Linker" section, edit "Runpath Search Paths" and add the path "@loader_path/../Frameworks".
    3. Now switch to to the "Build Phases" tab.
    4. Press the "Add Build Phase" button at the bottom of the window and create a new "Copy Files" phase.
    5. Set the phase's destination to "Frameworks".
    6. Press the "+" button below the phases' file list and select TouchDB.framework and CouchCocoa.framework to add them.

Next: Using TouchDB

Something went wrong with that request. Please try again.