Installation

Note

The easiest way to try out TileDB is to use a pre-built Docker image:

docker pull tiledb/tiledb
docker run -it tiledb/tiledb

which uses the latest TileDB version, or:

docker pull tiledb/tiledb:<version>
docker run -it tiledb/tiledb:<version>

which uses a specific TileDB version (ex. <version> could be 1.2.0).

More info at TileDB Docker Hub repo and the TileDB-Docker repo.

Pre-built Packages

Homebrew

TileDB can be installed easily using the Homebrew package manager for macOS. Install instructions for Homebrew are provided on the package manager’s website.

To install the latest stable version of TileDB:

brew update
brew install tiledb-inc/stable/tiledb

HDFS and S3 backends are not enabled by default. To build / install with one or more backends, use the --with- switch to enable them:

brew install tiledb-inc/stable/tiledb --with-s3
brew install tiledb-inc/stable/tiledb --with-hdfs

A full list of build options can be viewed with the info command:

brew info tiledb-inc/stable/tiledb

To upgrade to the latest stable version of TileDB:

brew upgrade tiledb-inc/stable/tiledb

To uninstall TileDB:

brew uninstall tiledb-inc/stable/tiledb

Homebrew Tap is located at https://github.com/TileDB-Inc/homebrew.

Conda

A package for TileDB is available for the Conda package manager. Conda makes it easy to install software into separate distinct environments on Windows, Linux, and macOS.

conda install -c conda-forge tiledb

Note: Conda packages are not currently built with the HDFS and S3 storage backends enabled.

If you are compiling / linking against the TileDB conda package, you need to explicity add the conda env path after activation:

export CPATH=$CONDA_PREFIX/include
export LIBRARY_PATH=$CONDA_PREFIX/lib
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib

Or as command line flags during compilation:

gcc -I$CONDA_PREFIX/include -L$CONDA_PREFIX/lib -ltiledb tiledb_example.cc -o tiledb_example

Windows Binaries

The easiest way to install TileDB on Windows is to download the .zip file containing pre-built Windows binaries from the latest TileDB release. You can then simply configure your project (if using Visual Studio) according to the Windows usage instructions.

Requirements

Operating Systems

TileDB has been tested on Ubuntu Linux (v.14.04+), CentOS Linux (v.7+), macOS Sierra (v.10.12) and Windows (7+), but TileDB should work with any reasonably recent version of Ubuntu, CentOS, macOS or Windows with an installed compiler supporting C++11.

Required Dependencies

TileDB requires a recent version (3.3 or later) of the CMake build system.

TileDB has minimal required dependencies and currently relies on the following libraries for compression:

When building from source, TileDB will locate these dependencies if already installed on your system, and locally install (not system-wide) any of them that are missing.

Optional Dependencies

TBB

Some TileDB internals are parallelized using the Intel Threaded Building Blocks library. The TileDB build system will install this library if it is not already present on your system. You can disable the TBB dependency when configuring the TileDB build, in which case TileDB will fall back on serial implementations of several algorithms. As a part of the TileDB installation process, the TBB dynamic library will also be installed in the same destination as the TileDB dynamic library. The TBB headers are not installed with TileDB.

S3

Backend support for S3 stores requires the AWS C++ SDK. Similarly to the required dependencies, the TileDB build system will install the SDK locally if it is not already present on your system (when the S3 build option is enabled).

TileDB also integrates well with the S3-compliant minio object store.

HDFS

Backend support for the Hadoop File System HDFS is optional. TileDB relies on the C interface to HDFS provided by libhdfs to interact with the distributed filesystem.

During the build process the following environmental variables must be set:

  • JAVA_HOME: Path to the location of the Java installation.
  • HADOOP_HOME: Path to the location of the HDFS installation.
  • CLASSPATH: The Hadoop jars must be added to the CLASSPATH before running interacting with libhdfs.

Consult the HDFS user guide for installing, setting up, and using the distributed Hadoop file system.

Building from Source

POSIX Systems

Begin by downloading a release tarball or by cloning the TileDB GitHub repo and checking out a release tag:

git clone https://github.com/TileDB-Inc/TileDB
git checkout <version>
cd TileDB

