Skip to content

Commit 8e0922f

Browse files
zbeekmanzbeekman
committed
Add INSTALL text file & canonical CMake directions
 - Add INSTALL, with simple, canonical CMake installation instructions - INSTALL is geared towards seasoned developers, GCC developers, package maintainers and users with experience building and installing software from source with CMake - INSTALL has a very brief quick start summary at the top for the impatient - A highly condensed version of INSTALL is added to the top of INSTALL.md in an attempt to steer GCC devs and package maintainers in the right direction
1 parent 1014ece commit 8e0922f

File tree

2 files changed

+220
-10
lines changed

2 files changed

+220
-10
lines changed

‎INSTALL

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
OpenCoarrays developer/quickstart guide
2+
=======================================
3+
4+
This guide assumes that the reader is on a *nix operating system---Windows
5+
is *NOT* officially supported.
6+
7+
Please report any issues encountered or bugs to:
8+
9+
<https://github.com/sourceryinstitute/OpenCoarrays/issues>
10+
11+
12+
How to build OpenCoarrays for the very impatient
13+
------------------------------------------------
14+
15+
mkdir opencoarrays-build
16+
cd opencoarrays-build
17+
export FC=/path/to/gfortran
18+
export CC=/path/to/gcc
19+
cmake /path/to/OpenCoarrays/source \
20+
-DCMAKE_INSTALL_PREFIX=/path/to/desired/installation/location
21+
make
22+
make test # optional; verify build works
23+
make install
24+
25+
26+
Intended audience
27+
-----------------
28+
29+
* GCC developers
30+
* Package maintainers
31+
* Experienced users who are comfortable installing software from source (with
32+
CMake)
33+
34+
A markdown document (best viewed online) with more detailed instructions is
35+
available. It is locally available at ./INSTALL.md and viewable online at:
36+
37+
<https://github.com/sourceryinstitute/OpenCoarrays/blob/master/INSTALL.md>
38+
39+
40+
Prerequisite software
41+
---------------------
42+
43+
Before installing OpenCoarrays you will need:
44+
45+
* CMake 3.4 or newer
46+
* GFortran 6.1 or newer
47+
* A standard conforming C compiler, GCC 6.1 or newer is preferred, but clang
48+
and other alternatives should be fine too
49+
* An MPI 3 implementation. MPICH 3.2 or newer is recommended, but others,
50+
such as OpenMPI, should work as well.
51+
52+
CMake binary and source distributions can be obtained from:
53+
54+
<https://cmake.org/download/>
55+
56+
MPICH may be obtained from <http://www.mpich.org/downloads/>.
57+
58+
59+
Before you start
60+
----------------
61+
62+
Please ensure that your environment is configured so that:
63+
64+
* The MPI-3 implementation's `mpiexec` and compiler wrapper scripts
65+
are at the front of your `$PATH`. (Load the MPICH environment module, if
66+
applicable, to accomplish this.)
67+
* Your environment is setup to use the compilers you wish to build and use
68+
OpenCoarrays with. (LD_LIBRARY_PATH is set, if needed, etc.)
69+
70+
Also, you will need the OpenCoarrays source, which, you presumably already
71+
have if you are reading this. The latest stable OpenCoarrays release can be
72+
obtained at:
73+
74+
<https://github.com/sourceryinstitute/OpenCoarrays/releases/latest>
75+
76+
or the latest development version may be obtained from Github, either through
77+
the web UI or using git:
78+
79+
git clone https://github.com/sourceryinstitute/OpenCoarrays
80+
81+
82+
Configure, build and install OpenCoarrays
83+
-----------------------------------------
84+
85+
OpenCoarrays does *NOT* allow in source builds. Once you have obtained the
86+
source code, you must create a build directory. This may be a subdirectory of
87+
the top level source directory, or in a completely un-related location.
88+
89+
mkdir opencoarrays-build
90+
cd opencoarrays-build
91+
92+
Next tell CMake which C and Fortran compilers you want to use and configure
93+
the project with CMake. The Fortran compiler must be GFortran 6.1 or later.
94+
The OpenCoarrays build system uses system introspection and other means to
95+
ensure the version of the library built has interfaces matching the version
96+
of GFortran specified at compile time. No CMake configuration options should
97+
need tinkering with. A list of CMake variables that modify the OpenCoarrays
98+
build will be given at the end of this document.
99+
100+
export FC=/path/to/gfortran # You can use the version on your PATH
101+
export CC=/path/to/gcc
102+
103+
cmake /path/to/OpenCoarrays/source \
104+
-DCMAKE_INSTALL_PREFIX=/path/to/desired/install/location
105+
106+
Next build the library, wrapper scripts, and test programs, optionally run
107+
the tests and install OpenCoarrays:
108+
109+
make -j 8 # Parallel builds are supported
110+
make test # invoke ctest
111+
make install
112+
113+
114+
Configure options
115+
-----------------
116+
117+
The OpenCoarrays build system attempts to set the best possible defailt
118+
settings for your Fortran compiler and MPI implementation through intro-
119+
spection. However, some bugs or use cases may warrant tweaking the config-
120+
uration. Each of the following options may be set using the `-D` flag to
121+
cmake or using the CMake gui interfaces, ccmake or cmake-gui. e.g.,
122+
123+
cmake /path/to/source -DVAR=VALUE
124+
125+
Basic configure options:
126+
127+
CMAKE_INSTALL_PREFIX
128+
Tell cmake where to install OpenCoarrays. Default=/usr/local
129+
Example: cmake .. -DCMAKE_INSTALL_PREFIX=/opt/OpenCoarrays/1.9.1
130+
131+
CMAKE_BUILD_TYPE
132+
Specify the build type. Default value: Release
133+
Options to pick from are:
134+
* Debug
135+
* Release
136+
* MinSizeRel
137+
* RelWithDebInfo
138+
* CodeCoverage
139+
Example: cmake .. -DCMAKE_BUILD_TYPE=Debug
140+
141+
CAF_ENABLE_FAILED_IMAGES
142+
Enable failed image support. Defaults to TRUE if experimental fault
143+
tolerance features are detected to be present in the MPI
144+
implementation. FALSE/unavailable if no MPI support is present
145+
Example: cmake .. -DCAF_ENABLE_FAILED_IMAGES=FALSE
146+
147+
CAF_EXPOSE_INIT_FINALIZE
148+
Expose caf_init and caf_finalize in the OpenCoarrays extensions
149+
module. This helps facilitate hybrid MPI-CAF programming.
150+
Default=FALSE
151+
Example: cmake .. -DCAF_EXPOSE_INIT_FINALIZE=TRUE
152+
153+
CAF_RUN_DEVELOPER_TESTS
154+
Run tests intended for developers that trigger known failures due to
155+
bugs, regressions and other issues. Default=FALSE unless user sets
156+
the environment variable OPENCOARRAYS_DEVELOPER=TRUE
157+
Example: cmake .. -DCAF_RUN_DEVELOPER_TESTS=TRUE
158+
159+
For a look at all of the possible CMake settings, many/most of which are
160+
default CMake options, please run `ccmake /path/to/source` or
161+
`cmake-gui /path/to/source`.

