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.
Several of the following dependencies require compilation as they are not available as binary distributions.
CMake
Precompiled, ready-to-install binaries are available for various Linux distributions:
Thrift v0.9.2 for C++
Download source from:
http://thrift.apache.org/download
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/
Path to NoSQL Database and proxy jar files.
kvclient.jar and kvproxy.jar are needed by client applications.
kvstore.jar is used only for the test suite.
Java runtime (Java 7 or later; Oracle NoSQL Database is certified against Java 7).
Thrift C++ library installation.
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
Run CMake, making sure to identify the top-level C driver source directory. For example, if your C driver package is located at:
/home/me/kv-c-driver-3.3.4
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:
-DCMAKE_BUILD_TYPE=<build type>
Allowed values are Debug, Release, RelWithDebInfo and MinSizeRel. Default is RelWithDebInfo.
-DCMAKE_INSTALL_PREFIX=<path>
Location where you want the built library installed. Default is /usr/local
-DKV_PATH_TO_JAR=<path>
Complete path to where your kvstore.jar file is located. This is required for the library's tests to run.
-DKVPROXY_PATH_TO_JAR=<path>
Complete path to where your kvproxy.jar file is located. This is required for the library's tests to run.
-DKV_TEST_ROOT_DIR=<path>
Used as the root directory for the library's tests. Defaults to build/test/kvstore.
-DKV_BUILD_TYPE=<build type>
Allowed values are shared and static. Use static if building a single static library into which the Thrift C++ lib is linked. Default is shared.
-DTHRIFT_PREFIX_DIR=<path>
Path to where your Thrift library is located. Only required if you installed Thrift to a non-standard location.
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.
-DCPACK_PACKAGE_VERSION=<version>
The version of package.
-DCPACK_PACKAGE_RELEASE=<number>
The release number of package. Default is 0.
-DCPACK_PACKAGING_INSTALL_PREFIX=<install prefix>
The install prefix used in the built package. Default is CMAKE_INSTALL_PREFIX.
-DKV_PACKAGE_PROXY_LIB=<path-to-proxy-lib>
The path to the directory containing the proxy jar file and its dependencies, all these file are packaged into the proxy install package.
-DKV_PACKAGE_COMPONENTS_BASED=<true|false>
There are 2 components included in package: C driver binaries and proxy related jar files. If this option is true, then the component-based packages will be built, otherwise, a single package includes all the C driver binaries and proxy related jar files will be built. Default is false.
-DKV_PACKAGE_GENERATE_TGZ=<true|false>
It is used to build TGZ package. Default is false.
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.
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
Note:
The path to kvroot must contain "kvstore" in it, or it will not work. That is, use something like /tmp/kvstore or /tmp/kvstore/ctest.
Note that the test will only create the final directory in the kvroot path. In the example above, "/tmp" or "/tmp/kvstore" must exist before running the test.
Make sure there are no other stores running on the current node that might collide with respect to the registry port.
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.
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
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.
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.