Download this file as a PDF document here.
- Developer Build and Install
- End-User Installation
- Advanced Installation from Source
Developer Build and Install
If you are a GCC developer, a package maintainer building OpenCoarrays
for distribution, or an advanced user who is comfortable building
software from source (using cmake), then we recommend installing
OpenCoarrays directly via CMake. If you do not fit into one of these
categories, we encourage you to skip ahead to review installation
options via Linux or MacOS package management software, or the
install.sh script. The text below is a condensed version of the
content available in
INSTALL: plain text instructions for installing
OpenCoarrays in a canonical CMake way.
Prerequites for direct CMake installation:
- An MPI 3 implementation (MPICH is preferred, OpenMPI works too)
- A recent version of GCC with GFortran version 6.1 or newer
- CMake version 3.4 or newer
After obtaining the OpenCoarrays source (from git or our latest release) the following commands to build and install OpenCoarrays from source using CMake:
mkdir opencoarrays-build cd opencoarrays-build export FC=/path/to/gfortran export CC=/path/to/gcc cmake /path/to/OpenCoarrays/source \ -DCMAKE_INSTALL_PREFIX=/path/to/desired/installation/location make make test # optional; verify build works make install
If you have either of the CMake gui tools installed,
cmake-gui you may explore different configuration options and/or try
to locate/change which MPI version is found by repeating the steps
above and simply replacing
Please keep in mind that CMake cache variables are sticky and, once
set, can only be changed by using
cmake-gui, or explicitly
setting them on the command line:
cmake ../path/to/src -DVAR=VALUE
If the wrong compiler or MPI implementation is being used and you
cannot determine why, you can try deleting the entire build directly
and re-running CMake.
Most users will find it easiest and fastest to use package management software to install OpenCoarrays. Package management options for macOS, Windows, and Linux are described first below. Also described below are options for installing via the Sourcery Institute virtual machine or via the bash scripts included that are in the OpenCoarrays source.
This is the recommend OpenCoarrays installation method on macOS. Basic Homebrew installation steps:
brew update brew install opencoarrays
OpenCoarrays also ships with a
Brewfilethat will make it easier to install opencoarrays using MPICH built with the GNU Compiler Collection (GCC). To install using the
Brewfilewith MPICH wrapping GCC, follow these steps:
brew tap homebrew/bundle brew update brew bundle
An unmaintained OpenCoarrays Portfile exists for the MacPorts package manager. Although the current OpenCoarrays contributors have no plans to update the portfile, new contributors are welcome to asssume the port maintainer role and to submit a pull request to update this INSTALL.md file.
Windows users may run the
install.sh script inside the Windows Subsystem
for Linux (WSL). The script uses Ubuntu's APT package manager to build
GCC 5.4.0, CMake, and MPICH. Windows users who desire a newer version
of GCC are welcome to submit a request via our Issues page and suggest a
method for updating. Previously attempted upgrade methods are described in
the discussion thread starting with commit comment 20539810.
Access OpenCoarrays on Linux via any of the following package managers or pre-installed copies:
- The linuxbrew package manager installs OpenCoarrays on all Linux distributions.
- Debian-based distributions such as Ubuntu provide an "open-coarrays" APT package.
- Arch Linux provides an aur package.
- An HPCLinux installation script is in the developer-scripts subdirectory (available via git clone only).
- EasyBuild can install OpenCoarrays on Linux distributions
- Spack, a multiplatform package manager, can also install OpenCoarrays on Linux distributions
linuxbrew does not require
sudo privileges and will generally
provide the most up-to-date OpenCoarrays release because linxubrew
pulls directly from macOS homebrew, which updates automatically.
With EasyBuild, the following bash commands install OpenCoarrays:
# Search available specification files (also known as easyconfigs) for OpenCoarrays eb --search OpenCoarrays # Automatically download prerequisites (with the --robot flag) and install OpenCoarrays # with the desired easyconfig, e.g., OpenCoarrays-1.9.0-gompi-2017a.eb eb OpenCoarrays-1.9.0-gompi-2017a.eb --robot
Once installed, use OpenCoarrays by loading the newly created environment
module load OpenCoarrays/1.9.0-gompi-2017a
With Spack, the following commands install OpenCoarrays in a bash shell:
# Check build information for OpenCoarrays in the default specification file spack spec opencoarrays # To automatically download prerequisites and install OpenCoarrays with the default # specification. # (Note: In addition to its own prerequisites, Spack requires gfortran compiler # to be installed to compile OpenMPI) spack install opencoarrays # Or, To install with customisations (e.g., to install OpenCoarrays [version 1.9.0] # with MPICH [version default] and GCC [version 7.1.0]). spack install firstname.lastname@example.org ^mpich %email@example.com
In the previous example, it was assumed that GCC [version 7.1.0] is already installed, and is available as a compiler to Spack. Otherwise, add a new compiler to Spack. Once installed, OpenCoarrays can be used by loading the environment modules with Spack, e.g.
spack module loads --dependencies opencoarrays
Use the OpenCoarrays FreeBSD, Port to install OpenCoarrays by executing the following commands as root:
pkg install opencoarrays
For more information, please review the FreeBSD ports/packages installation information.
Users of macOS, Windows, or Linux have the option to use OpenCoarrays by installing the Lubuntu Linux virtual machine from the Sourcery Institute Store. The virtual machine boots inside the open-source VirtualBox virtualization package. In addition to containing GCC, MPICH, and OpenCoarrays, the virtual machine contains dozens of other open-source software packages that support modern Fortran software development. See the download and installation instructions for a partial list of the included packages.
If the above package management or virtualization options are infeasible or unavailable, Linux, macOS, and WSL users may also install OpenCoarrays by downloading and uncompressing our latest release and running our installation script in the top-level OpenCoarrays source directory (see above for the corresponding Windows script):
tar xvzf OpenCoarrays-x.y.z.tar.gz cd OpenCoarrays-x.y.z ./install.sh
x.y.z should be replaced with the appropriate version numbers.
A complete installation should result in the creation of the following
directories inside the installation path (.e.g, inside
build in the
bin: contains the compiler wrapper (
caf) and program launcher (
mod: contains the
opencoarrays.modmodule file for use with non-OpenCoarrays-aware compilers
lib: contains the
libcaf_mpi.astatic library to which codes link for CAF support
Example script invocations
./install.sh --help or
./install.sh -h to see a list of flags
that can be passed to the installer. Below are examples of useful combinations
of flags. Each flag also has a single-character version not shown here.
Install after building any missing prerequisites -- all source, build, and installation files will be inside the OpenCoarrays source tree under prerequisites/installations:
Install non-interactively by assuming a "yes" answer to all questions
Install with the specified compilers, overriding the default compilers:
./install.sh --with-fortran <path-to-gcc-bin>/gfortran \ --with-cxx <path-to-gcc-bin>/g++ \ --with-c <path-to-gcc-bin>/gcc
Without the latter arguments,
install.shwill attempt to install the default GCC version even if a newer version is available. This happens to protect users from instability in cases when known one or more known regressions exist in the newer compiler.
Install only a specific prerequisite package (the default version):
./install.sh --package mpich
Install a specific version of a prerequisite:
./install.sh --package cmake --install-version 3.7.0
Download a prerequisite package (e.g., gcc/gfortran/g++ below) but don't build or install it:
./install.sh --only-download gcc
Print the default URL, version, or download mechanism that the script will use for a given prerequisite package (e.g., mpich below) on this system:
./install.sh --print-url mpich ./install.sh --print-version mpich ./install.sh --print-downloader mpich
Install a prerelease branch (e.g., trunk below) of the GCC repository:
./install.sh --package gcc --install-branch trunk
Install to a specific location:
./install.sh --install-prefix /opt/gnu/
If the path provided in the install prefix requires sudo privileges, the user will be prompted for a password after the package download and build complete and just before installing to the specified path.
Install a prerequisite package from a non-default URL:
./install.sh --package gcc \ --from-url https://github.com/sourceryinstitute/gcc/archive/teams-20170919.tar.gz \ --install-version teams-20170919
The latter command will install the Sourcery Institute GCC fork that provides experimental support for the Fortran 2015 teams feature.
Speed up a GCC build at a higher risk of a faild build:
./install.sh --package gcc --disable-bootstrap
If the latter command works, it could reduce GCC's build time from hours down to minutes.
Speed up a GCC build with multithreading at a risk of a failed build:
./install.sh --package gcc --num-threads 4
The latter command sometimes fails if the GCC build system has not fully specified dependencies between source files.
Advanced Installation from Source
Package managers and the
install.sh attempt to handle the installation
of all OpenCoarrays prerequisites automatically. Installing with CMake
or the provided, static Makefile burdens the person installing with the
need to ensure that all prerequisites have been built and are in the
expected or specified locations prior to building OpenCoarrays. The
prerquisite package/version dependency tree is as follows:
opencoarrays ├── cmake-3.4.0 └── mpich-3.2 └── gcc-6.1.0 ├── flex-2.6.0 │ └── bison-3.0.4 │ └── m4-1.4.17 ├── gmp ├── mpc └── mpfr
On most platforms, the
install.sh script ultimately invokes CMake after
performing numerous checks, customizations, and installations of any missing
prerequisites. Users wishing to install OpenCoarrays directly with CMake should
have a look at the documentation in the [
./INSTALL] file if they encounter
issues or need further guidance. A brief summary is also given at the top of
this document here.
Unlike the Makefiles that CMake generates automatically for the chosen
platform, static Makefiles require a great deal more maintenance and are
less portable. Also, the static Makefiles provided in src lack several
several important capabilities. In particular, they will not build the tests;
they will not generate the
caf compiler wrapper that ensures correct linking
cafrun program launcher that ensures support for advanced features such
as Fortran 2015 failed images; they will not build the opencoarrays module
that can be used to provide some Fortran 2015 features with non-Fortran-2015
compilers; nor do the static Makefiles provide a
make install option so you
will need to manually move the resultant library from the build location to your
chosen installation location.
If none of the installation methods mentioned higher in this document are work on your platform and if CMake is unavailable, build and install the OpenCoarrays parallel runtime library as follows:
tar xvzf opencoarrays.tar.gz cd opencoarray/src make mv mpi/libcaf_mpi.a <insert-install-path>
replacing the angular-bracketed text with your desired install path.
For the above steps to succeed, you might need to edit the make.inc
file to match your system settings. For example, you might need to
-Werror option from the compiler flags or name a
different compiler. In order to activate efficient strided-array
transfer support, uncomment the
-DSTRIDED flag inside the make.inc