Skip to content

Commit

Permalink
Do edits to new howto sections in users guide (#368, #582)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bartlettroscoe
bartlettroscoe committed Sep 21, 2023
1 parent 4d848d8 commit c941426
Showing 1 changed file with 57 additions and 45 deletions.
102 changes: 57 additions & 45 deletions tribits/doc/guides/TribitsGuidesBody.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6271,27 +6271,30 @@ parent TriBITS CMake project. The raw CMake code for such a package must
provide the ``<Package>::all_libs`` target both in the current CMake build
system and also in the generated ``<Package>Config.cmake`` file for the build
directory and in the installed ``<Package>Config.cmake`` file. Every such
TriBITS-compliant internal package therefore is also capable of installing a
TriBITS-compliant external package ``<Package>Config.cmake`` file.
TriBITS-compliant internal package therefore is **also capable of installing a
TriBITS-compliant external package** ``<Package>Config.cmake`` file (see `How
to implement a TriBITS-compliant external package using raw CMake`_).

.. ToDo: Consider listing out the key features of a raw CMake build system
that is needed for a TriBITS-compliant internal package.
A raw CMake build system for a TriBITS-compliant internal package is
demonstrated in the `TribitsExampleProject2`_ project ``Package1`` package.
The base ``CMakeLists.txt`` file for building ``Package1`` with a raw CMake
build system (called ``CMakeLists.raw.cmake`` in that directory) looks like:
build system (called ``package1/CMakeLists.raw.cmake`` in that directory)
looks like:

.. include:: TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake
:literal:

As shown above, this simple CMake package contains the basic features of any
CMake project/package including calling the ``cmake_minimum_required()`` and
``project()`` commands as well as including ``GNUInstallDirs``. In this
example, the project/package being built ``Package1`` has a dependency on a
external package ``Tpl1`` pulled in with ``find_package(Tpl1)``. Also in this
example, the package has native tests it defines with ``include(CTest)`` and
``add_subdirectory()`` (if ``Package1_ENABLE_TESTS`` is set to ``ON``).
example, the project/package being built ``Package1`` has a dependency on an
external upstream package ``Tpl1`` pulled in with ``find_package(Tpl1)``.
Also in this example, the package has native tests it defines with
``include(CTest)`` and ``add_subdirectory()`` (if ``Package1_ENABLE_TESTS`` is
set to ``ON``).

The file ``package1/src/CMakeLists.raw.cmake`` (which gets included from
``package1/src/CMakeLists.txt``) creates a library and executable for the
Expand Down Expand Up @@ -6322,8 +6325,8 @@ put in the generated ``Package1ConfigTargets.cmake`` file (see below).

The ``Package1Config.cmake`` (``<Package>Config.cmake``) file for the build
directory is generated inside of the included file
``cmake/raw/GeneratePackageConfigFileForBuildDir.cmake`` which has the
contents:
``package1/cmake/raw/GeneratePackageConfigFileForBuildDir.cmake`` which has
the contents:

.. include:: ../../examples/TribitsExampleProject2/packages/package1/cmake/raw/GeneratePackageConfigFileForBuildDir.cmake
:literal:
Expand All @@ -6333,12 +6336,16 @@ The above code uses the ``export(EXPORT ...)`` command to generate the file
IMPORTED targets ``Package1::package1`` and ``Package1::all_libs``. The
command ``configure_file(...)`` generates the ``Package1Config.cmake`` file
that includes it for the build directory
``<buildDir>/cmake_packages/Package1/``.
``<buildDir>/cmake_packages/Package1/``. (NOTE: The above code only runs when
the package is being built from inside of a TriBITS project which defines the
command ``tribits_package``. So this code gets skipped when building
``Package1`` as a stand-alone raw CMake project.)

Finally, the code for generating and installing the ``Package1Config.cmake``
file for the install directory ``CMAKE_PREFIX_PATH=<installDir>`` is specified in
the included file ``cmake/raw/GeneratePackageConfigFileForInstallDir.cmake``
with the contents:
file for the install directory ``CMAKE_PREFIX_PATH=<installDir>`` is specified
in the included file
``package1/cmake/raw/GeneratePackageConfigFileForInstallDir.cmake`` with the
contents:

.. include:: ../../examples/TribitsExampleProject2/packages/package1/cmake/raw/GeneratePackageConfigFileForInstallDir.cmake
:literal:
Expand Down Expand Up @@ -6367,20 +6374,21 @@ is used for this purpose. (For more details, see the book "Professional
CMake".)

**NOTE:** One should compare the above raw CMakeLists files to the more
compact TriBITS versions for the base ``CMakeLists.txt`` file (called
``CMakeLists.tribits.cmake`` in the base directory ``pacakge1/``):
compact TriBITS versions for the base ``package1/CMakeLists.txt`` file (called
``package1/CMakeLists.tribits.cmake`` in the base directory ``pacakge1/``):

.. include:: ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.tribits.cmake
:literal:

and the TriBITS ``CMakeLists.txt`` file (called ``CMakeLists.tribits.cmake``)
in the subdirectory ``package1/src/``:
and the TriBITS ``package1/src/CMakeLists.txt`` file (called
``package1/src/CMakeLists.tribits.cmake``):

.. include:: ../../examples/TribitsExampleProject2/packages/package1/src/CMakeLists.tribits.cmake
:literal:

This shows the amount of boilerplate code that TriBITS addresses automatically
(which reduces the overhead of finer-grained packages).
(which reduces the overhead of finer-grained packages and avoids common
mistakes with tedious low-level CMake code).


How to implement a TriBITS-compliant external package using raw CMake
Expand All @@ -6390,25 +6398,25 @@ As described in `TriBITS-Compliant External Packages`_, it is possible to
create a raw CMake build system for a CMake package such that once it is
installed, satisfies the requirements for a TriBITS-compliant external
package. These installed packages provide a ``<Package>Config.cmake`` file
that provides the required targets and behaviors. For most existing raw CMake
projects that already produce a "Professional CMake" compliant
``<Package>Config.cmake`` file, that usually just means adding the IMPORTED
target called ``<Package>::all_libs`` to the installed
``<Package>Config.cmake`` file.
that provides the required targets and behaviors as if it was produced by a
TriBITS project. For most existing raw CMake projects that already produce a
"Professional CMake" compliant ``<Package>Config.cmake`` file, that usually
just means adding the IMPORTED target called ``<Package>::all_libs`` to the
installed ``<Package>Config.cmake`` file.

A raw CMake build system for a TriBITS-compliant external package is
demonstrated in the `TribitsExampleProject2`_ project ``Package1`` package.
The base ``CMakeLists.txt`` file for building ``Package1`` with a raw CMake
build system (called ``CMakeLists.raw.cmake`` in that directory) for
implementing a TriBITS-compliant internal package (which also, by definition,
creates a TriBITS-compliant external package) looks like:
The base ``package1/CMakeLists.txt`` file for building ``Package1`` with a raw
CMake build system (called ``package1/CMakeLists.raw.cmake``) for implementing
a TriBITS-compliant internal package looks like:

.. include:: TribitsExampleProject2_Package1_CMakeLists.raw.external.cmake
:literal:

Note that the raw build system this example is identical to the build system
for the raw TriBITS-compliant internal package described above. The only
differences are:
for the raw TriBITS-compliant internal package described in `How to implement
a TriBITS-compliant internal package using raw CMake`_. The only differences
are:

1) The ``Package1Config.cmake`` (``<Package>Config.cmake``) file does **not**
need to be generated for the build directory and therefore the code in
Expand All @@ -6419,6 +6427,9 @@ differences are:
does **not** need to be generated (but should be to be "Professional CMake"
compliant).

Other than that, see `How to implement a TriBITS-compliant internal package
using raw CMake`_ for how to implement a TriBITS-compliant external package.


How to use TriBITS testing support in non-TriBITS project
---------------------------------------------------------
Expand All @@ -6428,31 +6439,32 @@ The TriBITS test support functions `tribits_add_test()`_ and
CMake project. To do so, one just needs to include the TriBITS modules:

* ``<tribitsDir>/core/test_support/TribitsAddTest.cmake``
* and ``<tribitsDir>/core/test_support/TribitsAddAdvancedTest.cmake``
* ``<tribitsDir>/core/test_support/TribitsAddAdvancedTest.cmake``

and set the variable ``${PROJECT_NAME}_ENABLE_TESTS`` to ``ON``. For an
MPI-enabled CMake project, one needs to define the following CMake variables
``MPI_EXEC``, ``MPI_EXEC_PRE_NUMPROCS_FLAGS``, ``MPI_EXEC_NUMPROCS_FLAG`` and
``MPI_EXEC_POST_NUMPROCS_FLAGS`` which define the MPI runtime program launcher
command-line used in these TriBITS testing functions::
MPI-enabled CMake project, the CMake variables ``MPI_EXEC``,
``MPI_EXEC_PRE_NUMPROCS_FLAGS``, ``MPI_EXEC_NUMPROCS_FLAG`` and
``MPI_EXEC_POST_NUMPROCS_FLAGS`` must also be set which define the MPI runtime
program launcher command-line used in the TriBITS testing functions::

${MPI_EXEC} ${MPI_EXEC_PRE_NUMPROCS_FLAGS}
${MPI_EXEC_NUMPROCS_FLAG} <NP>
${MPI_EXEC_POST_NUMPROCS_FLAGS}
<TEST_EXECUTABLE_PATH> <TEST_ARGS>
${MPI_EXEC_NUMPROCS_FLAG} <NP>
${MPI_EXEC_POST_NUMPROCS_FLAGS}
<TEST_EXECUTABLE_PATH> <TEST_ARGS>

(These are defined automatically in a TriBITS project.)
(NOTE: These variables are defined automatically in a TriBITS project when
``TPL_ENABLE_MPI`` is set to ``ON``.)

This is demonstrated in the `TribitsExampleProject2`_ project ``Package1``
package. The base ``CMakeLists.txt`` file for building ``Package1`` with a
raw CMake build system using TriBITS testing functions (called
``CMakeLists.raw.cmake`` in that directory) looks like:
package. The base ``pacakge1/CMakeLists.txt`` file for building ``Package1``
with a raw CMake build system using TriBITS testing functions (called
``package1/CMakeLists.raw.cmake``) looks like:

.. include:: TribitsExampleProject2_Package1_CMakeLists.raw.tribits_test.cmake
:literal:

The only difference between this base ``CMakeLists.txt`` file and one for a
raw CMake project is the inclusion of the file
The only difference between this base ``package1/CMakeLists.txt`` file and one
for a raw CMake project is the inclusion of the file
``package1/cmake/raw/EnableTribitsTestSupport.cmake`` which has the contents:

.. include:: ../../examples/TribitsExampleProject2/packages/package1/cmake/raw/EnableTribitsTestSupport.cmake
Expand All @@ -6464,7 +6476,7 @@ The key lines are::
include("${Package1_TRIBITS_DIR}/core/test_support/TribitsAddAdvancedTest.cmake")

This defines the CMake functions `tribits_add_test()`_ and
`tribits_add_advanced_test()`_.
`tribits_add_advanced_test()`_, respectively.

The above code demonstrates that ``CMAKE_MODULE_PATH`` does **not** need to be
updated to use these TriBITS ``test_support`` modules. However, one is free
Expand All @@ -6476,7 +6488,7 @@ like::
include(TribitsAddAdvancedTest)

Once these TriBITS modules are included, one can use the TriBITS functions as
demonstrated in the ``package1/test/CMakeLists.tribits.cmake`` file (which is
demonstrated in the file ``package1/test/CMakeLists.tribits.cmake`` (which is
included from the file ``package1/test/CMakeLists.txt``) and has the contents:

.. include:: ../../examples/TribitsExampleProject2/packages/package1/test/CMakeLists.tribits.cmake
Expand Down

0 comments on commit c941426

Please sign in to comment.