Install the Core+ C++ client

The Deephaven Core+ C++ client allows you to create and connect to Persistent Queries using the Community Core engine in the Deephaven Enterprise system. This page provides an overview of how to install the C++ client.

Obtain the C++ client sources

Contact your Deephaven representative to obtain the C++ client source bundle.

The source bundle includes a Dockerized build script that can be used in any supported Linux machine with Docker and Docker's buildx installed (buildx is the Docker CLI plugin for extended build capabilities with BuildKit). The script produces a binary package for supported platforms.

The source bundle is named dhe-cpp-src-<version>.tgz, where <version> is the Deephaven Enterprise version. Ensure that the version matches the version of the Deephaven Enterprise server you are connecting to.

Supported OS

The C++ client sources can only be built on Ubuntu 22.04. However, the build process produces a source bundle that can be used on any of the following operating systems:

  • Ubuntu 22.04
  • RHEL 9

Prerequisites

The Dockerized build uses a script to build the client. It requires docker and docker buildx, which can be installed by following the steps in Install Docker on Ubuntu. Additionally, if you need to run Docker as a non-root user, follow the instructions in Manage Docker as a non-root user. If you don't follow those steps, be sure to run the Dockerized build script with sudo.

All other prerequisites to use the client API are installed by the build script itself.

Unpack the client sources

Unpack the source bundle in a directory of your choice:

ROOT_DIR=/path/to/source/bundle
VERSION=<version>  # e.g. 1.20240517.499
cd $ROOT_DIR
tar -xvf dhe-cpp-src-$VERSION.tgz

Installation steps

The Dockerized build creates a series of 4 Docker images, each depending on the previous one:

  • dhe-cpp-base: The dependent C++ libraries, which include arrow, gRPC, and their respective dependencies.
  • dhe-cpp-dhc: The Community Core C++ client API.
  • dhe-cpp-dhe: The Enterprise Core+ C++ client API.
  • dhe-cpp-bundle: An image that contains a .tgz bundle with the final result that can be extracted from a Docker container and installed for use on any compatible machine.

The docker-build.sh script has a few parameters:

  • --base-distro: The Linux distribution to use. Defaults to ubuntu:22.04. Other valid options include:
    • registry.access.redhat.com/ubi8/ubi-minimal:9.6 for RHEL 9.
  • --prefix: The installation directory. Defaults to /opt/deephaven.
  • --clear-images: Automatically remove the images after the build. This behavior is disabled by default.

The Dockerized build script, docker-build.sh, can be found in $ROOT_DIR/coreplus/cpp-client/.

Before running the script, change the coreplus folder to DhcInDhe:

cd $ROOT_DIR
mv coreplus DhcInDhe

Then, cd into the cpp-client directory to run the build script:

cd DhcInDhe/cpp-client

Here are three examples of running the Dockerized build script:

# Build for Ubuntu 22.04 with the root directory set to /opt/deephaven
PREFIX=/opt/deephaven
DISTRO=ubuntu:22.04

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX

# Build for Fedora 38 with the root directory set to /opt/deephaven
PREFIX=/opt/deephaven
DISTRO=fedora:38

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX

# Build for RHEL 8 with the root directory set to /usr/local/deephaven and clear Docker images after the build
PREFIX=/usr/local/deephaven
DISTRO=registry.access.redhat.com/ubi8/ubi-minimal:8.8

./docker-build.sh --base-distro $DISTRO --prefix $PREFIX --clear-images

Note

The Docker images are not needed once the build is complete. The --clear-images option removes them after the build. If you plan to install the Core+ R client, you will need the Docker images produced during the build.

The build script creates a .tgz bundle in the build/ directory. For example, if you built against RHEL 8:

build/dhe-cpp-latest-ubi-8.8.tgz

Unpack the build bundle

The build/ tar bundle contains files relative to the $PREFIX you specified. For example, if you specified PREFIX=/usr/local/deephaven, the organization of the tar file is /usr/local/deephaven/....

Because of this organization, it is easiest to unpack the tar bundle in the root of the filesystem. You may need root access to unpack the bundle at /.

The $PREFIX is hardcoded into the installation. You cannot change your choice of installation directory without redoing the build.

cd build
tar -xvf <tar_bundle> --directory=/

Source the environment

At the root of the --prefix directory is an env.sh script that sets the environment variables needed to run the C++ client. This script should be sourced before running any C++ client program:

cd $PREFIX
source env.sh

Once this is done, you're ready to use the C++ client. The usage guide provides examples of how to use the client. For the quickest way to test the client against your Deephaven Enterprise installation, see Test scripts.