Merge pull request #507 from NOAA-EPIC/docs-linux-macos

Documentation updates for MacOS and Linux
NOAA-EMC · Dec 26, 2022 · d2acee7 · d2acee7
2 parents fb310cb + 921b4d3
commit d2acee7
Show file tree

Hide file tree

Showing 6 changed files with 175 additions and 517 deletions.
diff --git a/docs/README b/docs/README
@@ -1,8 +1,29 @@
-To build html docs:
+Steps to build and use the Sphinx documentation tool:
 
-From the docs directory:
+1) Get Sphinx, sphinxcontrib-bibtex, and the RTD theme installed on your desktop from
+    http://www.sphinx-doc.org/en/master/usage/installation.html
+    https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
+    https://pypi.org/project/sphinx-rtd-theme/
 
-make clean && sphinx-build -b html source build
+    For example:
+    pip install sphinx
+    pip install sphinxcontrib-bibtex
+    pip install sphinx-rtd-theme
+
+    One approach that has worked to resolve "Module Not Found" errors for users with MacPorts package manager:
+    $ sudo port install py-six  # may not be necessary
+    $ sudo port install py310-sphinxcontrib-bibtex
+    $ sudo port select --set sphinx py310-sphinx
+    $ sudo port install py310-sphinx_rtd_theme
+
+    py310 can be replaced with the user's version of Python (e.g., py39)
+
+Build html from the docs directory:
+
+$ cd hpc-stack/docs
+$ make clean && sphinx-build -b html source build
+
+The "make html" command can often be used in place of the previous command.
 
 OR simply run: 
 

diff --git a/docs/source/hpc-install.rst b/docs/source/hpc-install.rst
@@ -122,7 +122,7 @@ To install the HPC-Stack locally, the following pre-requisites must be installed
 * **Programs and software packages:** `Lmod <https://lmod.readthedocs.io/en/latest/030_installing.html>`_, `CMake <https://cmake.org/install/>`_, `make <https://www.gnu.org/software/make/>`_, `wget <https://www.gnu.org/software/wget/>`_, `curl <https://curl.se/>`_, `git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
 
 .. note::
-   For detailed instructions on how to build the HPC-Stack on two particular configurations of MacOS, see :numref:`Chapter %s <MacInstall>`
+   For detailed instructions on how to build the HPC-Stack on several configurations of MacOS, see :numref:`Chapter %s <MacInstall>`
 
 To determine whether these prerequisites are installed, query the environment variables (for ``Lmod``) or the location and version of the packages (for ``cmake``, ``make``, ``wget``, ``curl``, ``git``). For example:
 
@@ -136,18 +136,18 @@ If compilers or MPI's need to be installed, consult the :ref:`HPC-Stack Prerequi
 
 .. _UbuntuLinux:
 
-Ubuntu 20.04 Linux Example
---------------------------
+Ubuntu Linux (20.04, 22.04) Example
+-------------------------------------
 
-The example for Ubuntu 20.4 is for a user with sudo privileges to install system-wide. First, install GNU 10 compilers:
+The example for Ubuntu (tested for 20.04 and 22.04) is for a user with sudo privileges to install system-wide. First, install GNU 10 compilers:
 
 .. code-block:: console
 
     sudo apt install gcc-10 g++-10
     sudo apt install gfortran-10
-    which gcc 
+    which gcc-10
 
-The location of default compilers is likely be in ``/usr/bin/`` (e.g. /usr/bin/gcc), and other versions are installed with the same location with the version tag. Check all the versions installed and configure the alternatives to specify which version is to be default. Below is the example when two versions are available, e.g., gcc-9 and gcc-10.
+Newly installed compiler versions and default compilers likely are located under ``/usr/bin/`` directory. Verify the location of a default compiler using ``which gcc`` command (expected ``/usr/bin/gcc``). Several versions of gcc, g++ and gfortran compilers may be present at the same location with the version tag, e.g. gcc-9, gcc-10, g++-9, g++-10. Check all the versions installed and configure the alternatives to specify a default version for each compier, as well further priorities. Below is the example on how to set alternatives and a default compiler for ``gcc`` when two versions are available, e.g., gcc-9 and gcc-10.
 
 .. code-block:: console
 
