Restructure Build section, incorporating System Specific build

instructions.

src/doc/ESMF_install.tex

@@ -53,10 +53,67 @@ \subsection{Acquiring Development Snapshots}
 
 Once downloaded, development snapshots are built in the same way as releases.
 
-\subsection{System Requirements}
+\subsection{System Specific Information}
+
+\subsubsection{General Requirements}
 \label{sec:systemreq}
 \input{ESMF_systemreq}
 
+\subsubsection{Intel Compiler (Classic and oneAPI)}
+
+ESMF supports the Intel compiler suite via {\tt ESMF\_COMPILER=intel}. Starting in 2020, Intel began promoting their
+new LLVM-based C/C++ and Fortran compiler line under the oneAPI brand. As of 2023, the older compilers are still
+part of the Intel compiler suite and referred to as Intel Compiler Classic. ESMF supports both the classic and oneAPI
+compiler lines. The following paragraphs provide important details that allow users to fine-tune the interaction
+with the Intel compilers.
+
+Under {\tt ESMF\_OS=Linux}, with {\tt ESMF\_COMPILER=intel} and {\tt ESMF\_COMM=mpiuni} set, the C, C++, and
+Fortran compiler front-ends default to the classic options {\tt icc}, {\tt icpc}, and {\tt ifort}, respectively. Any
+of these defaults can be overridden by explicitly setting the {\tt ESMF\_C}, {\tt ESMF\_CXX}, or {\tt ESMF\_F90}
+environment variables to the oneAPI options {\tt icx}, {\tt icpx}, and {\tt ifx}, respectively.
+
+Under {\tt ESMF\_OS=Linux}, with {\tt ESMF\_COMPILER=intel} and {\tt ESMF\_COMM=intelmpi} set, the C, C++, and
+Fortran compiler front-ends default to the MPI compiler wrappers {\tt mpiicc}, {\tt mpicpc}, and {\tt mpiifort},
+respectively. It depends on the IntelMPI installation details whether classic, oneAPI, or a mixture of compilers
+are used underneath the MPI wrappers. The IntelMPI defaults can be overridden by explicitly setting the
+{\tt I\_MPI\_CC}, {\tt I\_MPI\_CXX}, or {\tt I\_MPI\_F90} environment variables. This is an IntelMPI feature.
+
+The recommendation for Cray systems that use the Cray compiler wrappers {\tt cc}, {\tt CC}, and {\tt ftn},
+respectively, is to use {\tt ESMF\_OS=Unicos}. In most cases this setting is detected automatically by the ESMF
+build system, and should {\em not} be overridden.
+
+Under {\tt ESMF\_OS=Unicos}, with {\tt ESMF\_COMPILER=intel}, the C, C++, and Fortran compiler front-ends default to
+{\tt cc}, {\tt CC}, and {\tt ftn}, respectively, regardless of the  {\tt ESMF\_COMM} setting. The appropriate
+classic, oneAPI, or mixed compiler combination is typically determined by the Intel environment module loaded.
+Common module names on Cray systems are {\tt intel-classic}, {\tt intel-oneAPI}, and {\tt intel}, respectively.
+
+{\bf Tip: } Use the ESMF "{\tt make info}" target to query compiler version information. This can be used to determine the
+appropriate settings, and to diagnose issues before kicking off the complete ESMF build procedure.
+
+\subsubsection{MacOS Darwin}
+
+ESMF supports MacOS systems via the {\tt ESMF\_OS=Darwin} setting, which
+typically is auto-detected by the ESMF build system. Various compilers and
+MPI implementations are supported under Darwin using the {\tt ESMF\_COMPILER}
+and {\tt ESMF\_COMM} environment variables. There are some combinations under
+Darwin that require special attention; these combinations are listed below.
+
+On Darwin with {\tt ESMF\_COMPILER=gfortran} and {\tt ESMF\_COMM=mpich},
+using MPICH3 built from source, it is important to specify the
+{\tt --enable-two-level-namespace} configure option when building the MPICH3
+library. By default, i.e. without this option, the produced MPICH compiler
+wrappers include a linker flag ({\tt -flat\_namespace}) that causes issues with
+C++ exception handling under GNU g++. Building and linking ESMF applications
+with MPICH compiler wrappers that specify this linker option leads to
+"mysterious" application aborts during execution.
+
+On Darwin with {\tt ESMF\_COMPILER=intel}, command line arguments cannot be
+accessed from ESMF applications when linked against the shared library version
+({\tt libesmf.dylib}). There is no issue when linked against the static
+version ({\tt libesmf.a}). Setting the environment variable
+{\tt ESMF\_SHARED\_LIB\_BUILD=OFF} when building ESMF can be used as a
+work around for this issue.
+
 \subsection{Third Party Libraries}
 \label{sec:ThirdParty}
 
@@ -1148,37 +1205,6 @@ \subsection{Supported Platforms}
 will be stored in a separate directories so the results will be kept
 separate for different architectures or options.
 
