How to build the C driver for Oracle NoSQL Database.

The Oracle NoSQL Database C driver lets applications written in C access the Oracle NoSQL Database via a Thrift based proxy server. This driver is supplied as source code and must be built for target platforms.

Prerequisites for building the C driver

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

  1. Install CMake.

  2. Install GLIB 2.0. This is required for Thrift.

  3. Build and install the Thrift library

  4. Build and install the Jansson library

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. GLIB library installation.

  4. Thrift c_glib library installation.

  5. Jansson library installation.

To build and run

  1. Create a build directory. All build and CMake artifacts reside here for easy cleanup. The build directory can be anywhere as long as the cmake command is:

    cmake <path-to-top-level-directory>

    This keeps the source tree clean of build artifacts.

    $mkdir build
    $cd build

  2. Generate makefiles(from build).

    Once cmake has succeeded, build. Tests can be run by directly invoking kvsuite, or by invoking make if KV_PATH_TO_JAR and KVPROXY_PATH_TO_JAR were specified for cmake.

    $ cmake <path-to-top-level-directory> [options]

    e.g. from the build directory you just made:

    cmake .. [options]

    These options are available on the cmake command line:

  3. Once cmake has succeeded, build.

    $ 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 libraries wherever that was built including libjansson*, libthrift_c_glib*, libglib*, libgobject*. The destination for the test suite and example binaries is the bin directory; they are not required for deployment.

  4. Tests can be run either by directly invoking kvsuite, or by invoking make if KV_PATH_TO_JAR and KVPROXY_PATH_TO_JAR were specified for cmake.

    $ 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, use direct test invocation as outlined below.

    To invoke tests directly:

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

    Note the following:

  5. Build and run the examples.

    The examples are built by the make process and can be executed directly. The examples require a running Oracle NoSQL DB 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 instance of Oracle NoSQL DB 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 c/build directory:

    $ build/bin/hello -store examples -host localhost -port 5000 \
    -proxy-host localhost -proxy-port 5010 \
    -kvproxy <path-to-install>/kvproxy/lib/kvproxy.jar \
    -kvclient <path-to-kvclient.jar>

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

  6. Once the driver build is verified, it can be installed to the location specified in the cmake arguments.

    $ make install

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

    $ sudo make install

  7. Build and run your application.

    To build, the compilation line must reference the include directory in this distribution (included) and link with the dependent libraries, which include:

    A good way to see an example of accurate compilation lines is to look at those 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 a sample compilation line, which will obviously need to be modified based on your installation paths. In this case, libkvstore, Thrift, Jansson, and glib are all installed in /usr/local/lib (the default). This is on a Linux system:

    gcc -o myprog myprog.c -lkvstore -lglib-2.0 -lgobject-2.0 -ljansson -Wl,-rpath,/usr/local/lib

To build the API documentation

The C API HTML documents can be generated using the doxygen tool with the the configuration file "doxyfile.txt". The output directory is "doc", in the current directory. You will need doxygen installed on your system to do this.

$ doxygen <path-to-top-level-directory>/doxyfile.txt