Skip to content

Commit 73d8c40

Browse files
memmettmemmett
committed
Merge pull request #120 from torbjoernk/feature/docu-fixes
docu: fix and extend installing instructions
2 parents 70b8832 + 38c56db commit 73d8c40

File tree

1 file changed

+80
-23
lines changed

1 file changed

+80
-23
lines changed

‎doc/source/installing.md‎

Lines changed: 80 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,57 +3,114 @@
33
## Prerequesites
44

55
* A recent C++ compiler that supports (most of) the C++11 standard.
6-
* The [CMake](http://cmake.org/) build tool.
6+
This either implies at least GCC 4.7 (we recommend 4.8 or later) or Clang 3.2 (we recommend 3.3 or later).
7+
78
* The [Boost](https://boost.org/) libraries at least of version 1.53.0.
89
Especially `boost::program_options` is required.
910

11+
* The [CMake] build tool (at least version 2.8).
12+
13+
* The [Eigen3] library is required for everything using the \em PFASST++ library.
14+
It will be automatically downloaded if it is not found on the system.
15+
16+
* The [FFTW3] library is required for (some) of the examples.
17+
It will be automatically downloaded and built as well if it is not found on the system.
18+
19+
* The [Google Testing] and [Mocking Framework] are required for the unit tests, and are automatically downloaded and
20+
built.
21+
1022

1123
## Obtaining the Sources
1224

13-
Just use _Git_ to clone the repository.
25+
Either use _Git_ to clone the repository (https://github.com/Parallel-in-Time/PFASST.git) or download the latest
26+
release from [GitHub][github_releases].
1427

1528

1629
## Building
1730

18-
1. Create a directory for out-of-source builds (usually, people are
19-
creative and name it `build`) in the source tree (or elsewhere).
31+
1. Create a directory for out-of-source builds (usually, people are creative and name it `build`) in the source tree
32+
(or elsewhere).
33+
34+
2. Decide on what and how you want to build:
35+
36+
* __General__
37+
38+
* By default everything gets built, i.e. tests and examples.
39+
40+
* Use `-DCMAKE_BUILD_TYPE=<VALUE>` to specify general compiler flags.
41+
42+
| `CMAKE_BUILD_TYPE` | implied compiler flags |
43+
|--------------------|------------------------|
44+
| `Debug` | `-g` |
45+
| `Release` | `-O3 -DNDEBUG` |
46+
| `RelWithDebInfo` | `-O2 -g -DNDEBUG` |
47+
| `MinSizeRel` | `-Os -DNDEBUG` |
48+
49+
* To enable profiling support, you need to specify `-Dpfasst_WITH_GCC_PROF=ON` and have the GNU compiler selected.
50+
When compiling with _Clang_ this option is obsolete as profiling with _Clang_ is not supported.
2051

21-
2. Decide on what you want to build:
52+
* Users on Linux systems with the _Clang_ compiler and a working installation of LLVM's \em libc++ library may
53+
want to activate the usage of that by specifying `-Dpfasst_DISABLE_LIBCXX=OFF`.
2254

23-
* By default everything gets built, i.e. tests and examples.
55+
* __MPI__
2456

25-
* To deactivate the tests, pass `-Dpfasst_BUILD_TESTS=OFF` to the _CMake_ command line.
57+
* To enable MPI, please specify `-Dpfasst_WITH_MPI=ON`.
2658

27-
* To deactivate the examples, pass `-Dpfasst_BUILD_EXAMPLES=OFF` to the _CMake_ command line.
59+
* __Test Suite__
2860

29-
* To enable profiling support, you need to specify `-Dpfasst_WITH_GCC_PROF` and have the GNU
30-
compiler selected.
61+
* Deactivate building of the test suite by passing `-Dpfasst_BUILD_TESTS=OFF` to the _CMake_ command line (not
62+
recommended).
3163

32-
* If you are not on a _Darvin_ system (i.e. MacOS, OSX, ...) and you are using _Clang_ as the
33-
compiler, you want to deactivate the use of LLVM's libc++ by passing
34-
`-Dpfasst_DISABLE_LIBCXX=ON` to the _CMake_ command line. (this is the default)
64+
* __Examples__
3565

36-
* For example, to build with _Clang_ on a Linux system without the examples, the call to
66+
* Deactivate building of the example programms by passing `-Dpfasst_BUILD_EXAMPLES=OFF` to the _CMake_ command
67+
line.
68+
69+
* Add compiled example programs to the `install` target by passing `-Dpfasst_INSTALL_EXAMPLES=ON` to the _CMake_
70+
command line (by default, they will not get installed).
71+
72+
* __Installing (optional)__
73+
74+
* Use `-DCMAKE_INSTALL_PREFIX=<PREFIX>` to specify the prefix for installing the headers and optional compiled
75+
examples.
76+
77+
By default, `<PREFIX>` is `/usr/local` on Linux systems.
78+
79+
The headers will go into `<PREFIX>/include` and compiled binaries in `<PREFIX>/bin`.
80+
81+
* In case you also want to install the compiled example programs on your system, specify
82+
`-Dpfasst_INSTALL_EXAMPLES=ON`.
83+
84+
* For example, to build a release version with _Clang_ on a Linux system without the examples, the call to
3785
_CMake_ looks like:
3886

39-
cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ [-Dpfasst_DISABLE_LIBCXX=ON] -Dpfasst_BUILD_EXAMPLES=OFF ..
87+
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -Dpfasst_BUILD_EXAMPLES=OFF ..
88+
89+
* A full debug build on a Linux system with GCC and the desire to install everything to `/home/<USER>`, call _CMake_
90+
with:
4091

41-
The [Google Testing] and [Mocking Framework] are required for the unit tests, and are
42-
automatically downloaded and built.
92+
cmake -DCMAKE_BUILD_TYPE=Debug -Dpfasst_WITH_GCC_PROF=ON -Dpfasst_INSTALL_EXAMPLES=ON -DCMAKE_INSTALL_PREFIX=$HOME ..
4393

44-
The [FFTW3] library is required for (some) of the examples. It will be automatically downloaded
45-
and built as well if it is not found on the system.
94+
3. Compile:
4695

47-
3. Run the unit tests (if unit tests have been built):
96+
make
97+
98+
4. Run the unit tests (if unit tests have been built):
4899

49100
make test
50101

51-
4. Run the examples (if they have been built):
102+
In case any of the tests do not pass, please [open an issue on GitHub][github_new_issue] and provide the full log of
103+
your _CMake_ and _make_ invocations.
104+
105+
5. (optional) Install \em PFASST++ headers (and compiled examples if specified so):
52106

53-
make run_example_all
107+
make install
54108

55-
Or go to `./dist/examples` and look for the exetuable you want to run.
56109

110+
[CMake]: http://cmake.org/
111+
[Eigen3]: http://eigen.tuxfamily.org/
57112
[Google Testing]: https://code.google.com/p/googletest/
58113
[Mocking Framework]: https://code.google.com/p/googlemock/
59114
[FFTW3]: http://fftw.org/
115+
[github_releases]: https://github.com/Parallel-in-Time/PFASST/releases
116+
[github_new_issue]: https://github.com/Parallel-in-Time/PFASST/issues/new

0 commit comments

Comments
 (0)