Building Oracle NoSQL Database C Driver for Tables

Before You Begin

This 15-minute tutorial shows you how to build Oracle NoSQL Database C Driver for Tables.

Background

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.

What Do You Need?

CMake - Precompiled, ready-to-install binaries are available for various Linux distributions from here.
Thrift v0.9.3 for C++ - Download source from here. To build and install the Thrift library, see here. About the detailed information of Thrift requirements, see here.

Please note that if you want to build the C driver static library with the option -DKV_BUILD_TYPE=static and would make the static library linked to a shared library, please include "-fPIC" option when build thrift library using ./configure CPPFLAGS=-fPIC, it was not used for static library by default.

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).

Build

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-4.4.6
```
then at a minimum your CMake command call is:
```
cmake /home/me/kv-c-driver-4.4.6/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. To make the static library can be linked to shared library, the "-fPIC" option is used when compile the source files, please make sure the thrift static cpp library is also built with "-fPIC" option.
- -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.

Test

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
```
- 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.

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. This command disables security, which is on by default.
```
$ mkdir kvroot
$ nohup java -jar <path-to-kvstore.jar> kvlite -root kvroot -store examples -host localhost -port 5000 -secure-config disable
```
"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-4.4.6/kvproxy/lib/kvproxy.jar \
-kvclient kv-c-driver-4.4.6/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

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:
- libkvstore.so -- the NoSQL DB client library
- libthrift.so -- the Thrift C++ runtime library
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.