Install cmake module files (#282)

* copies FindESMF.cmake into cmake directory in installation

Author: danrosen25

build/common.mk

@@ -552,6 +552,16 @@ else
 export ESMF_INSTALL_DOCDIR_ABSPATH = $(ESMF_INSTALL_DOCDIR)
 endif
 
+ifndef ESMF_INSTALL_CMAKEDIR
+ESMF_INSTALL_CMAKEDIR := cmake
+endif
+pathtype := $(shell $(ESMF_DIR)/scripts/pathtype $(ESMF_INSTALL_CMAKEDIR))
+ifeq ($(pathtype),rel)
+export ESMF_INSTALL_CMAKEDIR_ABSPATH = $(ESMF_INSTALL_PREFIX_ABSPATH)/$(ESMF_INSTALL_CMAKEDIR)
+else
+export ESMF_INSTALL_CMAKEDIR_ABSPATH = $(ESMF_INSTALL_CMAKEDIR)
+endif
+
 #-------------------------------------------------------------------------------
 # Set ESMFMKFILE here in order to be available for installcheck target
 #-------------------------------------------------------------------------------
@@ -654,6 +664,9 @@ ESMF_APPSDIR     = $(ESMF_BUILD)/apps/apps$(ESMF_BOPT)/$(ESMF_OS).$(ESMF_COMPILE
 # unified nuopc executable directory
 ESMF_ESMXDIR     = $(ESMF_BUILD)/src/addon/ESMX
 
+# cmake modules directory
+ESMF_CMAKEDIR    = $(ESMF_DIR)/cmake
+
 # include file directory
 ESMF_INCDIR     = $(ESMF_BUILD)/src/include
 

cmake/FindESMF.cmake

@@ -12,6 +12,21 @@
 # Set ESMFMKFILE as defined by system env variable. If it's not explicitly set
 # try to find esmf.mk file in default locations (ESMF_ROOT, CMAKE_PREFIX_PATH,
 # etc)
+
+# - Common Usage
+#
+# Where to look for this FindESMF.cmake file
+#   list(APPEND CMAKE_MODULE_PATH "<PATH_TO_THIS_FILE>")
+#   <PATH_TO_THIS_FILE> is to be replaced with the directory for this file
+#
+# How to locate ESMF libraries and create target
+#   find_package(ESMF <X.Y.Z> MODULE REQUIRED)
+#   <X.Y.Z> is to be replaced with the minimum version required
+#
+# How to link targets
+#   target_link_libraries(<CMAKE_TARGET> PUBLIC ESMF::ESMF)
+#   <CMAKE_TARGET> is to be replaced with your CMake target
+
 if(NOT DEFINED ESMFMKFILE)
   if(NOT DEFINED ENV{ESMFMKFILE})
     find_path(ESMFMKFILE_PATH esmf.mk PATH_SUFFIXES lib lib64)

cmake/README.md

@@ -0,0 +1,49 @@
+# CMake Modules Provided by ESMF
+
+The ESMF team provides CMake[1] modules that are useful when ESMF is needed
+within a CMake based build system. These modules can find libraries, create
+targets, and set variables within the scope of a CMake build. They may be
+used as is or customized for application specific build systems. Typically,
+CMake module files are copied into a project and maintained along with the
+project's build system. For more information about installing the provided
+modules see the ESMF User's Guide[2].
+
+Provided modules:
+
+- FindESMF.cmake
+
+### FindESMF.cmake
+
+The FindESMF.cmake module provided by ESMF utilizes a CMake variable,
+named ESMFMKFILE, to locate the esmf.mk file. The esmf.mk file is parsed to locate
+ESMF libraries and create CMake targets for ESMF. If the ESMF library is not
+found then ESMF_FOUND is set to FALSE, a warning is displayed, and find_package
+fails (when REQUIRED is set).
+
+If the ESMFMKFILE variable is not set then FindESMF.cmake will look for an
+environment variable with the same name. If ESMFMKFILE is not set in either
+context then CMake will search default paths, including ESMF_ROOT, for the
+esmf.mk file.
+
+Usage in CMake:
+```
+# Where to look for the FindESMF.cmake file
+#   <PATH_TO_FINDESMF> is to be replaced with the location of FindESMF.cmake
+
+list(APPEND CMAKE_MODULE_PATH "<PATH_TO_FINDESMF>")
+
+# How to locate ESMF libraries and create target
+#   <X.Y.Z> is to be replaced with the minimum version required
+
+find_package(ESMF <X.Y.Z> MODULE REQUIRED)
+
+# How to link targets
+#   <CMAKE_TARGET> is to be replaced with your CMake target
+
+target_link_libraries(<CMAKE_TARGET> PUBLIC ESMF::ESMF)
+```
+
+## Links
+
+- [1] https://cmake.org/cmake/help/book/mastering-cmake/index.html
+- [2] https://earthsystemmodeling.org/doc/

makefile

@@ -337,6 +337,7 @@ endif
 	-@echo "ESMF_INSTALL_LIBDIR:    $(ESMF_INSTALL_LIBDIR)"
 	-@echo "ESMF_INSTALL_BINDIR:    $(ESMF_INSTALL_BINDIR)"
 	-@echo "ESMF_INSTALL_DOCDIR:    $(ESMF_INSTALL_DOCDIR)"
+	-@echo "ESMF_INSTALL_CMAKEDIR:  $(ESMF_INSTALL_CMAKEDIR)"
 	-@echo " "
 	-@echo "--------------------------------------------------------------"
 	-@echo " * ESMF Benchmark directory and parameters *"
@@ -479,6 +480,7 @@ endif
 	-@echo "ESMF_APPSDIR=$(ESMF_APPSDIR)" >> $(MKINFO)
 	-@echo "ESMF_LIBSDIR=$(ESMF_LIBDIR)" >> $(MKINFO)
 	-@echo "ESMF_ESMXDIR=$(ESMF_ESMXDIR)" >> $(MKINFO)
+	-@echo "ESMF_CMAKEDIR=$(ESMF_CMAKEDIR)" >> $(MKINFO)
 	-@echo "" >> $(MKINFO)
 	-@echo "" >> $(MKINFO)
 	-@echo "ESMF_F90COMPILER=$(ESMF_F90COMPILER)" >> $(MKINFO)
@@ -772,7 +774,7 @@ envdump:
 
 # Rewrite esmf.mk during installation to ensure correct installation paths are encoded
 install_info_mk:
-	$(MAKE) info_mk ESMF_APPSDIR=$(ESMF_INSTALL_BINDIR_ABSPATH) ESMF_LDIR=$(ESMF_INSTALL_LIBDIR_ABSPATH) ESMF_LIBDIR=$(ESMF_INSTALL_LIBDIR_ABSPATH) ESMF_ESMXDIR=$(ESMF_INSTALL_HEADERDIR_ABSPATH)/ESMX ESMF_MODDIR=$(ESMF_INSTALL_MODDIR_ABSPATH) ESMF_INCDIR=$(ESMF_INSTALL_HEADERDIR_ABSPATH)
+	$(MAKE) info_mk ESMF_APPSDIR=$(ESMF_INSTALL_BINDIR_ABSPATH) ESMF_LDIR=$(ESMF_INSTALL_LIBDIR_ABSPATH) ESMF_LIBDIR=$(ESMF_INSTALL_LIBDIR_ABSPATH) ESMF_ESMXDIR=$(ESMF_INSTALL_HEADERDIR_ABSPATH)/ESMX ESMF_CMAKEDIR=$(ESMF_INSTALL_CMAKEDIR_ABSPATH) ESMF_MODDIR=$(ESMF_INSTALL_MODDIR_ABSPATH) ESMF_INCDIR=$(ESMF_INSTALL_HEADERDIR_ABSPATH)
 
 # Relink apps during installation to ensure correct shared library location is encoded
 install_apps:
@@ -811,6 +813,8 @@ install: envdump
 	cp -f $(ESMF_BUILD)/src/include/ESMC_*.h $(ESMF_INSTALL_HEADERDIR_ABSPATH)
 	cp -f $(ESMF_DIR)/build_config/$(ESMF_OS).$(ESMF_COMPILER).$(ESMF_SITE)/ESMC_Conf.h $(ESMF_INSTALL_HEADERDIR_ABSPATH)
 	cp -fr $(ESMF_ESMXDIR) $(ESMF_INSTALL_HEADERDIR_ABSPATH)
+	mkdir -p $(ESMF_INSTALL_CMAKEDIR_ABSPATH)
+	cp -f $(ESMF_CMAKEDIR)/*.cmake $(ESMF_INSTALL_CMAKEDIR_ABSPATH)
 	mkdir -p $(ESMF_INSTALL_MODDIR_ABSPATH)
 	cp -f $(ESMF_MODDIR)/*.mod $(ESMF_INSTALL_MODDIR_ABSPATH)
 	mkdir -p $(ESMF_INSTALL_LIBDIR_ABSPATH)

src/doc/ESMF_builddetail.tex

@@ -279,6 +279,8 @@ \subsubsection{Customizing the {\tt build\_rules.mk} fragment}
 \item[ESMF\_INCDIR]
 \item[ESMF\_INSTALL\_BINDIR]
 \item[ESMF\_INSTALL\_BINDIR\_ABSPATH]
+\item[ESMF\_INSTALL\_CMAKEDIR]
+\item[ESMF\_INSTALL\_CMAKEDIR\_ABSPATH]
 \item[ESMF\_INSTALL\_DOCDIR]
 \item[ESMF\_INSTALL\_DOCDIR\_ABSPATH]
 \item[ESMF\_INSTALL\_HEADERDIR]

src/doc/ESMF_install.tex

@@ -959,6 +959,13 @@ \subsection{ESMF Environment Variables}
 location can be specified as absolute path (starting with "/") or relative to
 {\tt ESMF\_INSTALL\_PREFIX}.
 
+\item[ESMF\_INSTALL\_CMAKEDIR]
+Possible value: {\em relative or absolute path}
+
+Location into which to install the CMake module files during installation. This
+location can be specified as absolute path (starting with "/") or relative to
+{\tt ESMF\_INSTALL\_PREFIX}.
+
 \item[ESMF\_INSTALL\_PREFIX]
 Possible value: {\em relative or absolute path}
 
@@ -1322,6 +1329,7 @@ \subsection{Installing the ESMF}
 \item {\tt ESMF\_INSTALL\_MODDIR} -- where to install Fortran module files.
 \item {\tt ESMF\_INSTALL\_BINDIR} -- where to install application files.
 \item {\tt ESMF\_INSTALL\_DOCDIR} -- where to install documentation files.
+\item {\tt ESMF\_INSTALL\_CMAKEDIR} -- where to install cmake module files.
 \end{itemize}
 
 Section~\ref{EnvironmentVariables} describes what each of these

src/doc/ESMF_quickstart.tex

@@ -279,6 +279,7 @@ \subsubsection{make info}
 ESMF_INSTALL_LIBDIR:    lib/libg/Linux.intel.64.mpiuni.default
 ESMF_INSTALL_BINDIR:    bin/bing/Linux.intel.64.mpiuni.default
 ESMF_INSTALL_DOCDIR:    doc
+ESMF_INSTALL_CMAKEDIR:  cmake
  
  
 --------------------------------------------------------------