where <version> is the version you wish to use (e.g., 1.2.0).

To configure TileDB, you can use the bootstrap script to run the CMake build generator:

mkdir build
cd build
../bootstap <flags>

You can also use the CMake command directly:

mkdir build
cd build
cmake <flags> ..

The flags for the bootstrap script and the CMake equivalents are as follows:

Flag Description CMake Equivalent
--help Prints command line flag options n/a
--prefix=PREFIX Install files in tree rooted at PREFIX (defaults to TileDB/dist) CMAKE_INSTALL_PREFIX=<PREFIX>
--dependency=DIRs Colon separated list to binary dependencies CMAKE_PREFIX_PATH=<DIRs>
--enable-debug Enable debug build CMAKE_BUILD_TYPE=Debug
--enable-coverage Enable build with code coverage support CMAKE_BUILD_TYPE=Coverage
--enable-verbose Enable verbose status messages TILEDB_VERBOSE=ON
--enable-hdfs Enables building with HDFS storage backend support TILEDB_HDFS=ON
--enable-s3 Enables building with S3 storage backend support TILEDB_S3=ON
--disable-werror Disables building with the -Werror flag TILEDB_WERROR=OFF
--disable-cpp-api Disables building the TileDB C++ API TILEDB_CPP_API=OFF
--disable-tbb Disables use of TBB for parallelization TILEDB_TBB=OFF

After configuring, run the generated make script:

make -j <nprocs>

To build the examples run:

make examples

To run the tests:

make check

To install to the configured prefix:

make -C tiledb install

TileDB uses the Catch C++ unit test framework for testing.

Additional command line flags can be provided to the tiledb/test/tiledb_unit binary for controlling which tests are run and test output.

Windows

This section details how to build TileDB from source if you do not wish to use the precompiled DLLs from the .zip file attached to the TileDB releases.

Building TileDB on Windows has been tested to work with Microsoft Visual Studio 2017. You can install the free Community Edition if you’d like the full IDE, or the Build Tools only if you don’t need the IDE installed.

During the Visual Studio setup process, make sure the Git for Windows component is selected if you do not already have a working Git installation. Also be sure to select the CMake component if you do not have a working CMake installation.

In addition, you will need to install PowerShell (free).

To build and install TileDB, first open PowerShell and clone the TileDB repository:

> git clone https://github.com/TileDB-Inc/TileDB
> cd TileDB

Next, ensure the CMake binaries are in your path. If you installed Visual Studio, execute:

> $env:Path += ";C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"

If you installed the build tools, instead execute:

> $env:Path += ";C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin"

Next create a build directory and configure TileDB:

> mkdir build
> cd build
> ..\bootstrap.ps1 <flags>

You can also use the CMake command directly:

> mkdir build
> cd build
> cmake <flags> ..

The flags for the bootstrap script and the CMake equivalents are as follows:

Flag Description CMake Equivalent
-? Display a usage message. n/a
-Prefix Install files in tree rooted at PREFIX (defaults to TileDB\dist) CMAKE_INSTALL_PREFIX=<PREFIX>
-Dependency Semicolon separated list to binary dependencies. CMAKE_PREFIX_PATH=<DIRs>
-CMakeGenerator Optionally specify the CMake generator string, e.g. “Visual Studio 15 2017”. Check ‘cmake –help’ for a list of supported generators. -G <generator>
-EnableDebug Enable debug build CMAKE_BUILD_TYPE=Debug
-EnableVerbose Enable verbose status messages. TILEDB_VERBOSE=ON
-EnableS3 Enables building with the S3 storage backend. TILEDB_S3=ON
-DisableWerror Disables building with the /WX flag TILEDB_WERROR=OFF
-DisableCppApi Disables building the TileDB C++ API TILEDB_CPP_API=OFF
-DisableTBB Disables use of TBB for parallelization TILEDB_TBB=OFF

Note that the HDFS storage backend is not yet supported on Windows.

Finally, run the build:

> cmake --build . --config Release

To run the tests:

> cmake --build . --target check --config Release

Or to build and install:

> cd tiledb
> cmake --build . --target install --config Release

Python Bindings

Build and install instructions for Python bindings can be found at the TileDB-Inc/TileDB-Py repo.