Merge pull request #149 from memmett/feature/build-docs

Update install instructions. LGTM.

Author: torbjoernk

doc/source/installing.md

@@ -2,34 +2,63 @@
 
 ## Prerequesites
 
-* A recent C++ compiler that supports (most of) the C++11 standard.
-  This either implies at least GCC 4.7 (we recommend 4.8 or later) or Clang 3.2 (we recommend 3.3 or later).
+If you use [CMake] to compile, most of the prerequesites are downloaded automatically if they aren't
+already found on your system.
 
-* The [Boost](https://boost.org/) libraries at least of version 1.53.0.
-  Especially `boost::program_options` is required.
+### Required
 
-* The [CMake] build tool (at least version 2.8).
+* A recent C++ compiler that supports (most of) the C++11 standard.  This implies either: GCC 4.7
+  (we recommend 4.8 or later) or Clang 3.2 (we recommend 3.3 or later).
 
-* The [Eigen3] library is required for everything using the \em PFASST++ library.
-  It will be automatically downloaded if it is not found on the system.
+* The [Boost] `boost::program_options` library (at least version 1.53.0).  The [Boost]
+  multiprecision component may also be of interest to \em PFASST++ users.
 
-* The [FFTW3] library is required for (some) of the examples.
-  It will be automatically downloaded and built as well if it is not found on the system.
+* The [Eigen3] library.
 
-* The [Google Testing] and [Mocking Framework] are required for the unit tests, and are automatically downloaded and 
-  built.
+### Optional
+
+* The [CMake] build tool (at least version 2.8).  This is especially useful for developers.
+
+* The [FFTW3] library is required for some of the examples.
+
+* The [Google Testing] and [Google Mocking] are required for the unit tests.
+
+* An MPI implementation.
+
+### Using [HashDist] to obtain prerequesites
+
+The [HashDist] environment management system provides an easy, robust, and version controlled way
+for our developers (and users) to download and install all prerequesites *locally* (ie, you don't
+need special privileges on your system to use [HashDist], and it won't modify your system).
+
+To use [HashDist]
+
+1. Install [HashDist]
+
+        git clone [email protected]:hashdist/hashdist.git
+        export PATH=$PWD/hashdist/bin:$PATH
+
+2. Install prerequesites
+
+        cd PFASST
+        hit build -v tools/hashdist/pfasst-stack.debian.yaml
+        mv pfasst-stack.debian stack
+
+This may take a while (ie, do this before going for lunch) the first time through.  However, once
+complete, subsequent builds (using [CMake] or otherwise) will bypass prerequesite installation, even
+if you change [CMake] build options or start a fresh out-of-source build directory.
 
 
 ## Obtaining the Sources
 
-Either use _Git_ to clone the repository (https://github.com/Parallel-in-Time/PFASST.git) or download the latest 
-release from [GitHub][github_releases].
+Use _Git_ to clone the repository (https://github.com/Parallel-in-Time/PFASST.git) or download the
+latest release from [GitHub][github_releases].
 
 
-## Building
+## Building with CMake
 
-1. Create a directory for out-of-source builds (usually, people are creative and name it `build`) in the source tree 
-   (or elsewhere).
+1. Create a directory for out-of-source builds (usually, people are creative and name it `build`) in
+   the source tree (or elsewhere).
 
 2. Decide on what and how you want to build:
 
@@ -58,7 +87,7 @@ release from [GitHub][github_releases].
 
    * __Test Suite__
 
-     * Deactivate building of the test suite by passing `-Dpfasst_BUILD_TESTS=OFF` to the _CMake_ command line (not 
+     * Deactivate building of the test suite by passing `-Dpfasst_BUILD_TESTS=OFF` to the _CMake_ command line (not
        recommended).
 
    * __Examples__
@@ -81,7 +110,7 @@ release from [GitHub][github_releases].
      * In case you also want to install the compiled example programs on your system, specify
        `-Dpfasst_INSTALL_EXAMPLES=ON`.
 
-   * For example, to build a release version with _Clang_ on a Linux system without the examples, the call to 
+   * For example, to build a release version with _Clang_ on a Linux system without the examples, the call to
      _CMake_ looks like:
 
          cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -Dpfasst_BUILD_EXAMPLES=OFF ..
@@ -99,18 +128,25 @@ release from [GitHub][github_releases].
 
        make test
 
-   In case any of the tests do not pass, please [open an issue on GitHub][github_new_issue] and provide the full log of 
+   In case any of the tests do not pass, please [open an issue on GitHub][github_new_issue] and provide the full log of
    your _CMake_ and _make_ invocations.
 
 5. (optional) Install \em PFASST++ headers (and compiled examples if specified so):
 
        make install
 
+## Building with vanilla make
+
+A sample `Makefile` is included in the `advection_diffusion` example.  This may be of particular
+interested to advanced users wishing to incorporate \rm PFASST++ into their existing code bases.
+
 
+[Boost]: https://boost.org/
 [CMake]: http://cmake.org/
 [Eigen3]: http://eigen.tuxfamily.org/
 [Google Testing]: https://code.google.com/p/googletest/
-[Mocking Framework]: https://code.google.com/p/googlemock/
+[Google Mocking]: https://code.google.com/p/googlemock/
 [FFTW3]: http://fftw.org/
 [github_releases]: https://github.com/Parallel-in-Time/PFASST/releases
 [github_new_issue]: https://github.com/Parallel-in-Time/PFASST/issues/new
+[HashDist]: http://hashdist.readthedocs.org/en/latest/