Skip to content

Commit

Permalink
SQUASH AGAINST: WIP: Add HowTos for TriBITS-compliant raw CMake packa…
Browse files Browse the repository at this point in the history
  • Loading branch information
bartlettroscoe committed Sep 8, 2023
1 parent ed04232 commit 32df700
Show file tree
Hide file tree
Showing 4 changed files with 47 additions and 29 deletions.
2 changes: 2 additions & 0 deletions tribits/doc/guides/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
/TriBITS.README.DIRECTORY_CONTENTS.rst.tmp
/TribitsCommonTPLsList.txt
/TribitsCommonTPLsList.txt.tmp
/TribitsExampleProject2_Package1_CMakeLists.raw.external.cmake
/TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake
/TribitsGitVersion.txt
/TribitsGitVersion.txt.tmp
/TribitsHelloWorldDirAndFiles.txt
Expand Down
60 changes: 33 additions & 27 deletions tribits/doc/guides/TribitsGuidesBody.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6262,6 +6262,31 @@ file as well. Then every ``CMakeLists.txt`` file in subdirectories just calls
``include_tribits_build()``. That is it.


How to implement a TriBITS-compliant external package using raw CMake
---------------------------------------------------------------------

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 behavior. For most existing raw CMake
projects that already produce a ``<Package>Config.cmake`` file, that means
adding a IMPORTED target to the installed ``<Package>Config.cmake`` file
called ``<Package>::all_libs``.

This is demonstrated in the `TribitsExampleProject2`_ package ``Package1``.
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 looks like:

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

ToDo: Complete me!




How to implement a TriBITS-compliant internal package using raw CMake
---------------------------------------------------------------------

Expand All @@ -6272,19 +6297,16 @@ TriBITS project. The raw CMake code for such a package must provide the
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 is capable of installing TriBITS-compliant external package's
``<Package>Config.cmake`` file. This is demonstrated in the
`TribitsExampleProject2`_ package ``Package1``. 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 looks like:
``<Package>Config.cmake`` file.

.. include:: ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake
:literal:
This is demonstrated in the `TribitsExampleProject2`_ package ``Package1``.
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:

**SIDENOTE:** The above example shows the optional inclusion of the TriBITS
test function modules ``TribitsAddTest.cmake`` and
``TribitsAddAdvancedTest.cmake`` which are not included by default. (See `How
to use TriBITS testing support in non-TriBITS project`_).
.. include:: TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake
:literal:

After the build targets the tests are defined, the ``Package1::all_libs``
target is generated in such a way that ``Package1::all_libs`` will become an
Expand Down Expand Up @@ -6323,22 +6345,6 @@ in the directory ``package1/src/``):
:literal:


How to implement a TriBITS-compliant external package using raw CMake
---------------------------------------------------------------------

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 all of the requirements for a TriBITS-compliant external
package. These installed packages provide a ``<Package>Config.cmake`` file
that provides all of the needed targets and behavior. For most existing raw
CMake package projects, that means adding a IMPORTED target to the installed
``<Package>Config.cmake`` file called ``<Package>::all_libs``.

The raw CMake code to create a TriBITS-compliant external package is identical
for the case for creating a TriBITS-compliant internal package as described
above. The only difference is that such a package does not need to generate


How to use TriBITS testing support in non-TriBITS project
---------------------------------------------------------

Expand Down
11 changes: 11 additions & 0 deletions tribits/doc/guides/generate-guide.sh
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,17 @@ function tribits_extract_other_doc {
&> TribitsHelloWorldDirAndFiles.txt.tmp
update_if_different TribitsHelloWorldDirAndFiles.txt tmp

echo
echo "Generating TribitsExampleProject2/Package1 CMakeList file variants ..."
echo
cat ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake | \
grep -v EnableTribitsTestSupport | \
grep -v GeneratePackageConfigFileForBuildDir \
&> TribitsExampleProject2_Package1_CMakeLists.raw.external.cmake
cat ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake | \
grep -v EnableTribitsTestSupport | \
&> TribitsExampleProject2_Package1_CMakeLists.raw.internal.cmake

echo
echo "Generating output for 'checkin-test.py --help' ..."
echo
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@ if (Package1_ENABLE_TESTS)
add_subdirectory(test)
endif()

# Stuff that TriBITS does automatically
include("${CMAKE_CURRENT_LIST_DIR}/cmake/raw/DefineAllLibsTarget.cmake")

include("${CMAKE_CURRENT_LIST_DIR}/cmake/raw/GeneratePackageConfigFileForBuildDir.cmake")

include("${CMAKE_CURRENT_LIST_DIR}/cmake/raw/GeneratePackageConfigFileForInstallDir.cmake")

0 comments on commit 32df700

Please sign in to comment.