‎INSTALL.md

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
Download this file as a PDF document
1414
[here][INSTALL.pdf].
1515

16+
* [Developer Build and Install]
1617
* [End-User Installation]
1718
* [macOS]
1819
* [Windows]
@@ -22,17 +23,63 @@ Download this file as a PDF document
2223
* [Installation Script]
2324
* [Advanced Installation from Source]
2425
* [Prerequisites]
25-
* [CMake scripts]
26+
* [CMake]
2627
* [Make]
2728

29+
## Developer Build and Install ##
30+
31+
If you are a GCC developer, a package maintainer building OpenCoarrays
32+
for distribution, or an advanced user who is comfortable building
33+
software from source (using cmake), then we recommend installing
34+
OpenCoarrays directly via CMake. If you do not fit into one of these
35+
categories, we encourage you to skip ahead to review installation
36+
options via Linux or MacOS package management software, or the
37+
[`install.sh`] script. The text below is a condensed version of the
38+
content available in [`INSTALL`]: plain text instructions for installing
39+
OpenCoarrays in a canonical CMake way.
40+
41+
Prerequites for direct CMake installation:
42+
43+
* An MPI 3 implementation (MPICH is preferred, OpenMPI works too)
44+
* A recent version of GCC with GFortran version 6.1 or newer
45+
* CMake version 3.4 or newer
46+
47+
After obtaining the OpenCoarrays source (from git or our [latest release])
48+
the following commands to build and install OpenCoarrays from source
49+
using CMake:
50+
51+
```bash
52+
mkdir opencoarrays-build
53+
cd opencoarrays-build
54+
export FC=/path/to/gfortran
55+
export CC=/path/to/gcc
56+
cmake /path/to/OpenCoarrays/source \
57+
-DCMAKE_INSTALL_PREFIX=/path/to/desired/installation/location
58+
make
59+
make test # optional; verify build works
60+
make install
61+
```
62+
63+
If you have either of the CMake gui tools installed, `ccmake` or
64+
`cmake-gui` you may explore different configuration options and/or try
65+
to locate/change which MPI version is found by repeating the steps
66+
above and simply replacing `cmake` with `ccmake` or `cmake-gui`.
67+
68+
Please keep in mind that CMake cache variables are sticky and, once
69+
set, can only be changed by using `ccmake`, `cmake-gui`, or explicitly
70+
setting them on the command line: `cmake ../path/to/src -DVAR=VALUE`
71+
If the wrong compiler or MPI implementation is being used and you
72+
cannot determine why, you can try deleting the entire build directly
73+
and re-running CMake.
74+
2875
## End-User Installation ##
2976

