C driver for Oracle NoSQL Database build instructions

The Oracle NoSQL Database C driver provides C applications access the Oracle NoSQL Database using a Thrift based proxy server. C driver is supplied as source code and must be built for target platforms. The proxy server is included in this download package as a Java JAR file.

This document describes how to build the C driver library. For information on using the C driver with your application code, see the Quick Start Guide and the C API Reference.

  1. Prerequisites for building the driver
  2. Prerequisites for running and testing
  3. Build the driver library
  4. Test
  5. Run examples
  6. Install the driver library
  7. Build and run applications

Prerequisites for building the C driver

Several of the following dependencies require compilation as they are not available as binary distributions.

  1. CMake

    Precompiled, ready-to-install binaries are available for various Linux distributions:


  2. Thrift v0.9.2 for C++

    Download source from:


    To build and install the Thrift library, see http://thrift.apache.org/docs/BuildingFromSource. The prerequisites are:

    About the detailed information of Thrift requirements, see http://thrift.apache.org/docs/install/

Prerequisites for running and testing C applications

  1. Path to NoSQL Database and proxy jar files.

  2. Java runtime (Java 7 or later; Oracle NoSQL Database is certified against Java 7).

  3. Thrift C++ library installation.


  1. Create a build directory. All build and CMake artifacts reside here for easy cleanup. The build directory can be anywhere as long as CMake is told where the C library source is located.

    $ mkdir build
    $ cd build

  2. Run CMake, making sure to identify the top-level C driver source directory. For example, if your C driver package is located at:


    then at a minimum your CMake command call is:

    cmake /home/me/kv-c-driver-3.3.4/c

    The following command line options may also be useful to you:

    If KV_BUILD_TYPE is static, then building a binary installation package is enabled. You can use the command line options list below to configure the install package. If KV_PACKAGE_PROXY_LIB is set, then two packages are built -- the C driver and the Proxy packages -- otherwise, only the C driver package is built.

  3. Once CMake has succeeded, build the driver library:

    $ make

    If there is a problem, additional information, such as the specific compiler flags being used, can be obtained this way:

    $ VERBOSE=1 make

    The destination for the build artifacts is build/build/{bin,lib,include}. The libraries required by the driver are lib/libkvstore* and the prerequisite library libthrift*. The destination for the test suite and example binaries is the bin directory, they are not required for deployment.

  4. Build binary install package:

    $ make package

    Alternatively, you can build package use below command:

    $ cpack -G <package type>

    Supported package type are RPM, DEB and TGZ. For Debian based distributions, the package type can be DEB or TGZ. For RPM based distributions, the package type can be RPM or TGZ, the rpmbuild tool is required to build RPM package.


Tests can be run one of two ways. If the -DKV_PATH_TO_JAR and -DKVPROXY_PATH_TO_JAR command line options were provided to CMake, then you can run the tests from make:

$ make test

The output of make test ends up in the file Testing/Temporary/LastTest.log. It can be examined for detailed success and failure information.

NOTE: "make test" may hang. If it does, invoke the tests directly.

The second way to run the tests is to invoke them directly using the kvsuite utility:

$ build/bin/kvsuite -r <path-to-kvroot> -k <path-to-kvstore.jar> -d <path-to-kvproxy-jar> -v


Run the examples

The examples are automatically built when the driver library is built. To run them, you must have a running Oracle NoSQL Database store.

The simplest way to create a store is to use the KVLite utility, which creates a single-node deployment. To use KVLite on the local machine you need access to kvstore.jar and its accompanying jar files.

The following command deploys an Oracle NoSQL Database store named "examples" on the local machine. Because it uses "localhost" as a hostname, the store is only accessible locally. If you want a remotely accessible store, use a valid hostname.

$ mkdir kvroot
$ nohup java -jar <path-to-kvstore.jar> kvlite -root kvroot -store examples -host localhost -port 5000 -admin 5001

"nohup" will run the command in background, and is optional.

To run the "hello" example against this store, from the build directory:

$ build/bin/hello -store examples -host localhost -port 5010 -helper-hosts localhost:5000 \
-kvproxy kv-c-driver-3.3.4/kvproxy/lib/kvproxy.jar \
-kvclient kv-c-driver-3.3.4/kvproxy/lib/kvclient.jar

The program takes a few seconds to start the proxy and before running the example applications. Output is sent to stdout.

Install the driver library

Once the driver build is verified, it can be installed to the location specified in the CMake arguments. By default, /usr/local is used.

$ make install

If additional permissions are required for the installation directory you may need to use:

$ sudo make install

Build and run your application

  1. Using the shared library

    To build, the compilation line must reference the include directory in the driver distribution and link with the dependent libraries, which include:

    To see an example of accurate compilation lines, look at the compile line for the example code. In the build directory you can rebuild everything by doing this:

    $ make clean

    $ VERBOSE=1 make

    The VERBOSE=1 will cause the build to show compilation lines.

    Here is an example compilation line (modify to suit your local installation.) In this case, libkvstore* and libthrift* are all installed in /usr/local/lib (the default).

    gcc -o myprog myprog.c -lkvstore -Wl,-rpath,/usr/local/lib

    If your libraries are installed in a non-standard location then to run your application remember to include their location in your LD_LIBRARY_PATH environment variable.

  2. Using the static library

    To build, the compilation line must reference the include directory in the driver distribution and link with libkvstore-static.a.

    There is C++ code in libkvstore-static.a, so you may have to use g++ as the linker.

    Here is an example compilation line (modify to suit your local installation.) In this case, libkvstore-static.a is installed in /usr/local/lib (the default).

    gcc -o myprog.c.o -c myprog.c
    g++ myprog.c.o -o myprog -lkvstore-static -lpthread

    If libkvstore-static.a is installed in a non-standard location then to build your application remember to use -L<path-to-installation> to specify the search directory.