5db475f Jan 25, 2018
@rouson @zbeekman @anujsharmax
519 lines (405 sloc) 18.9 KB

Installing OpenCoarrays

GitHub release Github All Releases Download as PDF

Download this file as a PDF document here.

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 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 \
make test # optional; verify build works
make install

If you have either of the CMake gui tools installed, ccmake or 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 cmake with ccmake or cmake-gui.

Please keep in mind that CMake cache variables are sticky and, once set, can only be changed by using ccmake, 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.

End-User Installation

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.



  • Homebrew:
    This is the recommend OpenCoarrays installation method on macOS. Basic Homebrew installation steps:

    brew update
    brew install opencoarrays

    OpenCoarrays also ships with a Brewfile that will make it easier to install opencoarrays using MPICH built with the GNU Compiler Collection (GCC). To install using the Brewfile with MPICH wrapping GCC, follow these steps:

    brew tap homebrew/bundle
    brew update
    brew bundle
  • MacPorts:
    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 file.



Windows users may run the 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 OpenCoarrays/1.9.0-gompi-2017a:

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 opencoarrays@1.9.0 ^mpich %gcc@7.1.0

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.


Virtual machine

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.


Installation Script

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

where 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 above example):

  • bin: contains the compiler wrapper (caf) and program launcher (cafun).
  • mod: contains the opencoarrays.mod module file for use with non-OpenCoarrays-aware compilers
  • lib: contains the libcaf_mpi.a static library to which codes link for CAF support

Example script invocations

Execute ./ --help or ./ -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.

  1. Install after building any missing prerequisites -- all source, build, and installation files will be inside the OpenCoarrays source tree under prerequisites/installations:

  2. Install non-interactively by assuming a "yes" answer to all questions

    ./ --yes-to-all
  3. Install with the specified compilers, overriding the default compilers:

    ./ --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, will 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.

  4. Install only a specific prerequisite package (the default version):

    ./ --package mpich
  5. Install a specific version of a prerequisite:

    ./ --package cmake --install-version 3.7.0
  6. Download a prerequisite package (e.g., gcc/gfortran/g++ below) but don't build or install it:

    ./ --only-download gcc
  7. 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:

    ./ --print-url mpich
    ./ --print-version mpich
    ./ --print-downloader mpich
  8. Install a prerelease branch (e.g., trunk below) of the GCC repository:

    ./ --package gcc --install-branch trunk
  9. Install to a specific location:

    ./ --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.

  10. Install a prerequisite package from a non-default URL:

    ./ --package gcc \
      --from-url \
      --install-version teams-20170919

    The latter command will install the Sourcery Institute GCC fork that provides experimental support for the Fortran 2015 teams feature.

  11. Speed up a GCC build at a higher risk of a faild build:

    ./ --package gcc --disable-bootstrap

    If the latter command works, it could reduce GCC's build time from hours down to minutes.

  12. Speed up a GCC build with multithreading at a risk of a failed build:

    ./ --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 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:

├── 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 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 and 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
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 file to match your system settings. For example, you might need to remove the -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 file.


GitHub forks GitHub stars GitHub watchers Twitter URL