Reorganize _cet_install() docs for reuse in install_X()

FNALssi · Nov 9, 2023 · 701168f · 701168f
1 parent 5da6442
commit 701168f
Show file tree

Hide file tree

Showing 14 changed files with 168 additions and 89 deletions.
diff --git a/Modules/CetInstall.cmake b/Modules/CetInstall.cmake
@@ -44,98 +44,50 @@ include (ProjectVariable)
    Options
    ^^^^^^^
 
-     .. _p_cet_install-BASENAME_EXCLUDES:
-
-     ``BASENAME_EXCLUDES [[REGEX] <exp>]...``
-       Filenames matching these expressions in any searched subdirectory
-       are excluded from installation; :command:`file(GLOB)
-       <cmake-ref-current:command:file(glob)>` expressions are
-       permitted.
-
-     ``DESTINATION <dest-path>``
-       Installation subdirectory below :variable:`CMAKE_INSTALL_PREFIX
-       <cmake-ref-current:variable:CMAKE_INSTALL_PREFIX>`
-       (mutually-exclusive with ``DEST_VAR``).
-
-     ``DEST_VAR <dest-var>``
-       The name of a CMake variable containing the installation
-       subdirectory (mutually-exclusive with ``DESTINATION``).
-
-     .. _p_cet_install-EXCLUDES:
-
-     ``EXCLUDES [<exclude-exp>...]``
-       A list of paths to exclude from the list of files that would
-       otherwise be installed. This keyword accepts files only: no
-       wildcards or directories
-
-     .. _p_cet_install-opt-LIST:
-
-     ``LIST [<file>...]``
-       A list of files to install. Mutually-exclusive with any option
-       assuming a generated list via :ref:`p_cet_install-_GLOB`,
-       specifically :ref:`p_cet_install-EXCLUDES`,
-       :ref:`p_cet_install-BASENAME_EXCLUDES`,
-       :ref:`p_cet_install-EXTRAS`, and :ref:`p_cet_install-SUBDIRS`,
-
-     .. _p_cet_install-EXTRAS:
-
-     ``EXTRAS [<extra file>...]``
-       TODO.
-
-     ``PROGRAMS``
-       TODO.
-
-     ``SUBDIRNAME <dest-subdir>``
-       TODO.
-
-     .. _p_cet_install-SUBDIRS:
-
-     ``SUBDIRS [<source-subdir>...]``
-       TODO.
+   .. include:: /opts-inc.rst
 
    .. _p_cet_install-meta-options:
 
    Meta-options
    """"""""""""
 
-     ``_EXTRA_BASENAME_EXCLUDES [<basename-exclude-exp>...]``
-       Additional basename exclusion expressions.
+   ``_EXTRA_BASENAME_EXCLUDES [<basename-exclude-exp> ...]``
+     Additional basename exclusion expressions.
 
-     ``_EXTRA_EXCLUDES [<exclude-exp>...]``
-       Additional full-path exclusion expressions.
+   ``_EXTRA_EXCLUDES [<exclude-exp> ...]``
+     Additional full-path exclusion expressions.
 
-     ``_EXTRA_EXTRAS [<path>...]``
-       Files to install in addition to those found via :command:`GLOB
-       <cmake-ref-current:command:file(glob)>` expressions.
+   ``_EXTRA_EXTRAS [<path>...]``
+     Files to install in addition to those found via :command:`GLOB
+     <cmake-ref-current:command:file(glob)>` expressions.
 
-     .. _p_cet_install-_GLOB:
+   .. _p_cet_install-_GLOB:
 
-     ``_GLOBS [<file(glob)>...]``
-       \ :command:`GLOB <cmake-ref-current:command:file(glob)>`
-       expressions for files to include.
+   ``_GLOBS [<file(glob)>...]``
+     \ :command:`GLOB <cmake-ref-current:command:file(glob)>`
+     expressions for files to include.
 
-     ``_INSTALLED_FILES_VAR <var>``
-       The name of a variable in which to stored the full list of files
-       installed.
+   ``_INSTALLED_FILES_VAR <var>``
+     The name of a variable in which to stored the full list of files
+     installed.
 
-     ``_INSTALL_ONLY``
-       Do not copy files to the build tree.
+   ``_INSTALL_ONLY``
+     Do not copy files to the build tree.
 
