INSTALL

# This file is part of HemeLB and is Copyright (C)
# the HemeLB team and/or their institutions, as detailed in the
# file AUTHORS. This software is provided under the terms of the
# license in the file LICENSE.

Instructions to configure, build, and install HemeLB.

HemeLB uses CMake (http://cmake.org/cmake/help/cmake-2-8-docs.html)
CMake works best with 'out of source' builds, these are recommended for HemeLB.
To build and install from any CMake file (CMakeLists.txt) do:
     > mkdir build
     > cd build
     > cmake <path to directory containing CMakeLists.txt> <options>
     > make
     > make install (optional, will copy executables into path.)
Common options include -DCMAKE_INSTALL_PREFIX to set the path to install to, if you do not have root.
CMake options can be configured with a GUI on many systems by using ccmake instead of cmake above.
     * When the ccmake gui appears:
     * press c to generate options, press e to move on from any messages displayed by cmake. 
     * edit any options displayed, 
     * press c to see if there are any new options resulting from the previous round of choices
     * repeat until you are happy with the options
     * press g to generate the build
     * move on to the make step as usual.

HemeLB provides three entry points to the CMake system. 
     * When building for use, the "Master build file" is easiest to use
     * When building for development, the individual "Code" and "dependencies" entry points provide the most control.
# Master build file
     * Resides at the top level of the HemeLB checkout
     * Optionally builds all HemeLB components
          (TODO - only builds hemelb and unittests at the moment, we should add steering client and setuptools to this)
     * Will download and build HemeLB dependencies as necessary
     * (Invokes Code and Dependencies builds.)
# Code build file
     * Resides in Code/ directory
     * Assumes all HemeLB dependencies are installed and accessible
     * Builds HemeLB and optionally the unit-tests
# Dependencies build file
     * Resides in dependencies/ directory
     * Builds dependencies for HemeLB and places them where the Code/ build will find them
     * Attempts to download from the internet
     * Will look for pre-downloaded tarballs of dependencies in dependencies/distributions (or choose where with ccmake)

--- Useful CMAKE options. --

These can be set with -D<OPTION>=<VALUE> or using CCMAKE
Global options:
	CMAKE_BUILD_TYPE: Can be None, Debug or Release. Release compiles with optimisation. Debug compiles with -g.
	TIXML_USE_STL: Should TinyXML use the C++ Standard template library?
Options for Code, or master build:
	CMAKE_INSTALL_PREFIX: Location where make install will install to.
	(CPPUNIT;PARMETIS;TINYXML)-(LIBRARY;INCLUDE): Locations where dependent libraries will be obtained
	USE_HEMELB_DEBUGGER: When HemeLB runs, should automatically start and attach to a system-appropriate debugger.
	USE_MULTIMACHINE: Use support for multi-level parallelism.
	HEMELB_BUILD_UNITTESTS: Should the unit-tests be built?
	HEMELB_LOG_LEVEL: Log level, can be debug, info, or warning.
	HEMELB_STEERING_LIB: Library for HemeLB steering, can be basic or none.
	
Options for dependencies, or master build:
	CPPUNIT_TARBALL, TINYXML_TARBALL, PARMETIS_TARBALL: URL to download or path to find dependency tarchive.
	(If cmake detects a local install of these, the TARBALL options will not be enabled.)