Bumping version to 0.11.0

[hoomd-blue.git] / doc / user / compile_guide_linux_generic.doc

/*
Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
(HOOMD-blue) Open Source Software License Copyright 2008-2011 Ames Laboratory
Iowa State University and The Regents of the University of Michigan All rights
reserved.

HOOMD-blue may contain modifications ("Contributions") provided, and to which
copyright is held, by various Contributors who have granted The Regents of the
University of Michigan the right to modify and/or distribute such Contributions.

You may redistribute, use, and create derivate works of HOOMD-blue, in source
and binary forms, provided you abide by the following conditions:

* Redistributions of source code must retain the above copyright notice, this
list of conditions, and the following disclaimer both in the code and
prominently in any materials provided with the distribution.

* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions, and the following disclaimer in the documentation and/or
other materials provided with the distribution.

* All publications and presentations based on HOOMD-blue, including any reports
or published results obtained, in whole or in part, with HOOMD-blue, will
acknowledge its use according to the terms posted at the time of submission on:
http://codeblue.umich.edu/hoomd-blue/citations.html

* Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
http://codeblue.umich.edu/hoomd-blue/

* Apart from the above required attributions, neither the name of the copyright
holder nor the names of HOOMD-blue's contributors may be used to endorse or
promote products derived from this software without specific prior written
permission.

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.

IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/


/*! 
\page page_compile_guide_linux_generic Compiling HOOMD-blue on Linux (generic)

Table of contents:
 - \ref sec_build_linux_generic_prereq
 - \ref sec_build_linux_generic_compile
<hr>

\section sec_build_linux_generic_prereq Software Prerequisites

This page assumes that you have a standard terminal window open. Commands to run will
be indicated as below:
\code
 $ echo hello
hello
\endcode
" $ " indicates a shell prompt. As demonstrated above, if you type "echo hello", then you should see the same
output obtained above on the next line: "hello"

The process for installing software/libraries differs from linux distribution to distribution. 
In Gentoo (http://www.gentoo.org/) 
\code
 $ emerge python
\endcode
would install python. Look at your linux distribution's documentation to find how to install
packages on your system (i.e. yum, apt-get, up2date, or another). You may need to "su -" or use sudo to
become root before installing.

\section software_req_install_linux_python Python

First, check if python is already installed
\code
 $ python -V
Python 2.4.4
\endcode
Make sure that the version is 2.3 or greater. If you get
\code
bash: python: command not found
\endcode
or have a version older than 2.3, you will need to upgrade/install python. 
Note that you will also 
need the python development libraries which some distributions might separate into into
python-devel or some such. The existence of the python development package can be tested
by checking the output of 
\code 
 $ ls /usr/include/python2.X/Python.h
/usr/include/python2.X/Python.h
\endcode
where X is replaced with the major version of python that you have (i.e. For python 2.4.4 above,
X would be 4). If this returned 
\code
ls: cannot access /usr/include/python2.X/Python.h: No such file or directory
\endcode
then you do not have the python development libraries installed.



\section software_req_install_linux_boost Boost

First, check if boost is already installed
\code
 $ grep BOOST_LIB_VERSION /usr/include/boost/version.hpp
//  BOOST_LIB_VERSION must be defined to be the same as BOOST_VERSION
#define BOOST_LIB_VERSION "1_34_1"
\endcode
Make sure that the version is 1_32_0 or newer. If you get
\code
grep: /usr/include/boost/version.hpp: No such file or directory
\endcode
then boost is not installed. You can upgrade/install boost with your distribution's package
manager. You may need to install the boost-static package to get the static libraries needed by
HOOMD-blue.

If your distribution doesn't have a new enough version of boost, you can build it by hand. Building boost is a time consuming process, but not complicated if you follow these instructions.

Start by downloading \b boost_1_41_0.tar.bz2 from http://www.boost.org/ . Extract the tarball and 
configure boost for building with the following commands.
\code
 $ tar -xjf boost_1_41_0.tar.bz2 
 $ cd boost_1_41_0
 $ ./bootstrap.sh --prefix=/home/myuser/software
-n Building Boost.Jam with toolset darwin... 
tools/jam/src/bin.macosxx86/bjam
-n Detecting Python version... 
2.5
-n Detecting Python root... 
/System/Library/Frameworks/Python.framework/Versions/2.5
...
\endcode

Now, run the command
\code
 $ ./bjam variant=release threading=multi link=shared,static
\endcode
and wait a \e long time for everything to compile. At the end, you should see a message saying
\code
...updated 765 targets...
\endcode

Now, you are ready to install the library.
\code
 $ ./bjam variant=release threading=multi link=shared,static install
\endcode
After a considerably shorter wait, you should see
\code
...updated 7684 targets...
\endcode
again. Boost is now installed.

You can delete the boost_1_41_0 directory now if you wish. It might be worth 
saving for a little while until you have compiled HOOMD-blue and know everything 
is working so that you won't need to go through all the setup steps again. 


Before running ccmake or cmake-gui, set the following environment variables to the location where you installed boost:
\code
 $ export BOOST_ROOT=/home/myuser/software
 $ ccmake ../src  # or run cmake-gui
 ... continue with build instructions ...
\endcode

\section software_req_install_linux_compiler Compiler

These instructions test for the installation of gcc. Other C++ compilers can be used
if you wish, though compilations with CUDA enabled are only supported with gcc.

Test if g++ is installed.
\code 
 $ g++ --version
 $ g++ (GCC) 4.1.2 (Gentoo 4.1.2)
\endcode
Any version should do. If you get
\code
bash: g++: command not found
\endcode
then you will need to install gcc using your distributions package management system.


\section software_req_install_linux_cmake CMake

It is not very likely that your linux distribution includes CMake by default, 
but check anyways.
\code
 $ cmake --version
cmake version 2.6-patch 1
\endcode
Make sure the version is 2.6 or later. If you have an old version or get
\code
bash: cmake: command not found
\endcode
then you will need to upgrade/install CMake. Try your distributions package 
manager first. I.e. in Gentoo
\code
 $ emerge cmake
\endcode

If your distribution does not have a cmake package, 
then you can install it into your home directory by hand. First, download
cmake-2.6.1-Linux-i386.tar.gz from the Downloads section at http://www.cmake.org.
Unpack the tarball to any location you prefer: this example assumes you are installing it to the 
${HOME}/software
\code 
 $ mkdir ~/software
 $ mv cmake-2.6.1-Linux-i386.tar.gz ~/software/
 $ cd ~/software
 $ tar -xvzf cmake-2.6.1-Linux-i386.tar.gz
\endcode
Then you need to put the bin directory for cmake into your path. If you use bash for a shell you can do 
this by editing ~/.bashrc. Look for a line with PATH=... and add the cmake directory to the end separated 
by a colon. If you can't find the line, create it like so.
\code
PATH=$PATH:$HOME/software/cmake-2.6.1-Linux-i386/bin
export PATH
\endcode
Restart your bash shell (or open a new one) and try the version check above to test your installation.

\section software_req_install_linux_cuda CUDA

Even if you do not have the needed graphics hardware to run, you can still install the CUDA toolkit and 
run executables in emulation mode. The emulation is slow, but will allow you to develop and test
any changes you make that affect any of the *GPU classes. 

CUDA is quite new and it is not likely that there is a package available through your linux distribution. 
Gentoo is the only distribution currently offering a package:
\code
 $ emerge nvidia-cuda-toolkit
\endcode
will install the latest version of the CUDA toolkit and set all environment variables for you.

If your distribution doesn't come with a package, go to http://developer.nvidia.com/object/cuda.html  
and download the latest CUDA toolkit for you architecture and linux distribution. If your distribution isn't listed,
pick one that looks close, it will likely work. To install, simply go to the directory where you downloaded 
the toolkit and run:
\code
 $ bash NVIDIA_CUDA_Toolkit_2.0_rhel5_x86_64.run
\endcode
Note, this example lists a specific file: change the command to match the file that you downloaded. The
file is a self-unpacking and installing script. Just accept the default location if you have root access
to install, or install to ~/CUDA or anywhere else you please. Open up ~/.bashrc in your
favorite text editor and add the following line:
\code
export LD_LIBRARY_PATH=/usr/local/cuda/lib:$DYLD_LIBRARY_PATH
export PATH=$PATH:/usr/local/cuda/bin
\endcode
Change the paths on these lines if you did not install to the default location.

If you have a CUDA capable graphics card, you will also need the proper graphics driver version. See
the CUDA webpage linked to above for more information.

If you wish, you can download the CUDA SDK from the same website and compile the example files to
test your CUDA installation. The CUDA SDK is not required to compile or run HOOMD-blue, however.

\section software_req_install_linux_git Git

Git is used for version control. You need to install it if you are going to 
work on active development of HOOMD-blue, or if you just want to download and compile the latest and greatest
version.

First, see if you already have git installed.
\code
 $ git --version
git version 1.7.6.1
\endcode
If you get
\code
-bash: git: command not found
\endcode
then you will need to install it with your distrubition's package manager.

\section sec_build_linux_generic_compile Compile hoomd

Now that all of the prerequisite software is installed, you are ready to compile hoomd.

<b>Step 1: Get a copy of the source code</b>
There are two ways to get the source code for HOOMD-blue.  You can download it
(http://codeblue.umich.edu/hoomd-blue/download.html) or you can clone the git repository:
\code
 $ mkdir hoomd
 $ cd hoomd
 $ git clone https://codeblue.umich.edu/git/hoomd-blue code
\endcode
By default, the \em master branch will be checked out. This branch includes new features tested and
validated for the next feature release. Using the command <code>git checkout</code> \em branchname
you can access bugfixes applied to the previous tagged release (\em maint) or experimental features
still under development (\em next).

To access a tagged release, check out the tag (for example 0.11.0):
\code
 $ git checkout v0.11.0
\endcode

You can verify that the tagged release is exactly as it appeared to the developers when it was created if you
have GPG installed.
\code
 $ git cat-file blob 175bf6edfc8ac23c067df1d9bd7b5dd41982be3c | gpg --import
 $ git tag -v v0.11.0
\endcode

<b>Step 2: Compile and install hoomd with makefiles</b>
\code
 $ cd hoomd
 $ mkdir build
 $ cd build
 $ cmake ../code -DCMAKE_INSTALL_PREFIX=~/hoomd-install
 $ make install -j4
\endcode
The -j4 option to make allows it to compile many files in parallel. Set the number to the number of CPU cores in your
system plus two.

Now run
\code
 $ make check -j4
\endcode
to test your build

<b>Step 3: Setup your PATH</b>

Open \c ~/.bash_profile and add the following line to the end
\code
 export PATH=$PATH:${HOME}/hoomd-install/bin
\endcode
assuming that you set CMAKE_INSTALL_PREFIX to ~/hoomd-install above. If you prefer to install hoomd to a different
location, simply set CMAKE_INSTALL_PREFIX to the desired directory in the cmake command in step 2.

Either open a new terminal or
\code
 source ~/.bash_profile
\endcode
for the path setting to take effect.

<hr>
*/