Fix rpath linking for NAG, add documentation on setup (#2142)

3 files changed, 57 insertions, 27 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index 878f0df0dd..24b53b7593 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1357,7 +1357,7 @@ will add a ``python-2.7.12`` version string to any packages compiled with
 python matching the spec, ``python@2.7.12``. This is useful to know which
 version of python a set of python extensions is associated with. Likewise, the
 ``openblas`` string is attached to any program that has openblas in the spec,
-most likely via the ``+blas`` variant specification.  
+most likely via the ``+blas`` variant specification.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Regenerating Module files
diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index ddb9ba7a09..a125af70e4 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -324,7 +324,7 @@ by adding the following to your ``packages.yaml`` file:
        compiler: [gcc@4.9.3]
 
 
-.. note::
+.. tip::
 
     If you are building your own compiler, some users prefer to have a
     Spack instance just for that.  For example, create a new Spack in
@@ -393,11 +393,13 @@ build your own, plus modules:
 
 #. Once the compiler is installed, you should be able to test it by
    using Spack to load the module it just created, and running simple
-   builds (eg: ``cc helloWorld.c; ./a.out``)
+   builds (eg: ``cc helloWorld.c && ./a.out``)
 
 #. Add the newly-installed compiler to ``compilers.yaml`` as shown
    above.
 
+.. _mixed-toolchains:
+
 ^^^^^^^^^^^^^^^^
 Mixed Toolchains
 ^^^^^^^^^^^^^^^^
@@ -509,16 +511,17 @@ compilers:
    features (``spack install gcc``).
 
 #. Tell the Intel compiler how to find that desired GCC.  This may be
-   done in one of two ways: (text taken from `Intel Reference Guide
-   <https://software.intel.com/en-us/node/522750>`_):
+   done in one of two ways:
+
+      "By default, the compiler determines which version of ``gcc`` or ``g++``
+      you have installed from the ``PATH`` environment variable.
 
-   > By default, the compiler determines which version of ``gcc`` or ``g++``
-   > you have installed from the ``PATH`` environment variable.
-   >
-   > If you want use a version of ``gcc`` or ``g++`` other than the default
-   > version on your system, you need to use either the ``-gcc-name``
-   > or ``-gxx-name`` compiler option to specify the path to the version of
-   > ``gcc`` or ``g++`` that you want to use.
+      If you want use a version of ``gcc`` or ``g++`` other than the default
+      version on your system, you need to use either the ``-gcc-name``
+      or ``-gxx-name`` compiler option to specify the path to the version of
+      ``gcc`` or ``g++`` that you want to use."
+
+      -- `Intel Reference Guide <https://software.intel.com/en-us/node/522750>`_
 
 Intel compilers may therefore be configured in one of two ways with
 Spack: using modules, or using compiler flags.
@@ -556,11 +559,6 @@ configuration in ``compilers.yaml`` illustrates this technique:
 Command Line Configuration
 """"""""""""""""""""""""""
 
-. warning::
-
-    As of the writing of this manual, added compilers flags are broken;
-    see `GitHub Issue <https://github.com/LLNL/spack/pull/1532>`_.
-
 One can also control which GCC is seen by the Intel compiler by adding
 flags to the ``icc`` command:
 
@@ -616,7 +614,7 @@ distinguishable by their names.  "Old" compilers:
 Older installations of PGI contains just the old compilers; whereas
 newer installations contain the old and the new.  The new compiler is
 considered preferable, as some packages
-(``hdf4``) will not build with the old compiler.
+(``hdf``) will not build with the old compiler.
 
 When auto-detecting a PGI compiler, there are cases where Spack will
 find the old compilers, when you really want it to find the new
@@ -641,7 +639,7 @@ Other issues:
 
 .. note::
 
-   It is believed the problem with ``hdf4`` is that everything is
+   It is believed the problem with HDF 4 is that everything is
    compiled with the ``F77`` compiler, but at some point some Fortran
    90 code slipped in there. So compilers that can handle both FORTRAN
    77 and Fortran 90 (``gfortran``, ``pgfortran``, etc) are fine.  But
@@ -653,9 +651,40 @@ Other issues:
 NAG
 ^^^
 
-At this point, the NAG compiler is `known to not
-work<https://github.com/LLNL/spack/issues/590>`.
+The Numerical Algorithms Group provides a licensed Fortran compiler. Like Clang,
+this requires you to set up a :ref:`mixed-toolchains`. It is recommended to use
+GCC for your C/C++ compilers.
+
+The NAG Fortran compilers are a bit more strict than other compilers, and many
+packages will fail to install with error messages like:
+
+.. code-block:: none
+
+   Error: mpi_comm_spawn_multiple_f90.f90: Argument 3 to MPI_COMM_SPAWN_MULTIPLE has data type DOUBLE PRECISION in reference from MPI_COMM_SPAWN_MULTIPLEN and CHARACTER in reference from MPI_COMM_SPAWN_MULTIPLEA
 
+In order to convince the NAG compiler not to be too picky about calling conventions,
+you can use ``FFLAGS=-mismatch`` and ``FCFLAGS=-mismatch``. This can be done through
+the command line:
+
+.. code-block:: console
+
+   $ spack install openmpi fflags=\"-mismatch\"
+
+Or it can be set permanently in your ``compilers.yaml``:
+
+.. code-block:: yaml
+
+   - compiler:
+    modules: []
+    operating_system: centos6
+    paths:
+      cc: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/gcc
+      cxx: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/g++
+      f77: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
+      fc: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
+    flags:
+      fflags: -mismatch
+    spec: nag@6.1
 
 ---------------
 System Packages
@@ -663,7 +692,7 @@ System Packages
 
 Once compilers are configured, one needs to determine which
 pre-installed system packages, if any, to use in builds.  This is
-configured in the file `~/.spack/packages.yaml`.  For example, to use
+configured in the file ``~/.spack/packages.yaml``.  For example, to use
 an OpenMPI installed in /opt/local, one would use:
 
 .. code-block:: yaml
@@ -824,8 +853,8 @@ appeal to the system's package manager can fix such problems.  If not,
 the solution is have Spack install the required packages, and then
 have Spack use them.
 
-For example, if `curl` doesn't work, one could use the following steps
-to provide Spack a working `curl`:
+For example, if ``curl`` doesn't work, one could use the following steps
+to provide Spack a working ``curl``:
 
 .. code-block:: console
 
@@ -860,7 +889,7 @@ source code, and to load generated environment modules: ``curl``,
 
 As long as the user's environment is set up to successfully run these
 programs from outside of Spack, they should work inside of Spack as
-well.  They can generally be activated as in the `curl` example above;
+well.  They can generally be activated as in the ``curl`` example above;
 or some systems might already have an appropriate hand-built
 environment module that may be loaded.  Either way works.
 
@@ -905,6 +934,7 @@ your Linux distribution does not have Environment Modules, you can get it
 with Spack:
 
 #. Consider using system tcl (as long as your system has Tcl version 8.0 or later):
+
    #) Identify its location using ``which tclsh``
    #) Identify its version using ``echo 'puts $tcl_version;exit 0' | tclsh``
    #) Add to ``~/.spack/packages.yaml`` and modify as appropriate:
diff --git a/lib/spack/spack/compilers/nag.py b/lib/spack/spack/compilers/nag.py
index 7beb0efdf5..5ba235adbb 100644
--- a/lib/spack/spack/compilers/nag.py
+++ b/lib/spack/spack/compilers/nag.py
@@ -61,11 +61,11 @@ class Nag(Compiler):
     # options with '-Wl,-Wl,,'
     @property
     def f77_rpath_arg(self):
-        return '-Wl,-Wl,,-rpath,'
+        return '-Wl,-Wl,,-rpath,,'
 
     @property
     def fc_rpath_arg(self):
-        return '-Wl,-Wl,,-rpath,'
+        return '-Wl,-Wl,,-rpath,,'
 
     @classmethod
     def default_version(self, comp):