Skip to content

Latest commit

 

History

History
573 lines (456 loc) · 22.6 KB

INSTALL.md

File metadata and controls

573 lines (456 loc) · 22.6 KB
Raw

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 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, 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. Below is the status of OpenCoarrays in various package managers. If you do not see your favorite package manager listed or it is badly out of date, please reach out and ask for it to be included or updated, or contribute it yourself. We are happy to work with package managers to resolve issues, and adapt our build system to play nicely so they don't have to maintain patches.

Packaging status

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.

top

macOS

  • Homebrew: homebrew This is the recommended 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 installation support has recently been enhanced. The new installation method doesn't require Cygwin or WSL and relies only a light weight git/bash distribution like Git-Bash, and the Intel OneAPI base distribution as well as the Intel OneAPI HPC Toolkit. This allows native and redistributable statically linked binaries to be built if you use the appropriate compiler flags. Clients will only require the free redistributable Intel MPI runtime.

New and Recommended Windows Installation

Please follow these instructions, this is the recommended way to install OpenCoarrays on Windows.

Pre-requisites
Installation Procedure
  1. Ensure all the prerequisites have been installed following the directions of the provider.
  2. Launch the 64-bit Intel OneAPI developer shell. This will either be in the start menu, or you may need to figure out how to launch it manually. See the note below for help.
  3. Ensure that cmake, git-bash, gfortran, gcc, make are available on your default path. The installers should have taken care of this for you.
  4. Launch a Git-Bash bash shell from the OneAPI environment, or ensure Git-Bash's bash.exe is first on your path by either:
    1. Typing git-bash from within the windows CMD.exe style OneAPI shell, or
    2. Editing your system wide %PATH% variable, or updating it in the local shell so that git-bash's bin subdirectory (containing bash.exe) is at the front of your PATH: set PATH=C:\path\to\Git-Bash\bin;%PATH%.
  5. At this point, typing bash --version should show you you're using Git-Bash, AND typing bash -c pwd should match the current directory. bash provided with WSL will show the directory as your home directory, something like /home/username and this will cause problems later
  6. cd to the extracted OpenCoarrays source directory (obtained by downloading a release archive, or, for advanced useres, checked out with git, etc.)
  7. Create a build directory and change to it with something like: mkdir build and cd build
  8. Set GCC and GFortran as the default C and Fortran compilers with something like: set FC=gfortran and set CC=gcc
  9. Check that Intel's MPI is setup correctly by typing mpifc -show which should show you how the compiler wrapper script is planning to build MPI programs. (It's fine if this shows ifort being used as the compiler instead of gfortran at this point.)
  10. Configure Open-Coarrays with CMake and specify the installation directory you would like to use. (If this is not a user-writable location, you will have to open a new shell later as an administrator to perform the installation step.) Run: cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="C:\path\to\desired\install\location" ".\path\to\opencoarrays-source-dir" The quotes ensure paths with spaces are handled properly. You may omit them if there are no spaces.
  11. When the configuration completes, build with: cmake --build . -j <ncores>
  12. Install OpenCoarrays: cmake --build . -j <ncores> -t install
  13. Optionally run the test suite. There are a few known failures on Windows. Also, a large numberof firewall warnings will pop up. cmake --build . -t check

NOTE About the Intel OneAPI CMD.exe shell

If you don't have a "Intel oneAPI command prompt for Intel 64 for Visual Studio 20xx" in your start menu you can figure out how to launch an equivalent CMD.exe or Powershell instance by examining the shortcut Target that it created for me:

%ComSpec% /E:ON /K ""C:\Program Files (x86)\Intel\oneAPI\setvars.bat" intel64 vs2022"

So it looks like you can launch CMD.exe and then run the appropriate setvars.bat script with the intel64 and vs20<xx> arguments where vs20<xx> matches the appropriate Visual Studio version.

Old Procedure

NOTE: Use this method at your own risk, it is no longer officially supported!

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 linuxbrew pulls directly from macOS homebrew, which updates automatically.

Note that distributions are often split into two parts: a "binary" package with the runtime libraries and a "development" package for developing programs yourself. Be sure to install both packages.

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 2.2.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 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. If you don't care about tailoring installation locations,use

    ./install.sh

  2. Or build faster by multithreading, skipping user queries, and also specify an installation destination for all packages that must be built:

    ./install.sh \
  --prefix-root ${HOME}/software \
  --num-threads 4 \
  --yes-to-all

  3. Specify the compilers to be used (overriding what is in your PATH) as follows:

    ./install.sh --with-fortran <path-to-gcc-bin>/gfortran \
             --with-cxx <path-to-gcc-bin>/g++ \
             --with-c <path-to-gcc-bin>/gcc

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

    ./install.sh --package mpich

  5. Install a specific version of a prerequisite:

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

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

    ./install.sh --print-url mpich
./install.sh --print-version mpich
./install.sh --print-downloader mpich

  8. Install a prerelease branch (e.g., trunk below) of the GCC repository:

    ./install.sh --package gcc --install-branch trunk

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

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.

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 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 2018 failed images; they will not build the opencoarrays module that can be used to provide some Fortran 2018 features with non-Fortran-2018 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