Download this file as a PDF document here.
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 and/or CMake 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 opencoarraysOpenCoarrays 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 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 --robotOnce installed, use OpenCoarrays by loading the newly created environment
module OpenCoarrays/1.9.0-gompi-2017a:
module load OpenCoarrays/1.9.0-gompi-2017aWith 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 [email protected] ^mpich %[email protected]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 opencoarraysUse the OpenCoarrays FreeBSD, Port to install OpenCoarrays by executing the following commands as root:
pkg install opencoarraysFor 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.shwhere 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 theopencoarrays.modmodule file for use with non-OpenCoarrays-aware compilerslib: contains thelibcaf_mpi.astatic library to which codes link for CAF support
Execute ./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.sh- Install non-interactively by assuming a "yes" answer to all questions
$ ./install.sh --yes-to-all- 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.sh 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.
- 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-20170919The 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-bootstrapIf 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 4The latter command sometimes fails if the GCC build system has not fully specified dependencies between source files.
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.
Advanced users who prefer to invoke CMake directly may do so as described here.
CMake is a cross-platform Makefile generator that includes the testing tool CTest.
To avoid cluttering or clobbering the source tree, our CMake setup requires that
your build directory be any directory other than the top-level OpenCoarays
source directory. In a bash shell, the following steps should build OpenCoarrays,
build the tests, run the tests, and report the test results:
tar xvzf opencoarrays.tar.gz
cd opencoarrays
mkdir opencoarrays-build
cd opencoarrays-build
CC=gcc FC=gfortran cmake .. -DCMAKE_INSTALL_PREFIX=${HOME}/packages/
make
ctest
make installwhere the the first part of the cmake line sets the CC and FC
environment variables and the final part of the same line defines the
installation path as the packages directory in the current user's
$HOME directory. Please report any test failures via the
OpenCoarrays Issues page. Please note that you need a recent
GCC/GFortran, and a recent MPI-3 implementation. If CMake is having
trouble finding the MPI implementation, or is finding the wrong MPI
implementation, you can try setting the MPI_HOME environment
variable to point to the installation you wish to use. If that fails,
you can also try passing the
-DMPI_Fortran_COMPILER=/path/to/mpi/fortran/wrapper/script and
-DMP_C_COMPILER=/path/to/mpi/c/wrapper/script options to CMake.
Advanced options (most users should not use these):
-DMPI_HOME=/path/to/mpi/dir # try to force CMake to find your preferred MPI implementation
# OR
-DMPI_C_COMPILER=/path/to/c/wrapper
-DMPI_Fortran_COMPILER=/path/to/fortran/wrapper
-DHIGH_RESOLUTION_TIMER=ON # enables timers that tick once per clock cycle
-DCOMPILER_PROVIDES_MPI # is set automatically when building with-the Cray
# Compiler EnvironmentUnlike 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
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
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 make.inc
file.