-     ``_LIST_ONLY``
-       Disable globbing: enforce explicit lists of files to install via
-       :ref:`LIST <p_cet_install-opt-LIST>`.
+   ``_LIST_ONLY``
+     Disable globbing: enforce explicit lists of files to install via
+     :ref:`LIST <p_cet_install-opt-LIST>`.
 
-     ``_NO_LIST``
-       Disallow the use of :ref:`LIST <p_cet_install-opt-LIST>`.
+   ``_NO_LIST``
+     Disallow the use of :ref:`LIST <p_cet_install-opt-LIST>`.
 
-     ``_SEARCH_BUILD``
-       :command:`GLOB <cmake-ref-current:command:file(glob)>`
-       expressions will be applied to the build tree in addition to the
-       source tree.
+   ``_SEARCH_BUILD``
+     :command:`GLOB <cmake-ref-current:command:file(glob)>` expressions
+     will be applied to the build tree in addition to the source tree.
 
-     ``_SQUASH_SUBDIRS``
-       Subdirectory elements of source files are ignored when
-       calculating the copy/install destination.
+   ``_SQUASH_SUBDIRS``
+     Subdirectory elements of source files are ignored when calculating
+     the copy/install destination.
 
    Details
    ^^^^^^^
@@ -151,6 +103,7 @@ include (ProjectVariable)
       :command:`file(GLOB) <cmake-ref-current:command:file(glob)>` to
       generate targets is not CMake best practice, and may lead to
       hysteresis if looking for generated files in the build tree.
+
 #]============================================================]
 
 # Copy all files (or PROGRAMS) found matching provided glob expressions

diff --git a/Modules/InstallFW.cmake b/Modules/InstallFW.cmake
@@ -1,16 +1,14 @@
 #[================================================================[.rst:
-X
--
+InstallFW
+---------
+
+.. admonition:: HEP
+   .. rst-class:: admonition-app
+
+   Define the function :command:`install_fw` to install HEP framework
+   data files.
+
 #]================================================================]
-########################################################################
-# install_fw()
-#
-#   Install FW data in ${${CETMODULES_CURRENT_PROJECT_NAME}_FW_DIR}/<subdir>
-#
-# Usage: install_wp([SUBDIRNAME <subdir>] LIST ...)
-#
-# See CetInstall.cmake for full usage description.
-########################################################################
 
 # Avoid unwanted repeat inclusion.
 include_guard()
@@ -20,6 +18,22 @@ cmake_minimum_required(VERSION 3.18.2...3.27 FATAL_ERROR)
 include(CetInstall)
 include(ProjectVariable)
 
+#[================================================================[.rst:
+.. command:: install_fw
+
+   .. admonition:: HEP
+      .. rst-class:: admonition-app
+
+      Install HEP framework data files.
+
+      .. seealso:: :variable:`<PROJECT-NAME>_FW_DIR`.
+
+      .. code-block:: cmake
+
+         install_fw()
+
+#]================================================================]
+
 function(install_fw)
   project_variable(FW_DIR CONFIG NO_WARN_DUPLICATE
     OMIT_IF_EMPTY OMIT_IF_MISSING OMIT_IF_NULL

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -2,6 +2,29 @@ include(CetGenerateSphinxDocs)
 
 find_package(M4 REQUIRED)
 
+function(_generate_cet_install_opts_inc)
+  set(cet_install_opts_dir "${doc_root}/reference/_cet_install_opts")
+
+  add_custom_command(OUTPUT "${doc_root}/reference/opts-inc.rst"
+    COMMAND M4::M4
+    -Dm4src="${doc_root}/reference/_cet_install_opts"
+    "${CMAKE_CURRENT_SOURCE_DIR}/reference/opts-inc.rst.m4"
+    > "${doc_root}/reference/opts-inc.rst"
+    DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/reference/opts-inc.rst.m4"
+    "${cet_install_opts_dir}/BASENAME_EXCLUDES.rst"
+    "${cet_install_opts_dir}/DESTINATION.rst"
+    "${cet_install_opts_dir}/DEST_VAR.rst"
+    "${cet_install_opts_dir}/EXCLUDES.rst"
+    "${cet_install_opts_dir}/EXTRAS.rst"
+    "${cet_install_opts_dir}/LIST.rst"
+    "${cet_install_opts_dir}/PROGRAMS.rst"
+    "${cet_install_opts_dir}/SUBDIRNAME.rst"
+    "${cet_install_opts_dir}/SUBDIRS.rst"
+    VERBATIM
+    COMMENT "Generating ${doc_root}/reference/opts-inc.rst with m4"
+  )
+endfunction()
+
 function(_generate_reference)
   set(source_root "${CMAKE_CURRENT_BINARY_DIR}/gen/install")
   set(doc_root "${source_root}/doc")
@@ -31,6 +54,8 @@ function(_generate_reference)
     COMMENT "Generating ${doc_root}/reference/index.rst with m4"
   )
 
