SQUASH AGAINST: WIP: Add HowTos for TriBITS-compliant raw CMake packa…

…ge (TriBITSPub#582)

tribits/doc/guides/.gitignore

@@ -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

tribits/doc/guides/TribitsGuidesBody.rst

@@ -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
 ---------------------------------------------------------------------
 
@@ -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
@@ -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
 ---------------------------------------------------------
 

tribits/doc/guides/generate-guide.sh

@@ -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

tribits/examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake

@@ -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")