Home

Awesome

Couchbase Lite For C

This is a cross-platform version of the Couchbase Lite embedded NoSQL syncable database, with a plain C API. The API can be used directly, or as the substrate for binding to other languages like Python, JavaScript or Rust.

Goals

Examples

C

// Open a database:
CBLError error;
CBLDatabaseConfiguration config = {FLSTR("/tmp")};
CBLDatabase* db = CBLDatabase_Open(FLSTR("my_db"), &config, &error);

// Create a document:
CBLDocument* doc = CBLDocument_CreateWithID(FLSTR("foo"));
FLMutableDict props = CBLDocument_MutableProperties(doc);
FLSlot_SetString(FLMutableDict_Set(props, FLStr("greeting")), FLStr("Howdy!"));

// Save the document:
CBLDatabase_SaveDocument(db, doc, &error);
CBLDocument_Release(doc);

// Read it back:
const CBLDocument *readDoc = CBLDatabase_GetDocument(db, FLSTR("foo"), &error);
FLDict readProps = CBLDocument_Properties(readDoc);
FLSlice greeting = FLValue_AsString( FLDict_Get(readProps, FLStr("greeting")) );
CBLDocument_Release(readDoc);

C++

NOTE: The C++ API is a volatile API which means that the API is not finalized, and may change in future releases.

// Open a database:
cbl::Database db(kDatabaseName, {"/tmp"});

// Create a document:
cbl::MutableDocument doc("foo");
doc["greeting"] = "Howdy!";
db.saveDocument(doc);

// Read it back:
cbl::Document readDoc = db.getMutableDocument("foo");
fleece::Dict readProps = readDoc.properties();
fleece::slice greeting = readProps["greeting"].asString();

Documentation

Building It

Source Code

This project contains submodules in multiple levels. Please make sure all submodules are checked out before building the project.

git clone https://github.com/couchbase/couchbase-lite-C.git
cd couchbase-lite-C
git submodule update --init --recursive

Unix (Linux / macOS)

Dependencies:

Steps:

  1. Prepare and build project with CMake.

    # At the project directory, create a build directory:
mkdir build && cd build

# Prepare project. Specify CMAKE_INSTALL_PREFIX for the installation directory when running `make install`.
# Add -DSTRIP_SYMBOLS=ON to generate a separate debug symbol file and strip private symbols from the built shared library.
cmake -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_INSTALL_PREFIX=`pwd`/output ..

# Build:
make

  2. Install the built library and headers to the location specified by CMAKE_INSTALL_PREFIX

    make install

    The installation will contain header files in the include folder and a shared library file in the lib folder.

Linux (Cross Compile)

NOTE: Due to the complexity of cross compiling, these instructions are very high level on purpose. If you are curious about more fine-grained details you can check out the cross compilation script we use.

Dependencies:

Steps:

The steps are similar to the steps for building the regular linux library above. The difference is that you will also need to prepare the CMake toolchain file that sets up the cross compiler and sysroot for the cross compilation.

When running the cmake to prepare the build project, add CMAKE_TOOLCHAIN_FILE option to specify the CMake toolchain file:

cmake -DCMAKE_TOOLCHAIN_FILE=<YOUR/toolchain.cmake> -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_INSTALL_PREFIX=`pwd`/output ..

Windows

Dependencies:

Steps:

  1. Prepare project with CMake.

    # Using powershell, at the project directory, create a build directory:
md build
cd build

# Prepare project. Specify CMAKE_INSTALL_PREFIX for the installation directory:
cmake -G "Visual Studio 15 2017" -A x64 -DCMAKE_INSTALL_PREFIX="$pwd/output" ..

  2. Build and Install

    cmake --build . --config MinSizeRel --target install

    The installation will contain header files in the include folder, a dll file in the bin folder and a lib file in the lib folder.

Xcode on macOS

:warning: Do not use Xcode 13 because of a downstream issue :warning:

  1. Open the Xcode project CBL_C.xcodeproj
  2. Select scheme CBL_C Framework
  3. Build

The result is CouchbaseLite.framework in your Xcode Build Products/Debug directory (the path depends on your Xcode settings.)

Testing It

CMake on Unix

  1. Follow the steps in building
  2. Build the test project make CBL_C_Tests
  3. Run the tests in test directory ./CBL_C_Tests -r list (for cross compile, this step needs to be done on the target system)

CMake on Windows

  1. Follow the steps in building
  2. Build the test project cmake --build . --target CBL_C_Tests
  3. Run the tests in test\Debug directory .\CBL_C_Tests.exe -r list

With Xcode on macOS

  1. Open the Xcode project from the Building section
  2. Select scheme CBL_Tests
  3. Run

Using It

Generic instructions

With Xcode on macOS

Other Language Bindings

All of these (even C++) have no official support by Couchbase.

If you've created a language binding, please let us know by filing an issue, or a PR that updates the list below.