From 3ce4dcbd3ca9eaaeb85f17c6861de23f2b856855 Mon Sep 17 00:00:00 2001 From: "Roscoe A. Bartlett" Date: Tue, 18 Jul 2023 14:10:30 -0600 Subject: [PATCH] Rename function and improve documentation (#582) This makes the documentation ad code a little more clear. As part of this, I renamed the function `tribits_write_package_client_export_files_install_targets()` to ` tribits_write_package_client_export_files_export_and_install_targets()`. That makes it a little more clear what these functions are doing. --- ...ribitsInternalPackageWriteConfigFile.cmake | 60 +++++++++++-------- .../TribitsSystemMacroFunctionDocTemplate.rst | 2 +- 2 files changed, 37 insertions(+), 25 deletions(-) diff --git a/tribits/core/package_arch/TribitsInternalPackageWriteConfigFile.cmake b/tribits/core/package_arch/TribitsInternalPackageWriteConfigFile.cmake index 7d3c1bb68..e820d6222 100644 --- a/tribits/core/package_arch/TribitsInternalPackageWriteConfigFile.cmake +++ b/tribits/core/package_arch/TribitsInternalPackageWriteConfigFile.cmake @@ -84,12 +84,12 @@ function(tribits_write_package_client_export_files PACKAGE_NAME) tribits_write_flexible_package_client_export_files(${EXPORT_FILES_ARGS}) - tribits_write_package_client_export_files_install_targets(${EXPORT_FILES_ARGS}) + tribits_write_package_client_export_files_export_and_install_targets(${EXPORT_FILES_ARGS}) endfunction() -# @FUNCTION: tribits_write_package_client_export_files_install_targets() +# @FUNCTION: tribits_write_package_client_export_files_export_and_install_targets() # # Create the ``ConfigTargets.cmake`` file and install rules and the # install() target for the previously generated @@ -98,7 +98,7 @@ endfunction() # # Usage:: # -# tribits_write_package_client_export_files_install_targets( +# tribits_write_package_client_export_files_export_and_install_targets( # PACKAGE_NAME # PACKAGE_CONFIG_FOR_BUILD_BASE_DIR # PACKAGE_CONFIG_FOR_INSTALL_BASE_DIR @@ -107,7 +107,7 @@ endfunction() # The install() commands must be in a different subroutine or CMake will not # allow you to call the routine, even if you if() it out! # -function(tribits_write_package_client_export_files_install_targets) +function(tribits_write_package_client_export_files_export_and_install_targets) cmake_parse_arguments( #prefix @@ -333,10 +333,10 @@ endfunction() # @FUNCTION: tribits_write_flexible_package_client_export_files() # -# Utility function for writing ``${PACKAGE_NAME}Config.cmake`` files for -# package ``${PACKAGE_NAME}`` with some greater flexibility than what is -# provided by the function ``tribits_write_package_client_export_files()`` and -# to allow unit testing the generation of these files.. +# Utility function for writing the ``${PACKAGE_NAME}Config.cmake`` files for +# the build dir and/or for the install dir for the package ```` +# with some flexibility . (See NOTE below for what is actually generated and +# what is *NOT* generated.) # # Usage:: # @@ -352,7 +352,8 @@ endfunction() # ``PACKAGE_NAME `` # # Gives the name of the TriBITS package for which the export files should -# be created. +# be created. (This must match the export set for the libraries for the +# generated/exported ``ConfigTargets.cmake`` file.) # # ``EXPORT_FILE_VAR_PREFIX `` # @@ -362,28 +363,39 @@ endfunction() # # ``PACKAGE_CONFIG_FOR_BUILD_BASE_DIR `` # -# If specified, then the package's ``Config.cmake`` file and -# supporting files will be written under the directory -# ``/`` (and any subdirs that does exist -# will be created). The generated file ``Config.cmake`` is -# for usage of the package in the build tree (not the install tree) and -# points to include directories and libraries in the build tree. +# If specified, then the package's ``Config.cmake`` file will +# be written under the directory ``/`` (and +# any subdirs that do not exist will be created). The generated file +# ``Config.cmake`` is for usage of the package in the build +# tree (not the install tree) and points to include directories and +# libraries in the build tree. (NOTE: The included +# ``Targets.cmake`` file is *NOT* generated in this +# function.) # # ``PACKAGE_CONFIG_FOR_INSTALL_BASE_DIR `` # # If specified, then the package's ``Config_install.cmake`` -# file and supporting files will be written under the directory -# ``/`` (and any subdirs that does exist +# file will be written under the directory +# ``/`` (and any subdirs that do not exist # will be created). The file ``${PACKAGE_NAME}Config_install.cmake`` is # meant to be installed renamed as ``Config.cmake`` in the # install tree and it points to installed include directories and -# libraries. -# -# NOTE: This function does *not* contain any ``install()`` command itself -# because CMake will not allow those to even be present in scripting mode that -# is used for unit testing this function. Instead, the commands to install -# the files are added by the function -# ``tribits_write_package_client_export_files_install_targets()``. +# libraries. (NOTE: The included ``Targets.cmake`` +# file is *NOT* generated in this function.) +# +# NOTE: This function does *not* generate the ``Config.cmake`` +# files (which will be created later using ``export()`` or ``include()`) which +# are included in these generated package config files and this function. +# Also, this function does *not* invoke the ``install()`` command to install +# the package config file for the install directory. The ``export()`` and +# ``install()`` project commands are bot allowed in `cmake -P` scripting mode +# that is used for unit testing this function. Instead, the commands to +# generate the ``Targets.cmake`` files and install the package +# config file for the install tree are produced by the function +# ``tribits_write_package_client_export_files_export_and_install_targets()`` +# which is called after this function. This allows this function +# ``tribits_write_package_client_export_files()`` to be run in unit testing +# with a `cmake -P` script. # function(tribits_write_flexible_package_client_export_files) diff --git a/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst b/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst index a2fdb71c9..3723c3b7c 100644 --- a/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst +++ b/tribits/doc/guides/TribitsSystemMacroFunctionDocTemplate.rst @@ -51,6 +51,6 @@ understand the internals of TriBITS. @MACRO: tribits_save_off_dependency_vars() + @MACRO: tribits_set_dep_packages() + @FUNCTION: tribits_trace_file_processing() + -@FUNCTION: tribits_write_package_client_export_files_install_targets() + +@FUNCTION: tribits_write_package_client_export_files_export_and_install_targets() + @MACRO: tribits_write_xml_dependency_files() + @FUNCTION: tribits_write_xml_dependency_files_if_supported() +