-\subsubsection{Intel Compiler Support (Classic and oneAPI)}
-
-ESMF supports the Intel compiler suite via {\tt ESMF\_COMPILER=intel}. Starting in 2020, Intel began promoting their
-new LLVM-based C/C++ and Fortran compiler line under the oneAPI brand. As of 2023, the older compilers are still
-part of the Intel compiler suite and referred to as Intel Compiler Classic. ESMF supports both the classic and oneAPI
-compiler lines. The following paragraphs provide important details that allow users to fine-tune the interaction
-with the Intel compilers.
-
-Under {\tt ESMF\_OS=Linux}, with {\tt ESMF\_COMPILER=intel} and {\tt ESMF\_COMM=mpiuni} set, the C, C++, and
-Fortran compiler front-ends default to the classic options {\tt icc}, {\tt icpc}, and {\tt ifort}, respectively. Any
-of these defaults can be overridden by explicitly setting the {\tt ESMF\_C}, {\tt ESMF\_CXX}, or {\tt ESMF\_F90}
-environment variables to the oneAPI options {\tt icx}, {\tt icpx}, and {\tt ifx}, respectively.
-
-Under {\tt ESMF\_OS=Linux}, with {\tt ESMF\_COMPILER=intel} and {\tt ESMF\_COMM=intelmpi} set, the C, C++, and
-Fortran compiler front-ends default to the MPI compiler wrappers {\tt mpiicc}, {\tt mpicpc}, and {\tt mpiifort},
-respectively. It depends on the IntelMPI installation details whether classic, oneAPI, or a mixture of compilers
-are used underneath the MPI wrappers. The IntelMPI defaults can be overridden by explicitly setting the
-{\tt I\_MPI\_CC}, {\tt I\_MPI\_CXX}, or {\tt I\_MPI\_F90} environment variables. This is an IntelMPI feature.
-
-The recommendation for Cray systems that use the Cray compiler wrappers {\tt cc}, {\tt CC}, and {\tt ftn},
-respectively, is to use {\tt ESMF\_OS=Unicos}. In most cases this setting is detected automatically by the ESMF
-build system, and should {\em not} be overridden.
-
-Under {\tt ESMF\_OS=Unicos}, with {\tt ESMF\_COMPILER=intel}, the C, C++, and Fortran compiler front-ends default to
-{\tt cc}, {\tt CC}, and {\tt ftn}, respectively, regardless of the  {\tt ESMF\_COMM} setting. The appropriate
-classic, oneAPI, or mixed compiler combination is typically determined by the Intel environment module loaded.
-Common module names on Cray systems are {\tt intel-classic}, {\tt intel-oneAPI}, and {\tt intel}, respectively.
-
-{\bf Tip: } Use the ESMF "{\tt make info}" target to query compiler version information. This can be used to determine the
-appropriate settings, and to diagnose issues before kicking off the complete ESMF build procedure.
-
 \subsection{Building the ESMF Library}
 \label{BuildESMF}
 

src/doc/ESMF_systemreq.tex

@@ -57,7 +57,7 @@
 Internal packages that can optionally reference external libraries:
 \begin{itemize}
 \item LAPACK - version 3.x or newer
-\item ParallelIO (PIO) - version 2.5.7 or newer
+\item ParallelIO (PIO) - version 2.5.10 or newer
 \item yaml-cpp - tag yaml-cpp-0.6.2 or newer
 \end{itemize}
 

src/doc/makefile

@@ -30,7 +30,7 @@ TEXINPUTS_VALUE = ".:$(ESMF_DIR)/src/doc:$(ESMF_BUILD_DOCDIR):"
 # all of the dependent files, but even a partial listing  will be helpful.
 
 REFDOC_DEP_FILES = ESMF_options.tex
-USRDOC_DEP_FILES = ESMF_acknowledge.tex ESMF_whatisesmf.tex ESMF_usrintro.tex ESMF_usrsupport.tex ESMF_quickstart.tex ESMF_techoverview.tex ESMF_archoverview.tex ESMF_adoption.tex ESMF_use.tex ESMF_debug.tex ESMF_clts.tex ESMF_install.tex $(ESMF_DIR)/build/doc/ESMF_builddetail.tex ESMF_testing.tex ESMF_examples.tex ESMF_esmfmkfiletesting.tex $(ESMF_DIR)/build/doc/user_make.tex $(ESMF_DIR)/build/doc/user_arch.tex
+USRDOC_DEP_FILES = ESMF_acknowledge.tex ESMF_whatisesmf.tex ESMF_usrintro.tex ESMF_usrsupport.tex ESMF_quickstart.tex ESMF_techoverview.tex ESMF_systemreq.tex ESMF_archoverview.tex ESMF_adoption.tex ESMF_use.tex ESMF_debug.tex ESMF_clts.tex ESMF_install.tex $(ESMF_DIR)/build/doc/ESMF_builddetail.tex ESMF_testing.tex ESMF_examples.tex ESMF_esmfmkfiletesting.tex $(ESMF_DIR)/build/doc/user_make.tex $(ESMF_DIR)/build/doc/user_arch.tex
 
 include $(ESMF_DIR)/makefile