README

================
=== 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)
      A working snapshot is available at: www.hypertable.org/pub/thrift.tgz
      This snapshot is based off: 
      http://github.com/dreiss/thrift/commit/8fac5e4c37b75ccb93b757e83a5587de2091ab91
      
      Alternately grabbing a recent snapshot from the following location should work:
      http://gitweb.thrift-rpc.org/?p=thrift.git;a=summary

      The usual configure/make/make install will install the thrift IDL
      compiler and c++, ruby, perl, python and java libraries by default but
      not for other languages including php, c#, erlang 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, yum for Redhat/Fedora/CentOS and
    MacPorts for Mac OS X. To install an apt-get package: sudo apt-get install
    <package>; a yum package: sudo yum install <package>; a MacPorts package:
    sudo port 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