Graphlab
                         --------

=======
License
=======

GraphLab is free software licensed under the Apache 2.0 License. See
license/LICENSE.txt for details.

The GraphLab source distribution contains a modified version of METIS
which is under a different license. See the file 
src/graphlab/extern/metis/LICENSE for further details.

For more information, contact Yucheng Low at ylow@cs.cmu.edu or 
Joseph Gonzalez at jegonzal@cs.cmu.edu .

============
Introduction
============
Designing and implementing efficient and provably correct parallel 
machine learning (ML) algorithms can be very challenging. Existing 
high-level parallel abstractions like MapReduce are often insufficiently 
expressive while low-level tools like MPI and Pthreads leave ML experts 
repeatedly solving the same design challenges. By targeting common 
patterns in ML, we developed GraphLab, which improves upon abstractions 
like MapReduce by compactly expressing asynchronous iterative algorithms 
with sparse computational dependencies while ensuring data consistency 
and achieving a high degree of parallel performance.

For more details on the GraphLab see http://graphlab.ml.cmu.edu


============
Dependencies
============
We require Cmake, Boost and Kyoto Cabinet. If you use distributed
GraphLab, we also require MPI.


CMake
-----
You can obtain CMake from 
 - http://www.cmake.org/cmake/resources/software.html


Boost
-----
We have tested with Boost 1.46. Many earlier versions, and all later
versions should work as well.

To install Boost 1.46 with the minimal set of libraries:

   # download
   wget http://sourceforge.net/projects/boost/files/boost/1.46.1/boost_1_46_1.tar.bz2/download boost.tar.bz2
   cd boost_1_46_1
   
   # configure
   ./bootstrap.sh --with-libraries="filesystem,program_options,system,iostreams"
   
   # compile
   ./bjam --threading=multi --link=static --variant=release | tee bjamlog.txt
   
   # install 
   sudo ./bjam install


Kyoto Cabinet
-------------
We have tested with Kyoto Cabinet 1.2.53. Later versions should work
as well.

To install Kyoto Cabinet 1.2.53: 
   # download
   wget http://fallabs.com/kyotocabinet/pkg/kyotocabinet-1.2.53.tar.gz kyotocabinet.tar.gz
   cd kyotocabinet-1.2.53
   
   # configure
   ./configure
   
   # compile
   make
    
   # install
   sudo make install


MPI
---
We have tested with MPICH2. Open MPI might also work. 
Mac OS X comes with MPI and works out of the box.

To install MPICH2:
   # download
   http://www.mcs.anl.gov/research/projects/mpich2/downloads/tarballs/1.3.2p1/mpich2-1.3.2p1.tar.gz
   cd mpich2-1.3.2p1/
   
   # configure
   ./configure
   
   # compile
   make
   
   # install
   sudo make install
   

===========
Compilation
===========
GraphLab has three dependencies: CMake, Boost and Kyoto Cabinet

If you already have all dependencies satistied,
1a: ./configure

Otherwise, autodetect, install and build boost, CMake and Kyoto Cabinet.
Note that this will install all the dependencies in the deps/ directory
and not install them globally. We STRONGLY recommend installing all the 
dependencies globally. See the "Dependencies" section.

1b: ./configure --bootstrap 


The configure script will create three subdirectories
debug/
release/
profile/
With different configuration profiles.

cd into any of the subdirectories and run "make" will compile the entire 
GraphLab library + demoapps + unit tests. "make install" will install the
graphlab library.


==================
Running Unit Tests
==================
# switch into any of the build subdirectories
1:  cd debug/ or cd release/ or cd profile/

# cd into the tests directory
2:  cd tests/

# run the test script 
3:  ./runtest.sh

If you encounter any failures, please send us an email.


=====================
Writing Your Own Apps
=====================
There are two ways to write your own apps.
1: To work in the GraphLab source tree,
or
2: Install and link against Graphlab

1: Working in the GraphLab Source Tree
---------------------------------------
This is the best option if you just want to try using GraphLab quickly. GraphLab
uses the fairly sophisticated CMake build system enabling you to quickly create
a c++ project without having to write complicated Makefiles. 

1: Create your own sub-directory in the apps/ directory
   for example apps/my_app
   
2: Create a CMakeLists.txt in apps/my_app containing the following lines:

  project(GraphLab) 
  add_graphlab_executable(my_app [List of cpp files space seperated]) 
  target_link_libraries(my_app [Additional libraries space seperated])

  Substituting the right values into the square brackets. For instance:

  project(GraphLab) 
  add_graphlab_executable(my_app my_app.cpp) 
  target_link_libraries(my_app tcmalloc)

  If you have no additional libraries, you can comment out the 
  target_link_libraries line by prepending it with a # character.

3: Running ./configure --bootstrap in the base of the source tree will then
create a debug/ release/ and profile/ directory with different build 
configurations.

4: Running "make" in any of the build directories will compile your program
in the apps/my_app directory.



2: Installing and Linking Against GraphLab
-------------------------------------------
Run the ./configure --bootstrap script to create the build directories. You can
change the default installation location (currently /usr/local) using the
--prefix option. For more options see ./configure

Once you have run the configure script change directories to release/ and then
run make and then make install . This will install the following:

  include/graphlab.hpp
      The primary GraphLab header 
  include/graphlab/...
      The folder containing the headers for the rest of the GraphLab library 
  lib/libgraphlab.a
      The main GraphLab binary 
    
Once you have installed GraphLab you can compile your program by running:

  g++ hello_world.cpp -lboost_program_options -lgraphlab 
  
  
Known Installation Issues
=========================

Boost configuration
--------------------
If running ./configure fails because of Boost libraries are not found, you might
need to declare environment variable BOOST_ROOT which points to the installation
directory of Boost. You can do this using:

env BOOST_ROOT=[location of boost installation] ./configure --bootstrap

Alternatively, you can try using our automatic dependency installing tools by
running

./configure --bootstrap

Please let us know if you have trouble configuring GraphLab on your system.

Mac OS X
--------
on Mac OS X, you also need to include Boost libraries in the list of
dynamic libraries defined in environment variable DYLD_LIBRARY_PATH. Here is an
example:
declare -x DYLD_LIBRARY_PATH=":${BOOST_ROOT}/stage/lib:${DYLD_LIBRARY_PATH}"