INSTALLING.md

Installing pmemkv

Installation of Key-Value Datastore for Persistent Memory

Contents

1. Building from Sources
   • Prerequisites
   • Building pmemkv and running tests
   • Managing shared library
   • Out-of-source builds
2. Installing on Fedora
3. Installing on Ubuntu
4. Using Experimental Engines
5. Building packages
6. Using a Pool Set

Building from Sources

Prerequisites

• Linux 64-bit (OSX and Windows are not yet supported)
• libpmem and libpmemobj, which are part of PMDK - Persistent Memory Development Kit 1.9.1
• libpmemobj-cpp - C++ PMDK bindings 1.13.0
• memkind - Volatile memory manager 1.8.0 (required by vsmap & vcmap engines)
• TBB - Thread Building Blocks (required by vcmap engine)
• RapidJSON - JSON parser 1.0.0 (required by libpmemkv_json_config helper library)
• Used only for testing:
  • pmempool - pmempool utility, part of PMDK
  • valgrind - tool for profiling and memory leak detection. pmem forked version with pmemcheck tool is recommended, but upstream/original valgrind is also compatible (package valgrind-devel is required).
• Used only for development:
  • pandoc - markup converter to generate manpages
  • doxygen - tool for generating documentation from annotated C++ sources
  • graphviz - graph visualization software required by doxygen
  • perl - for whitespace checker script
  • clang format - to format and check coding style, version 9.0 is required

Required packages (or their names) for some OSes may differ. Some examples or scripts in this repository may require additional dependencies, but should not interrupt the build.

See our Dockerfiles (used e.g. on our CI systems) to get an idea what packages are required to build the entire pmemkv, with all tests and examples.

Building pmemkv and running tests

git clone https://github.com/pmem/pmemkv
cd pmemkv
mkdir ./build
cd ./build
cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug    # run CMake, prepare Debug version
make -j$(nproc)                 # build everything
make test                       # run all tests

To see the output of failed tests, instead of the last command (make test) you can run:

ctest --output-on-failure

Building of the libpmemkv_json_config helper library is enabled by default. If you want to disable it (for example to get rid of the RapidJSON dependency), instead of a standard cmake .. command run:

cmake .. -DBUILD_JSON_CONFIG=OFF

Managing shared library

To package pmemkv as a shared library and install on your system:

cmake .. [-DCMAKE_BUILD_TYPE=Release]	# prepare e.g. Release version
sudo make install			# install shared library to the default location: /usr/local
sudo make uninstall			# remove shared library and headers

To install this library into other locations, pass appropriate value to cmake using CMAKE_INSTALL_PREFIX variable like this:

cmake .. -DCMAKE_INSTALL_PREFIX=/usr [-DCMAKE_BUILD_TYPE=Release]
sudo make install		# install to path specified by CMAKE_INSTALL_PREFIX
sudo make uninstall		# remove shared library and headers from path specified by CMAKE_INSTALL_PREFIX

Out-of-source builds

If the standard build does not suit your needs, create your own out-of-source build and run tests like this:

cd ~
mkdir mybuild
cd mybuild
cmake ~/pmemkv       # this directory should contain the source code of pmemkv
make -j$(nproc)
make test            # or 'ctest --output-on-failure'

Installing on Fedora

Install required packages (see comprehensive list of packages used in our CI on a Fedora image in utils directory):

Configure for proxy if necessary:

git config --global http.proxy <YOUR PROXY>
export HTTP_PROXY="<YOUR PROXY>"
export HTTPS_PROXY="<YOUR PROXY>"

Install latest PMDK:

cd ~
git clone https://github.com/pmem/pmdk
cd pmdk
make -j$(nproc)
su -c 'make install'
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig

Install latest PMDK C++ bindings:

cd ~
git clone https://github.com/pmem/libpmemobj-cpp
cd libpmemobj-cpp
mkdir build
cd build
cmake ..
make -j$(nproc)
su -c 'make install'

Install latest memkind:

cd ~
git clone https://github.com/memkind/memkind
cd memkind
./autogen.sh
./configure
make
su -c 'make install'

Finally build and install pmemkv from sources.

Installing on Ubuntu

Install required packages (see comprehensive list of packages used in our CI on a Ubuntu image in utils directory):

sudo apt install autoconf automake build-essential cmake libdaxctl-dev \
	libndctl-dev libnuma-dev libtbb-dev libtool rapidjson-dev

Configure for proxy if necessary:

git config --global http.proxy <YOUR PROXY>
export HTTP_PROXY="<YOUR PROXY>"
export HTTPS_PROXY="<YOUR PROXY>"

Install latest PMDK:

cd ~
git clone https://github.com/pmem/pmdk
cd pmdk
make -j$(nproc)
sudo make install

Install latest PMDK C++ bindings:

cd ~
git clone https://github.com/pmem/libpmemobj-cpp
cd libpmemobj-cpp
mkdir build
cd build
cmake ..
make -j$(nproc)
sudo make install

Install latest memkind:

cd ~
git clone https://github.com/memkind/memkind
cd memkind
./autogen.sh
./configure
make
sudo make install

Finally build and install pmemkv from sources.

Using Experimental Engines

To enable experimental engine(s) use adequate CMake parameter, e.g.:

cmake .. -DENGINE_CSMAP=ON

Now build will contain selected experimental engine(s) and their dependencies, that are not available by default.

Experimental engines may require additional libraries, see prerequisites section of a selected engine in ENGINES-experimental.md.

Building packages

...
cmake .. -DCPACK_GENERATOR="$GEN" -DCMAKE_INSTALL_PREFIX=/usr [-DCMAKE_BUILD_TYPE=Release]
make -j$(nproc) package

$GEN is a type of package generator and can be RPM or DEB.

CMAKE_INSTALL_PREFIX must be set to a destination where packages will be installed.

Using a Pool Set

First create a pool set descriptor (~/pmemkv.poolset in this example):

PMEMPOOLSET
1000M /dev/shm/pmemkv1
1000M /dev/shm/pmemkv2

Next initialize the pool set:

pmempool create --layout pmemkv obj ~/pmemkv.poolset