Skip to content

Latest commit

 

History

History
467 lines (379 loc) · 18.2 KB

INSTALL.md

File metadata and controls

467 lines (379 loc) · 18.2 KB
Raw

Installing OpenCoarrays

GitHub release Github All Releases Download as PDF

Download this file as a PDF document here.

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 and/or CMake scripts included that are in the OpenCoarrays source.

top

macOS

homebrew

  • 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 INSTALL.md file.

top

Windows

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.

top

Linux

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

top

FreeBSD

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.

top

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.

top

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

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

  1. Install after building any missing prerequisites -- all source, build, and installation files will be inside the OpenCoarrays source tree under prerequisites/installations:
$ ./install.sh
  1. Install non-interactively by assuming a "yes" answer to all questions
$ ./install.sh --yes-to-all
  1. 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.

  1. Install only a specific prerequisite package (the default version):
$ ./install.sh --package mpich
  1. Install a specific version of a prerequisite:
$ ./install.sh --package cmake --install-version 3.7.0
  1. Download a prerequisite package (e.g., gcc/gfortran/g++ below) but don't build or install it:
$ ./install.sh --only-download gcc
  1. 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
  1. Install a prerelease branch (e.g., trunk below) of the GCC repository:
$ ./install.sh --package gcc --install-branch trunk
  1. 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.

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

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

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

top

Advanced Installation from Source

Prerequisites

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

top

CMake scripts

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 install

where 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 Environment

top

Make

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

top

GitHub forks GitHub stars GitHub watchers Twitter URL