rocksdb/INSTALL.md
Nikhil Benesch 11c5d4741a cross-platform compatibility improvements
Summary:
We've had a couple CockroachDB users fail to build RocksDB on exotic platforms, so I figured I'd try my hand at solving these issues upstream. The problems stem from a) `USE_SSE=1` being too aggressive about turning on SSE4.2, even on toolchains that don't support SSE4.2 and b) RocksDB attempting to detect support for thread-local storage based on OS, even though it can vary by compiler on the same OS.

See the individual commit messages for details. Regarding SSE support, this PR should change virtually nothing for non-CMake based builds. `make`, `PORTABLE=1 make`, `USE_SSE=1 make`, and `PORTABLE=1 USE_SSE=1 make` function exactly as before, except that SSE support will be automatically disabled when a simple SSE4.2-using test program fails to compile, as it does on OpenBSD. (OpenBSD's ports GCC supports SSE4.2, but its binutils do not, so `__SSE_4_2__` is defined but an SSE4.2-using program will fail to assemble.) A warning is emitted in this case. The CMake build is modified to support the same set of options, except that `USE_SSE` is spelled `FORCE_SSE42` because `USE_SSE` is rather useless now that we can automatically detect SSE support, and I figure changing options in the CMake build is less disruptive than changing the non-CMake build.

I've tested these changes on all the platforms I can get my hands on (macOS, Windows MSVC, Windows MinGW, and OpenBSD) and it all works splendidly. Let me know if there's anything you object to—I obviously don't mean to break any of your build pipelines in the process of fixing ours downstream.
Closes https://github.com/facebook/rocksdb/pull/2199

Differential Revision: D5054042

Pulled By: yiwu-arbug

fbshipit-source-id: 938e1fc665c049c02ae15698e1409155b8e72171
2017-05-15 16:15:38 -07:00

5.5 KiB

Compilation

Important: If you plan to run RocksDB in production, don't compile using default make or make all. That will compile RocksDB in debug mode, which is much slower than release mode.

RocksDB's library should be able to compile without any dependency installed, although we recommend installing some compression libraries (see below). We do depend on newer gcc/clang with C++11 support.

There are few options when compiling RocksDB:

  • [recommended] make static_lib will compile librocksdb.a, RocksDB static library. Compiles static library in release mode.

  • make shared_lib will compile librocksdb.so, RocksDB shared library. Compiles shared library in release mode.

  • make check will compile and run all the unit tests. make check will compile RocksDB in debug mode.

  • make all will compile our static library, and all our tools and unit tests. Our tools depend on gflags. You will need to have gflags installed to run make all. This will compile RocksDB in debug mode. Don't use binaries compiled by make all in production.

  • By default the binary we produce is optimized for the platform you're compiling on (-march=native or the equivalent). SSE4.2 will thus be enabled automatically if your CPU supports it. To print a warning if your CPU does not support SSE4.2, build with USE_SSE=1 make static_lib or, if using CMake, cmake -DFORCE_SSE42=ON. If you want to build a portable binary, add PORTABLE=1 before your make commands, like this: PORTABLE=1 make static_lib.

Dependencies

  • You can link RocksDB with following compression libraries:

    • zlib - a library for data compression.
    • bzip2 - a library for data compression.
    • snappy - a library for fast data compression.
    • zstandard - Fast real-time compression algorithm.
  • All our tools depend on:

    • gflags - a library that handles command line flags processing. You can compile rocksdb library even if you don't have gflags installed.

Supported platforms

  • Linux - Ubuntu

    • Upgrade your gcc to version at least 4.8 to get C++11 support.
    • Install gflags. First, try: sudo apt-get install libgflags-dev If this doesn't work and you're using Ubuntu, here's a nice tutorial: (http://askubuntu.com/questions/312173/installing-gflags-12-04)
    • Install snappy. This is usually as easy as: sudo apt-get install libsnappy-dev.
    • Install zlib. Try: sudo apt-get install zlib1g-dev.
    • Install bzip2: sudo apt-get install libbz2-dev.
    • Install zstandard: sudo apt-get install libzstd-dev.
  • Linux - CentOS / RHEL

    • Upgrade your gcc to version at least 4.8 to get C++11 support: yum install gcc48-c++

    • Install gflags:

          git clone https://github.com/gflags/gflags.git
          cd gflags
          git checkout v2.0
          ./configure && make && sudo make install
      

      Notice: Once installed, please add the include path for gflags to your CPATH environment variable and the lib path to LIBRARY_PATH. If installed with default settings, the include path will be /usr/local/include and the lib path will be /usr/local/lib.

    • Install snappy:

          sudo yum install snappy snappy-devel
      
    • Install zlib:

          sudo yum install zlib zlib-devel
      
    • Install bzip2:

          sudo yum install bzip2 bzip2-devel
      
    • Install ASAN (optional for debugging):

          sudo yum install libasan
      
    • Install zstandard:

         wget https://github.com/facebook/zstd/archive/v1.1.3.tar.gz
         mv v1.1.3.tar.gz zstd-1.1.3.tar.gz
         tar zxvf zstd-1.1.3.tar.gz
         cd zstd-1.1.3
         make && sudo make install
      
  • OS X:

    • Install latest C++ compiler that supports C++ 11:
      • Update XCode: run xcode-select --install (or install it from XCode App's settting).
      • Install via homebrew.
        • If you're first time developer in MacOS, you still need to run: xcode-select --install in your command line.
        • run brew tap homebrew/versions; brew install gcc48 --use-llvm to install gcc 4.8 (or higher).
    • run brew install rocksdb
  • iOS:

    • Run: TARGET_OS=IOS make static_lib. When building the project which uses rocksdb iOS library, make sure to define two important pre-processing macros: ROCKSDB_LITE and IOS_CROSS_COMPILE.
  • Windows:

    • For building with MS Visual Studio 13 you will need Update 4 installed.
    • Read and follow the instructions at CMakeLists.txt
  • AIX 6.1

    • Install AIX Toolbox rpms with gcc

    • Use these environment variables:

         export PORTABLE=1
         export CC=gcc
         export AR="ar -X64"
         export EXTRA_ARFLAGS=-X64
         export EXTRA_CFLAGS=-maix64
         export EXTRA_CXXFLAGS=-maix64
         export PLATFORM_LDFLAGS="-static-libstdc++ -static-libgcc"
         export LIBPATH=/opt/freeware/lib
         export JAVA_HOME=/usr/java8_64
         export PATH=/opt/freeware/bin:$PATH
      
  • Solaris Sparc

    • Install GCC 4.8.2 and higher.

    • Use these environment variables:

         export CC=gcc
         export EXTRA_CFLAGS=-m64
         export EXTRA_CXXFLAGS=-m64
         export EXTRA_LDFLAGS=-m64
         export PORTABLE=1
         export PLATFORM_LDFLAGS="-static-libstdc++ -static-libgcc"