+  _generate_cet_install_opts_inc()
+
   # Generate documentation for installation with this package.
   file(READ "${CMAKE_CURRENT_SOURCE_DIR}/reference-conf.py.in" ref_conf)
   string(CONFIGURE "\
@@ -47,7 +72,9 @@ ${ref_conf}
     CONF_DIR "${CMAKE_CURRENT_BINARY_DIR}"
     EXTRA_ARGS ${cetmodules_SPHINX_DOC_EXTRA_ARGS}
     html_EXTRA_ARGS ${cetmodules_SPHINX_DOC_html_EXTRA_ARGS}
-    DEPENDS "${doc_root}/reference/index.rst" "${doc_root}/cetmodules-common.rst"
+    DEPENDS "${doc_root}/reference/index.rst"
+    "${doc_root}/cetmodules-common.rst"
+    "${doc_root}/reference/opts-inc.rst"
     TARGETS_VAR reference_html_target
   )
 
@@ -101,6 +128,9 @@ function(_publish_to_root)
     VERBATIM
     COMMENT "Generating ${doc_root}/reference/index.rst with m4"
   )
+
+  _generate_cet_install_opts_inc()
+
   file(READ "${CMAKE_CURRENT_SOURCE_DIR}/reference-conf.py.in" ref_conf)
   string(CONFIGURE "\
 ${COMMON_CONF}
@@ -126,7 +156,9 @@ ${ref_conf}
     CONF_DIR "${CMAKE_CURRENT_BINARY_DIR}/reference"
     EXTRA_ARGS ${cetmodules_SPHINX_DOC_EXTRA_ARGS}
     html_EXTRA_ARGS ${cetmodules_SPHINX_DOC_html_EXTRA_ARGS}
-    DEPENDS "${doc_root}/reference/index.rst" "${doc_root}/cetmodules-common.rst"
+    DEPENDS "${doc_root}/reference/index.rst"
+    "${doc_root}/cetmodules-common.rst"
+    "${doc_root}/reference/opts-inc.rst"
     TARGETS_VAR publish_ref_target
   )
   add_custom_command(OUTPUT "${doc_root}/landing/index.rst"
@@ -212,6 +244,7 @@ endfunction()
 
 function(_symlink_reference_to DEST)
   foreach(item IN ITEMS
+      _cet_install_opts
       envvar
       manual
       module

diff --git a/doc/reference/_cet_install_opts/BASENAME_EXCLUDES.rst b/doc/reference/_cet_install_opts/BASENAME_EXCLUDES.rst
@@ -0,0 +1,4 @@
+   ``BASENAME_EXCLUDES [[REGEX] <exp>] ...``
+     Filenames matching these expressions in any searched subdirectory
+     are excluded from installation; :command:`file(GLOB)
+     <cmake-ref-current:command:file(glob)>` expressions are permitted.
diff --git a/doc/reference/_cet_install_opts/DESTINATION.rst b/doc/reference/_cet_install_opts/DESTINATION.rst
@@ -0,0 +1,4 @@
+   ``DESTINATION <dest-path>``
+     Installation subdirectory below :variable:`CMAKE_INSTALL_PREFIX
+     <cmake-ref-current:variable:CMAKE_INSTALL_PREFIX>`
+     (mutually-exclusive with ``DEST_VAR``).
diff --git a/doc/reference/_cet_install_opts/DEST_VAR.rst b/doc/reference/_cet_install_opts/DEST_VAR.rst
@@ -0,0 +1,3 @@
+   ``DEST_VAR <dest-var>``
+     The name of a CMake variable containing the installation
+     subdirectory (mutually-exclusive with ``DESTINATION``).
diff --git a/doc/reference/_cet_install_opts/EXCLUDES.rst b/doc/reference/_cet_install_opts/EXCLUDES.rst
@@ -0,0 +1,4 @@
+   ``EXCLUDES [<exclude-exp> ...]``
+     A list of paths to exclude from the list of files that would
+     otherwise be installed. This keyword accepts files only: no
+     wildcards or directories
diff --git a/doc/reference/_cet_install_opts/EXTRAS.rst b/doc/reference/_cet_install_opts/EXTRAS.rst
@@ -0,0 +1,5 @@
+   ``EXTRAS [<extra file> ...]``
+     Specific files to copy/install in addition to those found via
+     :command:`GLOB <cmake-ref-current:command:file(glob)>`\
+     ing—incompatible with :ref:`p_cet_install-opt-LIST`.
+
diff --git a/doc/reference/_cet_install_opts/LIST.rst b/doc/reference/_cet_install_opts/LIST.rst
@@ -0,0 +1,7 @@
+   ``LIST [<file> ...]``
+     A list of files to install. Mutually-exclusive with any option
+     assuming a generated list via :ref:`p_cet_install-_GLOB`,
+     specifically :ref:`p_cet_install-EXCLUDES`,
+     :ref:`p_cet_install-BASENAME_EXCLUDES`,
+     :ref:`p_cet_install-EXTRAS`, and :ref:`p_cet_install-SUBDIRS`,
+
diff --git a/doc/reference/_cet_install_opts/PROGRAMS.rst b/doc/reference/_cet_install_opts/PROGRAMS.rst
@@ -0,0 +1,8 @@
+   ``PROGRAMS``
+     All files will be treated as executables and their mode will be set
+     accordingly upon copy and/or install.
+
+     .. seealso:: :command:`cet_copy`,
+                  :external+cmake-ref-current:ref:`install(PROGRAMS
+                  ...)  <install(programs)>`, :manpage:`chmod(1)`.
+
diff --git a/doc/reference/_cet_install_opts/SUBDIRNAME.rst b/doc/reference/_cet_install_opts/SUBDIRNAME.rst
@@ -0,0 +1,3 @@
+   ``SUBDIRNAME <dest-subdir>``
+     Add ``<dest-subdir>`` to the destination path.
+
diff --git a/doc/reference/_cet_install_opts/SUBDIRS.rst b/doc/reference/_cet_install_opts/SUBDIRS.rst
@@ -0,0 +1,4 @@
+   ``SUBDIRS [<source-subdir> ...]``
+     Install files from the specified ``<source-subdir> ...``;
+     incompatible with :ref:`p_cet_install-opt-LIST`.
+
diff --git a/doc/reference/manual/cetmodules-commands.7.rst b/doc/reference/manual/cetmodules-commands.7.rst
@@ -36,7 +36,16 @@ Generation, Installation, and Export
 * :command:`cet_register_export_set`
 * :command:`cet_script`
 * :command:`cet_test`
+* :command:`install_fw`
+* :command:`install_fhicl`
+* :command:`install_gdml`
+* :command:`install_headers`
+* :command:`install_perllib`
 * :command:`install_pkgmeta`
+* :command:`install_python`
+* :command:`install_scripts`
+* :command:`install_source`
+* :command:`install_wp`
 * :command:`ParseAndAddCatchTests`
 * :command:`process_smc`
 

diff --git a/doc/reference/opts-inc.rst.m4 b/doc/reference/opts-inc.rst.m4
@@ -0,0 +1,28 @@
+changequote([,])dnl
+   .. _p_cet_install-BASENAME_EXCLUDES:
+
+esyscmd([cat ]m4src[/BASENAME_EXCLUDES.rst])dnl
+
+esyscmd([cat ]m4src[/DESTINATION.rst])dnl
+
+esyscmd([cat ]m4src[/DEST_VAR.rst])dnl
+
+   .. _p_cet_install-EXCLUDES:
+
+esyscmd([cat ]m4src[/EXCLUDES.rst])dnl
+
+   .. _p_cet_install-opt-LIST:
+
+esyscmd([cat ]m4src[/LIST.rst])dnl
+
+   .. _p_cet_install-EXTRAS:
+
+esyscmd([cat ]m4src[/EXTRAS.rst])dnl
+
+esyscmd([cat ]m4src[/PROGRAMS.rst])dnl
+
+esyscmd([cat ]m4src[/SUBDIRNAME.rst])dnl
+
+   .. _p_cet_install-SUBDIRS:
+
+esyscmd([cat ]m4src[/SUBDIRS.rst])dnl
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		``SUBDIRNAME <dest-subdir>``
		Add ``<dest-subdir>`` to the destination path.