From 53ab450748672d5951960d54d141f1598febb6b1 Mon Sep 17 00:00:00 2001 From: Gerhard Theurich Date: Wed, 8 Nov 2023 11:41:02 -0800 Subject: [PATCH] Restructure Build section, incorporating System Specific build instructions. --- src/doc/ESMF_install.tex | 90 ++++++++++++++++++++++++-------------- src/doc/ESMF_systemreq.tex | 2 +- src/doc/makefile | 2 +- 3 files changed, 60 insertions(+), 34 deletions(-) diff --git a/src/doc/ESMF_install.tex b/src/doc/ESMF_install.tex index f499b012b1..b777516376 100644 --- a/src/doc/ESMF_install.tex +++ b/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} diff --git a/src/doc/ESMF_systemreq.tex b/src/doc/ESMF_systemreq.tex index f5880f2cd3..6d5a82878d 100644 --- a/src/doc/ESMF_systemreq.tex +++ b/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} diff --git a/src/doc/makefile b/src/doc/makefile index 7d47479895..30ef5b5206 100644 --- a/src/doc/makefile +++ b/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