@@ -156,16 +156,28 @@ The location of default compilers is likely be in ``/usr/bin/`` (e.g. /usr/bin/g
     sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 2
     sudo update-alternatives --config gcc
 
-Make selection (1) for gcc-10 to be the first priority (default).
+Make a selection (1) for gcc-10 to be the first priority (default).
 
-Repeat similar steps to configure the alternatives for g++  and gfortran. No need to configure for gfortran if you have only a single version.
+Repeat similar steps to configure the alternatives for g++  and gfortran, if several versions are present.
 
 .. code-block:: console
 
     ls -la /usr/bin/g++-*  
     sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 1
     sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9 2
     sudo update-alternatives --config g++
+    ls -la /usr/bin/gfortran-*  
+    sudo update-alternatives --install /usr/bin/gfortran gfortran /usr/bin/gfortran-10 1
+    sudo update-alternatives --install /usr/bin/gfortran gfortran /usr/bin/gfortran-9 2
+    sudo update-alternatives --config gfortran
+
+If there are no multiple versions, a symbolic link could be created instead of setting up alternatives. The example below shows how to create a link when only gfortran-10 is present:  
+
+.. code-block:: console
+
+    ls -la /usr/bin/gfortran*  
+    ln -s /usr/bin/gfortran-10 /usr/bin/gfortran
+   
 
 Install ``lua``, ``luac`` and ``tcl`` needed to support the ``Lmod`` module management system. Verify the installation location.
 
@@ -177,11 +189,12 @@ Install ``lua``, ``luac`` and ``tcl`` needed to support the ``Lmod`` module mana
     which luac
     
 Standard installation paths for lua/luac are ``/usr/bin/lua`` and ``/usr/bin/luac``. 
-Download and install Lmod, the module management environment, if not installed in the system. When installed, the environmental variable $LMOD_ROOT is defined: 
+Download and install Lmod, the module management environment, if not installed in the system. When installed, the environmental variable $LMOD_ROOT or $LMOD_PKG are usually defined.
 
 .. code-block:: console
 
     echo $LMOD_ROOT
+    echo $LMOD_PKG 
     git clone https://github.com/TACC/Lmod.git 
     cd Lmod
 
@@ -192,14 +205,15 @@ See the INSTALL file for instructions; configure and install. Use the paths for
     ./configure --with-lua=/usr/bin/lua  --with-luac=/usr/bin/luac --prefix=${HOME}/apps 
     make install
 
-Add the Lmod environment initialization to your shell profile, i.e. to $HOME/.bashrc or $HOME/.bash_profile: 
+Add the Lmod environment initialization to your shell profile, 
+i.e. to $HOME/.bash_profile (login bash session) or $HOME/.bashrc (non-login bash):
 
 .. code-block:: console
 
     export BASH_ENV=$HOME/apps/lmod/lmod/init/profile        
     source $BASH_ENV
 
-Install  wget, git, make and cmake; cmake could also be built bundled with the hpc-stack.
+Install  wget, git, make and cmake; cmake could also be built bundled with the hpc-stack as an alternative..
 
 .. code-block:: console
 
@@ -215,8 +229,25 @@ Install openssl, libssl-dev packages:
     sudo apt install openssl
     sudo apt-get install libssl-dev
 
+Install make and cmake:
+
+.. code-block:: console
+
+    sudo apt install make
+    sudo apt install cmake 
+
+
+Both ``python`` and ``python3`` commands need to be defined. The ``python`` could be set to python2 version higher than 2.7.x or to python3. python3 version needs to be higher than 3.6. Verify they are present and their versions:
+
+.. code-block:: console
+
+    which python 
+    which python3 
+    python --version 
+    python3 --version 
+    apt list | grep python  
 
-Both ``python2`` and ``python3`` are needed; python2 version higher than 2.7.x; python3 version higher than 3.6. You could update ``python3`` if higher versions are available (python3.9 in the example below at the time of writing), and set the alternatives when multiple versions exist. The highest version among the existing python3.8 and python3.9 is set as a default in the example below (choose selection 1 for python3.9 when prompt). 
+Usually, ``python`` and ``python2`` are available with the Linux distribution. If no ``python`` is found, a symbolic link to ``python3`` could be created, or alternatives to use python3 could be set instead. Python3 could be installed or updated if higher versions than existing are available. The example below shows how to verify the current installed version (e.g. python3.8), update to a higher one (e.g, python3.9), and set the alternatives to use python3.9 as a default version of ``python3``. Choose selection 1 for python3.9 when prompt: 
 
 .. code-block:: console
 
@@ -229,7 +260,7 @@ Both ``python2`` and ``python3`` are needed; python2 version higher than 2.7.x;
     sudo update-alternatives --config python3  
     python3 --version  
 
-Verify the version (python 3.9) set as default after the configuration. 
+Verify the version (python 3.9 in the above example) set as default using ``python3 --version``.
 
 
 .. _NonConConfigure:
@@ -326,7 +357,7 @@ Now all that remains is to build the stack:
 
       ./build_stack.sh -p <prefix> -c <configuration> -y <yaml_file> -m
 
-Here the -m option is only required when you need to build your own modules *and* LMod is used for managing the software stack. It should be omitted otherwise. ``<prefix>`` and ``<configuration>`` are the same as in :numref:`Step %s <NonConSetUp>`, namely a reference to the absolute-path installation prefix and a corresponding configuration file in the ``config`` directory. As in :numref:`Step %s <NonConSetUp>`, if this argument is omitted, the default is to use ``$HOME/opt`` and ``config/config_custom.sh`` respectively. ``<yaml_file>`` represents a user configurable yaml file containing a list of packages that need to be built in the stack along with their versions and package options. The default value of ``<yaml_file>`` is ``stack/stack_custom.yaml``.
+The the ``-m`` option is **required** to build the sofware stack as modules for Lmod environment, which is usually needed. It could be omitted to build the libraries with no module environment. ``<prefix>`` and ``<configuration>`` are the same as in :numref:`Step %s <NonConSetUp>`, namely a reference to the absolute-path installation prefix and a corresponding configuration file in the ``config`` directory. As in :numref:`Step %s <NonConSetUp>`, if this argument is omitted, the default is to use ``$HOME/opt`` and ``config/config_custom.sh`` respectively. ``<yaml_file>`` represents a user configurable yaml file containing a list of packages that need to be built in the stack along with their versions and package options. The default value of ``<yaml_file>`` is ``stack/stack_custom.yaml``.
 
 .. warning:: 
    Steps :numref:`Step %s <NonConConfigure>`, :numref:`Step %s <NonConSetUp>`, and :numref:`Step %s <NonConHPCBuild>` need to be repeated for each compiler/MPI combination that you wish to install. The new packages will be installed alongside any previously-existing packages that may already have been built from other compiler/MPI combinations.

diff --git a/docs/source/hpc-prereqs.rst b/docs/source/hpc-prereqs.rst
@@ -5,30 +5,33 @@
 Installation of the HPC-Stack Prerequisites
 =============================================
 
-A wide variety of compiler and MPI options are available. Certain combinations may play well together, whereas others may not. 
+A wide variety of compiler and MPI options are available. Certain combinations may play well together, whereas others may not. Some examples and installation instructions are given in previous Sections for Ubuntu Linux (:numref:`Chapter %s <NonContainerInstall>`) and MacOS (:numref:`Chapter %s <MacInstall>`).  
 
 The following system, compiler, and MPI combinations have been tested successfully:
 
 .. table::  Sample System, Compiler, and MPI Options
 
-   +------------------------+-------------------------+-----------------------------+
-   | **System**             |  **Compilers**          | **MPI**                     |
-   +========================+=========================+=============================+
-   | SUSE Linux Enterprise  | Intel compilers 2020.0  | Intel MPI wrappers          |
-   | Server 12.4            | (ifort, icc, icps)      | (mpif90, mpicc, mpicxx)     |
-   +------------------------+-------------------------+-----------------------------+
-   | Linux CentOS 7         | Intel compilers 2020.0  | Intel MPI                   |
-   |                        | (ifort, icc, icps)      | (mpiifort, mpiicc, mpiicpc) |
-   +------------------------+-------------------------+-----------------------------+
-   | Linux Ubuntu 20.04     | GNU compilers 10.3      | MPICH 3.3.2                 |
-   |                        | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |
-   +------------------------+-------------------------+-----------------------------+
-   | MacOS M1/arm64 arch.   | GNU compilers 10.2      | OpenMPI 4.1.2               |
-   |  Darwin20 (BigSur)     | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |
-   +------------------------+-------------------------+-----------------------------+
-   | MacOS Intel x86_64     | GNU compilers 10.2      | OpenMPI 4.1.2, MPICH 3.3.2  |
-   |   Darwin19 (Catalina)  | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |  
-   +------------------------+-------------------------+-----------------------------+
+   +-------------------------+-------------------------+-----------------------------+
+   | **System**              |  **Compilers**          | **MPI**                     |
+   +=========================+=========================+=============================+
+   | SUSE Linux Enterprise   | Intel compilers 2020.0  | Intel MPI wrappers          |
+   | Server 12.4             | (ifort, icc, icps)      | (mpif90, mpicc, mpicxx)     |
+   +-------------------------+-------------------------+-----------------------------+
+   | Linux CentOS 7          | Intel compilers 2020.0  | Intel MPI                   |
+   |                         | (ifort, icc, icps)      | (mpiifort, mpiicc, mpiicpc) |
+   +-------------------------+-------------------------+-----------------------------+
+   | Linux Ubuntu 20.04,22.04| GNU compilers 10.3      | MPICH 3.3.2                 |
+   |                         | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |
+   +-------------------------+-------------------------+-----------------------------+
+   | MacOS M1/arm64 arch.    | GNU compilers 10.2,11.3 | OpenMPI 4.1.2               |
+   |  Darwin20 (BigSur)      | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |
+   +-------------------------+-------------------------+-----------------------------+
+   | MacOS Intel x86_64      | GNU compilers 10.2      | OpenMPI 4.1.2, MPICH 3.3.2  |
+   |   Darwin19 (Catalina)   | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |  
+   +-------------------------+-------------------------+-----------------------------+
+   | MacOS Intel x86_64      | GNU compilers 11.3      | OpenMPI 4.1.2               |
+   |   Darwin21 (Monterey)   | (gcc, g++, gfortran)    | (mpifort, mpicc, mpicxx)    |  
+   +-------------------------+-------------------------+-----------------------------+
 
 Compilers and MPI libraries can be downloaded from the following websites: