================
=== CONTENTS ===
================

  * HOW TO BUILD
  * HOW TO RUN REGRESSION TESTS
  * HOW TO BUILD SOURCE CODE DOCUMENTATION TREE (Doxygen and Thrift)

====================
=== HOW TO BUILD ===
====================

  1. Install development environment (if necessary)

    - A standard C++ compiler (e.g.: GCC 4.0+ recommended)
      apt-get: g++; yum: gcc-c++; source: http://gcc.gnu.org/ (*)

    - GNU make 3.81+
      apt-get: make; yum: make

    - cmake 2.4.6+
      apt-get: cmake; yum: cmake; source: http://www.cmake.org/

  2. Install required libraries

    - BerkeleyDB 4.6+
      apt-get: libdb4.6++-dev; yum: db4-devel

      Building from source for generic Linux distribution:
      tar -xzvf ~/Downloads/db-4.7.25.tar.gz
      cd db-4.7.25/build_unix/
      ../dist/configure --enable-cxx
      make
      sudo make install
      echo "/usr/local/BerkeleyDB.4.7/lib" | \
          sudo tee /etc/ld.so.conf.d/BerkeleyDB.conf
      sudo /sbin/ldconfig

    - Boost version 1.34.1+
      apt-get: libboost-.*-dev; yum: boost-devel; source: http://www.boost.org/
      Note: if distribution has version older than 1.34.1+, try the generic way.

    - log4cpp 1.0+ dev lib
      apt-get: liblog4cpp5-dev; yum: log4cpp-devel;
      source: http://log4cpp.sourceforge.net/

    - sigar
      Example install on Linux system:
      binary tarball:  http://sourceforge.net/projects/sigar/
      tar -xzvf download/hyperic-sigar-1.6.0.tar.gz
      sudo cp hyperic-sigar-1.6.0/sigar-bin/include/*.h /usr/local/include
      sudo cp hyperic-sigar-1.6.0/sigar-bin/lib/libsigar-amd64-linux.so \
          /usr/local/lib # for 64-bit x86_64 machines
      ldconfig

      [NOTE: The amd64 sigar library works for 64-bit Xeon as well]

    - expat 0.9+ dev lib
      yum: expat-devel; apt-get: libexpat1-dev
      source: http://sourceforge.net/projects/expat

    - readline dev lib
      apt-get: libreadline5-dev; yum: readline-devel;
      source: http://tiswww.case.edu/php/chet/readline/rltop.html

    - ncurses dev lib (usually auto installed by installing the above)

    - zlib dev lib
      apt-get: zlib1g-dev; yum: zlib-devel; source: http://zlib.net/

    - libevent dev lib (only needed for ThriftBroker support)
      apt-get: libevent-dev; yum: libevent-devel;
      source: http://www.monkey.org/~provos/libevent/

    - thrift (only needed for ThriftBroker support)
      Grab a snapshot containing fixes for THRIFT-203 (Apache Jira) from:
      http://gitweb.thrift-rpc.org/?p=thrift.git;a=summary
      A Working snapshot: http://tr.im/2r61

      The usual configure/make/make install will install the thrift IDL
      compiler and c++, ruby and java libraries by default but not for other
      languages including python, perl and php etc. You need to follow the
      installation instructions for each of these languages.

    RECOMMENDED (but not required):

    - tcmalloc (to improve server memory usage and performance)
      apt-get: libgoogle-perftools-dev; yum: google-perftools-devel
      source: http://code.google.com/p/google-perftools/
    - sparse hash 
      apt-get: sparsehash; yum: sparsehash
      source: http://code.google.com/p/google-sparsehash/
    - cronolog (for log rotation)
      apt-get: cronolog; source: http://cronolog.org/

  3. Checkout the source code or download source tarball

    mkdir ~/src
    cd ~/src
    git clone git://scm.hypertable.org/pub/repos/hypertable.git

    or if tarball:
    tar zxvf <path_to_tarball>

  4. Create an install directory (optional)

    mkdir ~/hypertable

  5. Create a build directory

    mkdir -p ~/build/hypertable

  6. Configure the build.

    cd ~/build/hypertable
    cmake ~/src/hypertable

    By default, hypertable gets installed in /opt/hypertable. To install into
    your own install directory, say $prefix, you can use:

    cmake -DCMAKE_INSTALL_PREFIX=$prefix ~/src/hypertable

    By default the build is configured for debug. To make a release build for
    production/performance test/benchmark:

    cmake -DCMAKE_BUILD_TYPE=Release ~/src/hypertable

    Note, you can also use:

    ccmake ~/src/hypertable

    to change build parameters interactively.

    To build shared libraries, e.g., for scripting language extensions:
    cmake -DBUILD_SHARED_LIBS=ON ~/src/hypertable

    Since PHP has no builtin package system, its thrift installation needs to
    be manually specified for ThriftBroker support:
    cmake -DPHPTHRIFT_ROOT=~/thrift/lib/php/src ~/src/hypertable

  7. Build Hypertable binaries.

    make (or make -j<number_of_cpu_or_cores_plus_1> for faster compile)
    make install

    Note, if it's a shared library install, you might need to do:
    echo $prefix/$version/lib' | \
        sudo tee /etc/ld.so.conf.d/hypertable
    sudo /sbin/ldconfig

    Or, you can use the usual LD_LIBRARY_PATH (most Unix like OS) and
    DYLD_LIBRARY_PATH (Mac OS X) to specify non-standard shared library
    directories.


  * Note: Most OS distributions have their own package managers. Popular ones
    include apt-get for Ubuntu/Debian and yum for Redhat/Fedora/CentOS.
    To install an apt-get package: sudo apt-get install <package>;
    a yum package: sudo yum install <package>.

===================================
=== HOW TO RUN REGRESSION TESTS ===
===================================

1. Make sure software is built and installed according to 'HOW TO BUILD'

2. Run the regression tests

  cd ~/build/hypertable
  make alltests

  Note: there're two other high-level test targets: coretests (for core tests)
  and moretests (for more longer running tests, which is included in alltests.)
  These high-level test targets will (re)start test servers automatically when
  new servers are installed.  There is also a low-level 'test' target in root
  of the build tree and src (and src/<lang>/<Components>) and tests/integration
  directories that does NOT auto restart test servers. To force a restart of
  servers, remove the 'test-servers-started' file in the build directory.

=============================================================
=== HOW TO BUILD SOURCE CODE DOCUMENTATION TREE (Doxygen) ===
=============================================================

1. Install the following libraries:
  - doxygen (http://www.stack.nl/~dimitri/doxygen/)
  - graphviz (http://www.graphviz.org/)

2. If you have doxygen installed on your system, then CMake should detect this
   and add a 'doc' target to the make file.  Building the source code
   documentation tree is just a matter of running the following commands:

   cd ~/build/hypertable
   make doc

The source code documentation tree will get generated under
~/build/hypertable/doc. The thrift API reference documentation will get
generated under ~/build/hypertable/gen-html. To view the docs, load the
following file into a web browser:

  ~/build/hypertable/doc/html/index.html for source code documentation and,
  ~/build/hypertable/gen-html/index.html for thrift API documentation.

The thrift doc can also be generated independently (without doxygen installed)
by running the follow command in the build tree:

  make thriftdoc