3077
Most users will find it easiest and fastest to use package management
3178
software to install OpenCoarrays. Package management options for
3279
macOS, Windows, and Linux are described first below. Also described
3380
below are options for installing via the Sourcery Institute virtual
34-
machine or via the bash and/or CMake scripts included that are in the
35-
OpenCoarrays source.
81+
machine or via the bash scripts included that are in the OpenCoarrays
82+
source.
3683

3784
[top]
3885

@@ -69,7 +116,7 @@ OpenCoarrays source.
69116

70117
### Windows ###
71118

72-
Windows users may run the [install.sh] script inside the Windows Subsystem
119+
Windows users may run the [`install.sh`] script inside the Windows Subsystem
73120
for Linux ([WSL]). The script uses Ubuntu's [APT] package manager to build
74121
[GCC] 5.4.0, [CMake], and [MPICH]. Windows users who desire a newer version
75122
of GCC are welcome to submit a request via our [Issues] page and suggest a
@@ -227,7 +274,7 @@ of flags. Each flag also has a single-character version not shown here.
227274
--with-c <path-to-gcc-bin>/gcc
228275
```
229276

230-
Without the latter arguments, [install.sh] will attempt to install the
277+
Without the latter arguments, [`install.sh`] will attempt to install the
231278
default GCC version even if a newer version is available. This happens
232279
to protect users from instability in cases when known one or more
233280
known regressions exist in the newer compiler.
@@ -312,7 +359,7 @@ of flags. Each flag also has a single-character version not shown here.
312359

313360
### Prerequisites ###
314361

315-
Package managers and the [install.sh] attempt to handle the installation
362+
Package managers and the [`install.sh`] attempt to handle the installation
316363
of all OpenCoarrays prerequisites automatically. Installing with CMake
317364
or the provided, static Makefile burdens the person installing with the
318365
need to ensure that all prerequisites have been built and are in the
@@ -334,9 +381,9 @@ opencoarrays
334381

335382
[top]
336383

337-
### CMake scripts ###
384+
### CMake ###
338385

339-
On most platforms, the [install.sh] script ultimately invokes [CMake] after performing
386+
On most platforms, the [`install.sh`] script ultimately invokes [CMake] after performing
340387
numerous checks, customizations, and installations of any missing prerequisites.
341388
Advanced users who prefer to invoke CMake directly may do so as described here.
342389
CMake is a cross-platform Makefile generator that includes the testing tool CTest.
@@ -434,6 +481,7 @@ file.
434481
[Internal document links]: #
435482

436483
[top]: #top
484+
[Developer Build and Install]: #developer-build-and-install
437485
[End-User Installation]: #end-user-installation
438486
[macOS]: #macos
439487
[Windows]: #windows
@@ -444,12 +492,13 @@ file.
444492

445493
[Advanced Installation from Source]: #advanced-installation-from-source
446494
[Prerequisites]: #prerequisites
447-
[CMake scripts]: #cmake-scripts
495+
[CMake]: #cmake
448496
[Make]: #make
449497

450498
[Links to source]: #
451499

452-
[install.sh]: ./install.sh
500+
[`install.sh`]: ./install.sh
501+
[`INSTALL`]: ./INSTALL
453502

454503
[URLs]: #
455504

0 commit comments

Comments
 (0)