Commit 2a21ceb8 authored by Brandon's avatar Brandon

Merge branch 'bcf/reorg_compilers' into 'master'

Compilers: rearrange compiler docs

See merge request !232
parents 2b4ce21f e4ad0e1b
# Cray Compiler Wrappers
Cray provides a convenient set of wrapper commands that should be used
in almost all cases for compiling and linking parallel
programs. Invoking the wrappers will automatically link codes with MPI
libraries and other Cray system software. All MPI and Cray system
include directories are also transparently imported. In addition the
wrappers append the compiler's target processor arguments for the Cori
compute node processors.
!!! note
The intention is that programs are compiled on the login nodes
and executed on the compute nodes. Because the compute nodes and
login nodes have different operating systems, binaries created for
compute nodes may not run on the login node. The wrappers
mentioned above guarantee that codes compiled using the wrappers
are prepared for running on the compute nodes.
!!! warning
On Cori there are two types of compute nodes: Haswell and
KNL. While binaries built for Haswell do run on KNL (not vice
versa), it is necessary to build for KNL explicitly in order to
exploit the new AVX512 architecture. Please see below for more
information on how to compile for KNL compute nodes.
## Basic Example
The Cray compiler wrappers take the place of other common wrappers
such `mpif90`, `mpicc`, `mpiicc` and `mpic++`. By default the
appropriate MPI libraries are included and if the `cray-libsci` module
is loaded then BLAS and LAPACK will also be included if necessary.
### Fortran
```shell
ftn -o example.x example.f90
```
### C
```shell
cc -o example.x example.c
```
### C++
```shell
CC -o example.x example.cpp
```
## Makefile
In the ideal case one simply has to replace any variables or compiler
commands with the Cray compiler wrappers.
## configure
Often specifying the compiler wrappers is enough for a configure step
to succeed.
```shell
./configure CC=CC cc=cc FC=ftn
```
!!! tip
Reading the output of `./configure --help` is often very
instructive when determining what other options are
appropriate. (e.g. `--enable-mpi`)
# Native compilers on NERSC systems
Cori and Edison provide three compiler suites:
* Intel
* GNU
* Cray
Each suite provides compilers for C, C++, and Fortran. Each compiler has
different characteristics - different compilers generate faster code under
different circumstances. All three compilers provide support for OpenMP.
All compilers on Cori (Intel, Cray, and GNU), are provided via three
"programming environments" that are accessed via the `module` utility. Each
programming environment contains the full set of compatible compilers and
libraries. To change from one compiler to the other you change the programming
environment via the `module swap` command.
Additionally, NERSC provides the LLVM compilers `clang`, `clang++`, and `flang`
for C, C++, and Fortran, respectively. These are not supported by Cray and
therefore are not compatible with all of the same software and libraries that
the Cray-provided compiler suites are, but are nevertheless useful for users
who require an open-source LLVM-based compiler toolchain.
## Intel
The Intel compiler suite is available via the `PrgEnv-intel` module, and is loaded by
default on Cori and Edison. The native compilers in this suite are:
* C: `icc`
* C++: `icpc`
* Fortran: `ifort`
Full documentation of the Intel compilers is provided
[here](https://software.intel.com/en-us/intel-compilers). Additionally,
compiler documentation is provided through `man` pages (e.g., `man icpc`) and
through the `-help` flag to each compiler (e.g., `ifort -help`).
## GNU
The GCC compiler suite is available via the `PrgEnv-gnu` module. The native
compilers in this suite are:
* C: `gcc`
* C++: `g++`
* Fortran: `gfortran`
Full documentation of the GCC compilers is provided
[here](https://gcc.gnu.org/onlinedocs). Additionally, compiler documentation is
provided through `man` pages (e.g., `man g++`) and through the `--help` flag to
each compiler (e.g., `gfortran --help`).
## Cray
The Cray compiler suite is available via the `PrgEnv-cray` module. The native
compilers in this suite are:
* C: `cc`
* C++: `CC`
* Fortran: `ftn`
Full documentation of the Cray compilers is provided
[here](https://pubs.cray.com/content/S-2179/8.7/cray-c-and-c++-reference-manual/the-cray-compiling-environment)
for the C/C++ compilers, and
[here](https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/fortran-compiler-introduction)
for the Fortran compiler. Additionally, compiler documentation is provided
through `man` pages (e.g., `man CC`).
## LLVM
The LLVM core libraries along with the compilers are available only on Cori. It
is compiled against the GCC compiler suite and thus cannot be used with the
Intel or Cray programming environments.
In order to enable clang compiler, first make sure to load the gnu programming
environment
```Shell
module load PrgEnv-gnu
module load gcc
module load llvm/<version>
```
where `module avail llvm` displays which versions are currently installed.
The module `llvm/5.0.0-gnu-flang` contains the LLVM-based Fortran compiler
`flang`. However, this compiler is highly experimental and should not be used
for production applications. Furthermore, it does not find the standard headers
and Fortran modules by default. Therefore, those need to be added manually to
the compilation flags using `-I`. Please use `module show llvm/5.0.0-gnu-flang`
to find the corresponding include paths for these headers and modules.
For more information, see [LLVM](https://llvm.org/),
[Clang](https://clang.llvm.org/), and
[Flang](https://github.com/flang-compiler/flang/wiki) websites.
## Common compiler options
Below is a table documenting common flags for each of the three compilers.
| | Intel | GCC | Cray | comment |
|----------------------|--------|------|-------|---------|
| Overall optimization | `-O<n>` | `-O<n>` | `-O<n>` | Replace `<n>` with `1`, `2`, `3`, etc. |
| Enable OpenMP | `-qopenmp` | `-fopenmp` | `-h omp` | OpenMP enabled by default in Cray. |
| Free-form Fortran | `-free` | `-ffree-form` | `-f free` | Also determined by file suffix (`.f`, `.F`, `.f90`, etc.) |
| Fixed-form Fortran | `-fixed` | `-ffixed-form` | `-f fixed` | Also determined by file suffix (`.f`, `.F`, `.f90`, etc.) |
| Debug symbols | `-g` | `-g` | N/A | Debug symbols enabled by default in Cray. |
# Intel Compiler Wrappers
# Compiler Wrappers
## Introduction
NERSC provides compiler wrappers on Cori and Edison which combine the [native
compilers](native.md) (Intel, GNU, and Cray) with MPI and various other
libraries, to enable streamlined compilation of scientific applications.
Although the [Cray compiler wrappers](index.md) `cc`, `CC`, and `ftn`, are the
default (and recommended) compiler wrappers on the Cori and Edison systems,
wrappers for Intel MPI are provided as well via the the `impi` module.
## Cray Compiler Wrappers
Cray provides a convenient set of wrapper commands that should be used in
almost all cases for compiling and linking parallel programs. Invoking the
wrappers will automatically link codes with MPI libraries and other Cray system
software. All MPI and Cray system directories are also transparently imported.
In addition, the wrappers cross-compile for the appropriate compute node
architecture, based on which `craype-<arch>` module is loaded when the compiler
is invoked, where the possible values of `<arch>` are discussed below.
!!! note
The intention is that programs are compiled on the login nodes and executed
on the compute nodes. Because the compute nodes and login nodes have
different hardware and software, executables cross-compiled for compute
nodes may fail if run on login nodes. The wrappers mentioned above
guarantee that codes compiled using the wrappers are prepared for running
on the compute nodes.
!!! warning
On Cori there are two types of compute nodes: Haswell and KNL. While
applications cross-compiled for Haswell do run on KNL compute nodes, the
converse is not true (applications compiled for KNL will fail if run on
Haswell compute nodes). Additionally, even though a code compiled for
Haswell will run on a KNL node, it will not be able to take advantage of
the wide vector processing units available on KNL. Consequently, one should
specifically target KNL nodes during compilation in order to achieve the
highest possible code performance. Please see below for more information on
how to compile for KNL compute nodes.
### Basic Example
The Cray compiler wrappers replace other compiler wrappers commonly found on
computer clusters, such as `mpif90`, `mpicc`, and `mpic++`. By default, the
Cray wrappers include MPI libraries and header files, as well as the many
scientific libraries included in Cray [LibSci](../libraries/libsci/index.md).
#### Fortran
```shell
ftn -o example.x example.f90
```
#### C
```shell
cc -o example.x example.c
```
#### C++
```shell
CC -o example.x example.cpp
```
!!! tip "Using compiler wrappers in `./configure`"
When compiling an application which uses the standard series of `./configure`,
`make`, and `make install`, often specifying the compiler wrappers in the
appropriate environment variables is sufficient for a configure step to
succeed, e.g.:
```shell
./configure CC=CC CXX=cc FC=ftn
```
## Intel Compiler Wrappers
Although the Cray compiler wrappers `cc`, `CC`, and `ftn`, are the default (and
recommended) compiler wrappers on the Cori and Edison systems, wrappers for
Intel MPI are provided as well via the the `impi` module.
The Intel MPI wrapper commands are `mpiicc`, `mpiicpc`, and `mpiifort`, which
are analogous to `cc`, `CC`, and `ftn` from the Cray wrappers, respetively. In
......@@ -14,8 +81,8 @@ dynamic, not static.
!!! warning
Although Intel MPI is available on the Cray systems at NERSC, it is not
tuned for high performance on the high speed network on these systems.
Consequently, it is possible that MPI application performance will be lower
if compiled with Intel MPI than with Cray MPI.
Consequently, it is possible, even likely, that MPI application performance
will be lower if compiled with Intel MPI than with Cray MPI.
!!! note
If one chooses to use the Intel MPI compiler wrappers, they are compatible
......@@ -29,7 +96,13 @@ dynamic, not static.
user must apply the appropriate architecture flags to the wrappers manually,
e.g., adding the `-xMIC-AVX512` flag to compile for KNL.
## Compiling
!!! warning
Unlike the Cray compiler wrappers, the Intel compiler wrappers do not
automatically include and link to scientific libraries such as LibSci.
These libraries must be included and linked manually if using the Intel MPI
wrappers.
### Compiling
The Intel compiler wrappers function similarly to the Cray wrappers `cc`, `CC`,
and `ftn`. However a few extra steps are required. To compile with the Intel
......@@ -48,7 +121,7 @@ user@nersc> module load impi
user@nersc> mpiifort -xMIC-AVX512 -o example.x example.f90 # Intel wrappers ignore craype module
```
## Running
### Running
To run an application compiled with Intel MPI, one must set a few extra
environment variables:
......
......@@ -14,7 +14,7 @@ visit [MyNERSC](https://my.nersc.gov).
## Quick links/ FAQ
1. [Obtaining an Account](accounts/index.md#obtaining-an-account)
1. [Building Software](development/compilers/index.md)
1. [Building Software](development/compilers/wrappers.md)
1. [Running Jobs](jobs/index.md)
1. [Managing Data](data/management.md)
1. [Reset my password](accounts/index.md#forgotten-passwords)
......
......@@ -115,9 +115,8 @@ nav:
- Trace Analyzer and Collector: development/performance-debugging-tools/itac.md
- LIKWID : development/performance-debugging-tools/likwid.md
- Compilers :
- Cray Compiler Wrappers: development/compilers/index.md
- Intel Compiler Wrappers: development/compilers/intel_mpi.md
- LLVM : development/compilers/llvm.md
- Native Compilers : development/compilers/native.md
- Compiler Wrappers (recommended) : development/compilers/wrappers.md
- High-level Programming Environments:
- Python :
- development/high-level-environments/python/index.md
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment