Skip to content

Commit

Permalink
Add documentation for TriBITS-compliant external packages TRIBITS_PKG (…
Browse files Browse the repository at this point in the history 
…TriBITSPub#63)

* Documented special value of `TRIBITS_PKG` for the FINDMOD proeprty

* Updated some surrounding existing documentation to improve it some.

* Updated howto "How to add a new TriBITS external package/TPL" to mention
  `TRIBITS_PKG` and not needing the `FindTpl<tplName>.cmake` file in that
  case.

* Documented how support for dependencies for TriBITS-compliant external
  packages listed in the TPLsList.cmake file with `TRIBITS_PKG` would be
  handled (e.g. `TRIBITS_PKG:<path-to-dir-or-file>`).  This is currently
  speculative since there are not tests and no implementation for this yet.
  But it seemed best to document this while I was thinking about this.
  • Loading branch information
@bartlettroscoe
bartlettroscoe committed Feb 21, 2023
1 parent 2bcc17f commit 68c83ef
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 87 deletions.
98 changes: 46 additions & 52 deletions tribits/core/package_arch/TribitsProcessTplsLists.cmake
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ include(Split)

# @MACRO: tribits_repository_define_tpls()
#
# Define the list of `TriBITS TPLs`_ (external packages) for a given `TriBITS
# Repository`_ which includes the TPL name, find module, and classification .
# This macro is typically called from inside of the repository's
# `<repoDir>/TPLsList.cmake`_ file.
# Define the list of `TriBITS External Packages/TPLs`_ for a given `TriBITS
# Repository`_ which includes the external package/TPL name, TriBITS TPL find
# module, and classification . This macro is typically called from inside of
# a TriBITS Repository's `<repoDir>/TPLsList.cmake`_ file.
#
# Usage::
#
Expand All @@ -62,59 +62,53 @@ include(Split)
#
# This macro sets up a 2D array of ``NumTPLS`` by ``NumColumns`` listing out
# the `TriBITS TPLs`_ for a `TriBITS Repository`_. Each row (with 3 entries)
# specifies a TPL which contains the columns (ordered 0-2):
# specifies a different TriBITS exernal package/TPL which contains the columns
# (ordered 0-2):
#
# 0. **TPL** (``<tpli_name>``): The name of the TriBITS TPL ``<tplName>``.
# This name must be unique across all other TriBITS TPLs in this or any
# other TriBITS repo that might be combined into a single TriBITS project
# meta-build (see `Globally unique TriBITS TPL names`_). However, a TPL
# can be redefined from an upstream repo (see below). The name should be a
# valid identifier (e.g. matches the regex ``[a-zA-Z_][a-zA-Z0-9_]*``).
# TPL names typically use mixed case (e.g. ``SomeTpl`` and not
# ``SOMETPL``).
# 0. **TPL** (``<tpli_name>``): The name of the TriBITS external package/TPL
# ``<tplName>``. This name must be unique across all other TriBITS TPLs in
# this or any other TriBITS repo that might be combined into a single
# TriBITS project meta-build (see `Globally unique TriBITS TPL names`_).
# However, a TPL can be redefined from an upstream repo (see below). The
# name should be a valid identifier (e.g. matches the regex
# ``[a-zA-Z_][a-zA-Z0-9_]*``). TPL names typically use mixed case
# (e.g. ``SomeTpl``, not ``SOMETPL``).
#
# 1. **FINDMOD** (``<tpli_findmod>``): The relative or absolute path for the
# find module, usually with the name `FindTPL<tplName>.cmake`_. If it is a
# relative path, it is considered relative to the repository base directory
# ``<repoDir>``. If just the base path for the find module is given,
# ending with ``"/"`` (e.g. ``"cmake/tpls/"``), then the find module will
# be assumed to be under that this directory with the standard name
# 1. **FINDMOD** (``<tpli_findmod>``): For a TriBITS external package/TPL that
# **is not** a `TriBITS-compliant external package`_, this is set to the
# relative or absolute path for the TriBITS TPL find module, usually with
# the name `FindTPL<tplName>.cmake`_. If it is a relative path, it is
# considered relative to the repository base directory ``<repoDir>``. If
# just the base path for the find module is given, ending with ``"/"``
# (e.g. ``"cmake/tpls/"``), then the find module will be assumed to be
# under that this directory with the standard name
# ``FindTPL<tplName>.cmake``. (See `Creating the FindTPL<tplName>.cmake
# file`_.)
# file`_.) However, if the external package **is** a `TriBITS-compliant
# external package`_, provide the value ``TRIBITS_PKG`` instead and no
# ``FindTPL<tplName>.cmake`` file is needed. If a
# ``FindTPL<tplName>Dependencies.cmake`` file is needed in this case, then
# provide the path to that file (relative or absolute, directory or file
# path) using ``TRIBITS_PKG:<path-to-dir-or-file>``. This field is used to
# set the variables `<tplName>_FINDMOD`_ and
# `<tplName>_DEPENDENCIES_FILE`_.
#
# 2. **CLASSIFICATION** (``<pkgi_classif>``): Gives the `Package Test
# Group`_ `PT`_, `ST`_, or `EX`_ and the maturity level ``EP``, ``RS``,
# ``PG``, ``PM``, ``GRS``, ``GPG``, ``GPM``, ``UM``. These are separated
# by a coma with no space in between such as ``"RS,PT"`` for a "Research
# Stable", "Primary Tested" package. No spaces are allowed so that CMake
# treats this a one field in the array. The maturity level can be left off
# in which case it is assumed to be ``UM`` for "Unspecified Maturity".
# 2. **CLASSIFICATION** (``<pkgi_classif>``): Gives the `Package Test Group`_
# `PT`_, `ST`_, or `EX`_ and the maturity level ``EP``, ``RS``, ``PG``,
# ``PM``, ``GRS``, ``GPG``, ``GPM``, ``UM``. These are separated by a coma
# with no space in between such as ``"RS,PT"`` for a "Research Stable",
# "Primary Tested" package. No spaces are allowed so that CMake treats
# this a one field in the array. The maturity level can be left off in
# which case it is assumed to be ``UM`` for "Unspecified Maturity". This
# field is used to set the variable `<tplName>_TESTGROUP`_ and
# ``<tplName>_MATURITY_LEVEL``.
#
# A TPL defined in a upstream repo can listed again in a downstream repo,
# which allows redefining the find module that is used to specify the TPL.
# This allows downstream repos to add additional requirements for a given TPL
# (i.e. add more libraries, headers, etc.). However, the downstream repo's
# find module file must find the TPL components that are fully compatible with
# the upstream's find module in terms of what it provides for packages in
# upstream repos.
#
# This macro just sets the variable::
#
# ${REPOSITORY_NAME}_TPLS_FINDMODS_CLASSIFICATIONS
#
# in the current scope. The advantages of using this macro instead of
# directly setting this variable are that the macro:
#
# * Asserts that the variable ``REPOSITORY_NAME`` is defined and set
#
# * Avoids having to hard-code the assumed repository name
# ``${REPOSITORY_NAME}``. This provides more flexibility for how other
# TriBITS projects choose to name a given TriBITS repo (i.e. the name of
# repo subdirs).
#
# * Avoids misspelling the name of the variable
# ``${REPOSITORY_NAME}_TPLS_FINDMODS_CLASSIFICATIONS``. If one misspells
# the name of a macro, it is an immediate error in CMake.
# A TPL defined in a upstream repo can be listed again in a downstream repo,
# which allows redefining the find module that is used to specify the external
# package/TPL. This allows downstream repos to add additional requirements
# for a given TPL (i.e. add more libraries, headers, etc.). However, the
# downstream repo's find module file must find the TPL components that are
# fully compatible with the upstream defined find module in terms of what it
# provides for packages in the upstream repos.
#
macro(tribits_repository_define_tpls)
assert_defined(REPOSITORY_NAME)
Expand Down
79 changes: 44 additions & 35 deletions tribits/doc/guides/TribitsGuidesBody.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ units are:
* `TriBITS External Package/TPL`_: The specification for a particular external
dependency that is required or can be used in one or more `TriBITS
Packages`_. A modern TriBITS external package/TPL (Third Party Library) is
typically just a small file ``FindTPL<tplName>.cmake`` that calls
typically just a small file ``FindTTPL<tplName>.cmake`` that calls
``find_package(<externalPkg>)`` and defines the ``<tplName>::all_libs``
target. More generally, an external package/TPL can be specificed as a list
list of libraries and/or include directories for header files. Examples of
Expand Down Expand Up @@ -1985,12 +1985,13 @@ below:
.. _FindTPL<tplName>.cmake:
.. _<tplDefsDir>/FindTPL<tplName>.cmake:

**<tplDefsDir>/FindTPL<tplName>.cmake**: [Required] Defines how an external
package/TPL is found and provided for usage by a downstream TriBITS package by
providing the ``<tplName>::all_libs`` target and a package config file
``<tplName>Config.cmake`` that also defines the target
``<tplName>::all_libs``. (The requirements for a ``FindTPL<tplName>.cmake``
file are given in `Requirements for FindTPL<tplName>.cmake modules`_).
**<tplDefsDir>/FindTPL<tplName>.cmake**: [Required] *TriBITS TPL find module*
that defines how a TriBITS external package/TPL is found and provided for
usage by a downstream TriBITS package. This module must provide the
``<tplName>::all_libs`` target and must create a `TriBITS-compliant external
package`_ wrapper package config file ``<tplName>Config.cmake``. (See the
requirements for a ``FindTPL<tplName>.cmake`` file in `Requirements for
FindTPL<tplName>.cmake modules`_).

The form of a simple ``FindTPL<tplName>.cmake`` file that uses an internal
call to ``find_package(<externalPkg>)`` which provides modern IMPORTED CMake
Expand All @@ -2006,7 +2007,8 @@ In this case, the purpose for the ``FindTPL<tplName>.cmake`` file (as apposed
to a direct call to ``find_package(<externalPkg>)``) is to ensure the
definition of the complete target ``<tplName>::all_libs`` which contains all
usage requirements for the external package/TPL (i.e. all of the libraries,
include directories, etc.).
include directories, etc.) and this also generates the wrapper package config
file ``<tplName>Config.cmake``.

The form of a simple ``FindTPL<tplName>.cmake`` file that just provides a list
of required header files and libraries that does **not** use an internal call
Expand Down Expand Up @@ -2070,23 +2072,20 @@ defined TPL ``TPL_NAME`` is assigned the following global non-cache variables:

``${TPL_NAME}_FINDMOD``

Relative path (w.r.t. ``<projectDir>``) or absolute path for the external
package/TPL's find module (typically named `FindTPL<tplName>.cmake`_):
This is set using the ``FINDMOD`` field in the call to
`tribits_repository_define_tpls()`_. The final value of the variable is
defined by the *last* `<repoDir>/TPLsList.cmake`_ file that is processed
that declares the TPL ``TPL_NAME``. For example, if
``Repo1/TPLsList.cmake`` and ``Repo2/TPLsList.cmake`` both list the TPL
``SomeTpl``, then if ``Repo2`` is processed after ``Repo1``, then
``SomeTpl_FINDMOD`` is determined by ``Repo2/TPLsList.cmake`` and the find
module listed in ``Repo1/TPLsList.cmake`` is ignored. NOTE: The special
value ``TRIBITS_PKG`` is also recognized for external packages/TPLs that
are *TriBITS-compliant* (i.e. defines a ``${TPL_NAME}Config.cmake``
file provides the ``${TPL_NAME}::all_libs`` target, calls
``find_dependency(<UpstreamPkg>)`` on all of its upstream dependencies,
and each of those dependencies defines the ``<UpstreamPkg>::all_libs``
target.) A pre-installed TriBITS package meets this definition,
obviously.
For a **non-** `TriBITS-compliant external package`_, this is the relative
path (w.r.t. ``<projectDir>``) or absolute path for the *TriBITS TPL find
module* (typically named `FindTPL<tplName>.cmake`_). This is set using the
``FINDMOD`` field in the call to `tribits_repository_define_tpls()`_. The
final value of the variable is defined by the **last**
`<repoDir>/TPLsList.cmake`_ file that is processed that declares the TPL
``TPL_NAME``. For example, if ``Repo1/TPLsList.cmake`` and
``Repo2/TPLsList.cmake`` both list the TPL ``SomeTpl``, then if ``Repo2``
is processed after ``Repo1``, then ``SomeTpl_FINDMOD`` is determined by
``Repo2/TPLsList.cmake`` and the find module listed in
``Repo1/TPLsList.cmake`` is ignored. NOTE: for a `TriBITS-compliant
external package`_, the special value ``TRIBITS_PKG`` is also recognized.
(Any pre-installed TriBITS package is a `TriBITS-compliant external
package`_.)

.. _<tplName>_DEPENDENCIES_FILE:
.. _${TPL_NAME}_DEPENDENCIES_FILE:
Expand All @@ -2096,10 +2095,15 @@ defined TPL ``TPL_NAME`` is assigned the following global non-cache variables:
Relative path (w.r.t. ``<projectDir>``) or absolute path for the external
package/TPL's dependencies file (typically named
`FindTPL<tplName>Dependencies.cmake`_). This is always beside the find
module `${TPL_NAME}_FINDMOD`_ (and in fact
``${TPL_NAME}_DEPENDENCIES_FILE`` is constructed from
``${TPL_NAME}_FINDMOD``).

module `${TPL_NAME}_FINDMOD`_. (In fact, for a **non-**
`TriBITS-compliant external package`_, ``${TPL_NAME}_DEPENDENCIES_FILE``
is constructed from ``${TPL_NAME}_FINDMOD``). NOTE: A `TriBITS-compliant
external package`_ with dependencies will also have this file set and the
path will be specified independent of the path to the non-existent
``FindTPL<tplName>.cmake`` file (see the ``FINDMOD`` field in the call to
`tribits_repository_define_tpls()`_).

.. _<tplName>_TESTGROUP:
.. _${TPL_NAME}_TESTGROUP:

``${TPL_NAME}_TESTGROUP``
Expand Down Expand Up @@ -5520,15 +5524,20 @@ To add a new TriBITS TPL, do the following:

3) **Create the FindTPL<tplName>.cmake file** (or some other name, see
`<tplName>_FINDMOD`_) under ``<tplDefsDir>/``. (See `Creating the
FindTPL<tplName>.cmake file`_.)
FindTPL<tplName>.cmake file`_.) However, if the external package/TPL is a
`TriBITS-compliant external package`_ this file is not needed and is
ignored.

4) **[Optional] Create the FindTPL<tplName>Dependencies.cmake file** in the
same directory as the ``FindTPL<tplName>.cmake`` file, ``<tplDefsDir>/``.
(See `FindTPL<tplName>Dependencies.cmake`_.)

5) **Add a row to the <repoDir>/TPLsList.cmake file** for the new TPL after
any TPLs that this new TPL may depend on. (See
`<repoDir>/TPLsList.cmake`_.)
(See `FindTPL<tplName>Dependencies.cmake`_.) NOTE: This file is need for a
`TriBITS-compliant external package`_ if it has upstream dependent external
packages/TPLs (where the file ``FindTPL<tplName>.cmake`` is not needed).

5) **Add a row to the <repoDir>/TPLsList.cmake file** for the new external
package/TPL after any upstream TPLs that this new TPL may depend on. NOTE:
For a `TriBITS-compliant external package`_, the special value
``TRIBITS_PKG`` is used for the TPL (See `<repoDir>/TPLsList.cmake`_.)

6) **Configure the TriBITS project enabling the new TPL with
TPL_ENABLE_<tplName>=ON** and see that the TPL is found correctly at
Expand Down

0 comments on commit 68c83ef

Please sign in to comment.