Add/update documentation for TriBITS TPLs (#299)

I did several things here:

* Updated howto for creating TriBITS FindTPL<tplName>.cmake files to cover all
  cases with more examples.  This also covers the new function
  tribits_external_package_create_imported_all_libs_target_and_config_file()

* Changed section name from "Addtional Topics" to "Miscellaneous Topics"

* Changes section name from "TriBITS TPL" to "TriBITS External Package/TPL"
  but provided anchor `TriBITS TPL`_ so I did not have to update all of the
  references.

* Provided subsections for TriBITS External Package/TPL files and variables

* Moved detailed material on tricky aspects of find_package() and
  <tplName>Config.cmake files to a new section "Tricky considerations for
  TriBITS-generated <tplName>Config.cmake files".

* Added references to documentation for the functions in the module
  TribitsExternalPackageWriteConfigFile.cmake.

tribits/core/package_arch/TribitsExternalPackageFindTplHelpers.cmake

@@ -64,6 +64,9 @@
 # ``find_dependency(<externalPkg>)`` (with no other argument) and then, again,
 # defines the correct imported library dependency.
 #
+# For more details, see `Creating FindTPL*.cmake using find_package() with
+# IMPORTED targets`_.
+#
 function(tribits_external_package_create_imported_all_libs_target_and_config_file
     tplName
   )

tribits/core/package_arch/TribitsExternalPackageWriteConfigFile.cmake

@@ -61,9 +61,9 @@ cmake_policy(SET CMP0057 NEW) # Support if ( ... IN_LIST ... )
 #   ``<tplConfigFile>``: Full file path for the ``<tplName>Config.cmake``
 #   file that will be written out.
 #
-# This function just calls
-# ``tribits_external_package_write_config_file_str()`` and writes that text to
-# the file ``<tplConfigFile>`` so see that function for more details.
+# This function just calls `tribits_external_package_write_config_file_str()`_
+# and writes that text to the file ``<tplConfigFile>`` so see that function
+# for more details.
 #
 function(tribits_external_package_write_config_file  tplName  tplConfigFile)
   tribits_external_package_write_config_file_str(${tplName} tplConfigFileStr)
@@ -172,30 +172,81 @@ endfunction()
 #   tribits_external_package_write_config_file_str(
 #     <tplName> <tplConfigFileStrOut> )
 #
-# The arguments are:
+# The function arguments are:
 #
 #   ``<tplName>``: Name of the external package/TPL
 #
 #   ``<tplConfigFileStrOut>``: Name of variable that will contain the string
 #   for the config file on output.
 #
-# This function reads from the variables ``TPL_<tplName>_INCLUDE_DIRS``
-# ``TPL_<tplName>_LIBRARIES``, and ``<tplName>_LIB_ENABLED_DEPENDENCIES``
+# This function reads from the (cache) variables
+#
+#   * ``TPL_<tplName>_INCLUDE_DIRS``
+#   * ``TPL_<tplName>_LIBRARIES``
+#   * ``<tplName>_LIB_ENABLED_DEPENDENCIES``
+#
 # (which must already be set) and uses that information to produce the
 # contents of the ``<tplName>Config.cmake`` which is returned as a string
 # variable that contains IMPORTED targets to represent these libraries and
 # include directories as well as ``find_dependency()`` calls for upstream
-# packages listed in ``<tplName>_LIB_ENABLED_DEPENDENCIES``
+# packages listed in ``<tplName>_LIB_ENABLED_DEPENDENCIES``.
+#
+# The arguments in ``TPL_<tplName>_LIBRARIES`` are handled in special ways in
+# order to create the namespaced IMPORTED targets ``<tplName>::<libname>`` and
+# the ``<tplName>::all_libs`` target that depends on these.  The types of
+# arguments that are handled and how the are interpreted:
+#
+#   ``<abs-base-path>/[lib]<libname>.<longest-ext>``
+#
+#     Arguments that are absolute file paths are treated as libraries and an
+#     imported target name ``<libname>`` is derived from the file name (of the
+#     form ``lib<libname>.<longest-ext>`` removing beginning ``lib`` and file
+#     extension ``.<longest-ext>``).  The IMPORTED target
+#     ``<tplName>::<libname>`` is created and the file path is set using the
+#     ``IMPORTED_LOCATION`` target property.
+#
+#   ``-l<libname>``
+#
+#     Arguments of the form ``-l<libname>`` are used to create IMPORTED
+#     targets with the name ``<tplName>::<libname>`` using the
+#     ``IMPORTED_LIBNAME`` target property.
+#
+#   ``<libname>``
+#
+#     Arguments that are a raw name that matches the regex
+#     ``^[a-zA-Z_][a-zA-Z0-9_-]*$`` are interpreted to be a library name
+#     ``<libname>`` and is used to create an IMPORTED targets
+#     ``<tplName>::<libname>`` using the ``IMPORTED_LIBNAME`` target property.
+#
+#   ``-L<dir>``
+#
+#     Link directories.  These are pulled off and added to the
+#     ``<tplName>::all_libs`` using ``target_link_options()``.  (The order of
+#     these options is maintained.)
+#
+#   ``-<any-option>``
+#
+#     Any other option that starts with ``-`` is assumed to
+#     be a link argument where the order does not matter in relation to the
+#     libraries (but the order of these extra options are maintained w.r.t. each
+#     other).
+#
+#   ``<unrecognized>``
+#
+#     Any other argument that does not match one of the above patterns is
+#     regarded as an error.
 #
-# ToDo: Flesh out more documentation for behavior as more features are added
-# for handling:
+# For more details on the handling of individual ``TPL_<tplName>_LIBRARIES``
+# arguments, see `tribits_tpl_libraries_entry_type()`_.
 #
-# * ``TPL_<tplName>_LIBRARIES`` containing ``-l`` and ``-L`` arguments ...
+# The list of directories given in ``TPL_<tplName>_INCLUDE_DIRS`` is added to
+# the ``<tplName>::all_libs`` target using ``target_include_directories()``.
 #
-# * ``TPL_<tplName>_LIBRARIES`` containing arguments other than library files
-# * or ``-l`` and ``-L`` arguments and files.
+# Finally, for every ``<upstreamTplName>`` listed in
+# ``<tplName>_LIB_ENABLED_DEPENDENCIES``, a link dependency is created using
+# ``target_link_library(<tplName>::all_libs INTERFACE <upstreamTplName>)``.
 #
-function(tribits_external_package_write_config_file_str tplName tplConfigFileStrOut)
+function(tribits_external_package_write_config_file_str  tplName  tplConfigFileStrOut)
 
   # A) Set up beginning of config file text
   set(configFileStr "")
@@ -402,30 +453,36 @@ function(tribits_external_package_process_libraries_list  tplName)
 endfunction()
 
 
+# @FUNCTION: tribits_tpl_libraries_entry_type()
+#
 # Returns the type of the library entry in the list TPL_<tplName>_LIBRARIES
 #
+# Usage::
+#
+#   tribits_tpl_libraries_entry_type(<libentry>  <libEntryTypeOut>)
+#
 # Arguments:
 #
-#   ``libentry`` [in]: Element of ``TPL_<tplName>_LIBRARIES``
+#   ``<libentry>`` [in]: Element of ``TPL_<tplName>_LIBRARIES``
 #
-#   ``libEntryTypeOut`` [out]: Variable set on output to the type of entry.
+#   ``<libEntryTypeOut>`` [out]: Variable set on output to the type of entry.
 #
 # The types of entries set on ``libEntryTypeOut`` include:
 #
-#   ``FULL_LIB_PATH``: A full library path
+#   * ``FULL_LIB_PATH``: A full library path
 #
-#   ``LIB_NAME_LINK_OPTION``: A library name link option of the form
-#   ``-l<libname>``
+#   * ``LIB_NAME_LINK_OPTION``: A library name link option of the form
+#     ``-l<libname>``
 #
-#   ``LIB_NAME``: A library name of the form ``<libname>``
+#   * ``LIB_NAME``: A library name of the form ``<libname>``
 #
-#   ``LIB_DIR_LINK_OPTION``: A library directory search option of the form
-#   ``-L<dir>``
+#   * ``LIB_DIR_LINK_OPTION``: A library directory search option of the form
+#     ``-L<dir>``
 #
-#   ``GENERAL_LINK_OPTION``: Some other general link option that starts with
-#   ``-`` but is not ``-l`` or ``-L``.
+#   * ``GENERAL_LINK_OPTION``: Some other general link option that starts with
+#     ``-`` but is not ``-l`` or ``-L``.
 #
-#   ``UNSUPPORTED_LIB_ENTRY``: An unsupported lib option
+#   * ``UNSUPPORTED_LIB_ENTRY``: An unsupported lib option
 #
 function(tribits_tpl_libraries_entry_type  libentry  libEntryTypeOut)
   string(SUBSTRING "${libentry}" 0 1 firstCharLibEntry)

tribits/core/package_arch/TribitsTplFindIncludeDirsAndLibraries.cmake

@@ -99,8 +99,9 @@ include(Split)
 # to disable the prefind call to ``find_package()`` even if it would be
 # allowed otherwise.
 #
-# See `How to use find_package() for a TriBITS TPL`_ for details in how to use
-# this function to create a ``FindTPL<tplName>.cmake`` module file.
+# See `Creating FindTPL*.cmake using find_package() without IMPORTED targets`_
+# for details in how to use this function to create a
+# ``FindTPL<tplName>.cmake`` module file.
 #
 function(tribits_tpl_allow_pre_find_package  TPL_NAME  ALLOW_PACKAGE_PREFIND_OUT)
 
@@ -157,10 +158,12 @@ endfunction()
 
 # @FUNCTION: tribits_tpl_find_include_dirs_and_libraries()
 #
-# Function that sets up cache variables for users to specify where to find a
-# `TriBITS TPL`_'s headers and libraries.  This function is typically called
-# inside of a ``FindTPL<tplName>.cmake`` module file (see
-# `${TPL_NAME}_FINDMOD`_).
+# This function reads (cache) variables that specify where to find a `TriBITS
+# TPL`_'s headers and libraries and then creates IMPORTED targets, the
+# ``<tplName>::all_libs`` target, and writes the file
+# ``<tplName>Config.cmake`` into the standard location in the build directory.
+# This function is typically called inside of a ``FindTPL<tplName>.cmake``
+# module file (see `${TPL_NAME}_FINDMOD`_).
 #
 # Usage::
 #
@@ -190,22 +193,23 @@ endfunction()
 #   ``MUST_FIND_ALL_HEADERS``
 #
 #     If set, then all of the header files listed in ``REQUIRED_HEADERS`` must
-#     be found in order for ``TPL_<tplName>_INCLUDE_DIRS`` to be defined.
+#     be found (unless ``TPL_<tplName>_INCLUDE_DIRS`` is already set).
 #
 #   ``REQUIRED_LIBS_NAMES``
 #
 #     List of libraries that are searched for when looking for the TPL's
 #     libraries using ``find_library()``.  This list can be overridden by the
-#     user by setting ``<tplName>_LIBRARY_DIRS`` (see below).
+#     user by setting ``<tplName>_LIBRARY_NAMES`` (see below).
 #
 #   ``MUST_FIND_ALL_LIBS``
 #
 #     If set, then all of the library files listed in ``REQUIRED_LIBS_NAMES``
-#     must be found or the TPL is considered not found!  If the global cache
-#     var ``<Project>_MUST_FIND_ALL_TPL_LIBS`` is set to ``TRUE``, then this
-#     is turned on as well.  WARNING: The default is not to require finding
-#     all of the listed libs.  This is to maintain backward compatibility with
-#     some older ``FindTPL<tplName>.cmake`` modules.
+#     must be found or the TPL is considered not found (unless
+#     ``TPL_<tplName>_LIBRARIES`` is already set).  If the global cache var
+#     ``<Project>_MUST_FIND_ALL_TPL_LIBS`` is set to ``TRUE``, then this is
+#     turned on as well.  WARNING: The default is not to require finding all
+#     of the listed libs.  (This is to maintain backward compatibility with
+#     some older ``FindTPL<tplName>.cmake`` modules.)
 #
 #   ``NO_PRINT_ENABLE_SUCCESS_FAIL``
 #
@@ -214,50 +218,69 @@ endfunction()
 # This function implements the TPL find behavior described in `Enabling
 # support for an optional Third-Party Library (TPL)`_.
 #
-# The following (cache) variables, if set, will be used by that this function:
+# The following (cache) variables, if set, will be used by this function:
 #
 #   ``<tplName>_INCLUDE_DIRS`` (type ``PATH``)
 #
 #     List of paths to search first for header files defined in
-#     ``REQUIRED_HEADERS``.
+#     ``REQUIRED_HEADERS <header1> <header2> ...``.
 #
 #   ``<tplName>_LIBRARY_DIRS`` (type ``PATH``)
 #
 #     The list of directories to search first for libraries defined in
-#     ``REQUIRED_LIBS_NAMES``.  If, for some reason, no libraries should be
-#     linked in for this particular configuration, then setting
-#     ``<tplName>_LIBRARY_DIRS=OFF`` will 
+#     ``REQUIRED_LIBS_NAMES <libname1> <libname2> ...``.  If, for some reason,
+#     no libraries should be linked in for this particular configuration, then
+#     setting ``<tplName>_LIBRARY_DIRS=OFF`` or is empty will no special paths
+#     will be searched.
 #
 #   ``<tplName>_LIBRARY_NAMES`` (type ``STRING``)
 #
 #     List of library names to be looked for instead of what is specified in
-#     ``REQUIRED_LIBS_NAMES``.
+#     ``REQUIRED_LIBS_NAMES <libname1> <libname2> ...``.
 #
-# This function sets global variables to return state so it can be called from
-# anywhere in the call stack.  The following cache variables are defined that
-# are intended for the user to set and/or use:
+#   ``<tplName>_LIB_ENABLED_DEPENDENCIES``
+#
+#     List of direct upstream external package/TPL dependencies that also
+#     define ``<upstreamTplName>::all_libs`` targets.
+#
+# An addition, the function will avoid calling the find operations if the
+# following (cache) variables are set on input:
 #
 #   ``TPL_<tplName>_INCLUDE_DIRS`` (type ``PATH``)
 #
 #     A list of common-separated full directory paths that contain the TPL's
-#     header files.  If this variable is set before calling this function,
-#     then no headers are searched for and this variable will be assumed to
-#     have the correct list of header paths.
+#     header files.
 #
 #   ``TPL_<tplName>_LIBRARIES`` (type ``FILEPATH``)
 #
 #     A list of commons-separated full library names (i.e. output from
-#     ``find_library()``) for all of the libraries found for the TPL.  If this
-#     variable is set before calling this function, then no libraries are
-#     searched for and this variable will be assumed to have the correct list
-#     of libraries to link to.
+#     ``find_library()``) for all of the libraries for the TPL.
+#
+# This function produces the following:
 #
 #   ``TPL_<tplName>_NOT_FOUND`` (type ``BOOL``)
 #
 #     Will be set to ``ON`` if all of the parts of the TPL could not be found.
 #
-# ToDo: Document the behavior of this function for finding headers and
-# libraries and when a find is successful and when it is not.
+#   ``<tplName>::<libname>``
+#
+#     Namespaced IMPORTED target for every library found or specified in
+#     ``TPL_<tplName>_LIBRARIES``.  These IMPORTED targets will have the
+#     ``<upstreamTplName>::all_libs`` for the upstream external packages/TPLs
+#     listed in ``<tplName>_LIB_ENABLED_DEPENDENCIES``.
+#
+#   ``<tplName>::all_libs``
+#
+#     INTERFACE target that depends on all of the created IMPORTED targets.
+#
+#   ``<buildDir>/external_packages/<tplName>/<tplName>Config.cmake``
+#
+#     A package configure file that contains all of the generated IMPORTED
+#     targets ``<tplName>::<libname>`` and the ``<tplName>::all_libs`` target.
+#     This fill will also call ``find_dependency()`` to pull in
+#     ``<upstreamTplName>Config.cmake`` files for upstream TPLs that are
+#     listed in ``<tplName>_LIB_ENABLED_DEPENDENCIES``.  (For more
+#     information, see `tribits_external_package_write_config_file()`_.)
 #
 # Note, if ``TPL_TENTATIVE_ENABLE_<tplName>=ON``, then if all of the parts of
 # the TPL can't be found, then ``TPL_ENABLE_<tplName>`` will be (forced) set
@@ -358,7 +381,7 @@ function(tribits_tpl_find_include_dirs_and_libraries TPL_NAME)
 
   else()
 
-    set(${TPL_NAME}_LIBRARY_DIRS) # Just to ignore below!
+    set(${TPL_NAME}_LIBRARY_DIRS "") # Just to ignore below!
 
   endif()