WIP: Add HowTos for TriBITS-compliant raw CMake package (TriBITSPub#582)

tribits/doc/guides/TribitsGuidesBody.rst

@@ -2970,6 +2970,28 @@ should be copied from this example project as they represent best practice
 when using TriBITS for the typical use cases.
 
 
+TribitsExampleProject2
+----------------------
+
+``TribitsExampleProject2`` in an example `TriBITS Project`_ and `TriBITS
+Repository`_ contained in the TriBITS source tree under::
+
+  tribits/examples/TribitsExampleProject2/
+
+This example TriBITS project provides some examples for a few other features
+and testing scenarios.  It contains three internal packages ``Package1``,
+``Package2``, and ``Package3`` as shown in its ``PackagesList.cmake`` file:
+
+.. include:: ../../examples/TribitsExampleProject2/PackagesList.cmake
+   :literal:
+
+and supports four external packages/TPLs ``Tpl1``, ``Tpl2``, ``Tpl3``, and
+``Tpl4`` as shown in its ``TPLsList.cmake`` file:
+
+.. include:: ../../examples/TribitsExampleProject2/TPLsList.cmake
+   :literal:
+
+
 MockTrilinos
 -------------
 
@@ -6240,6 +6262,87 @@ file as well.  Then every ``CMakeLists.txt`` file in subdirectories just calls
 ``include_tribits_build()``.  That is it.
 
 
+How to implement a TriBITS-compliant internal package using raw CMake
+---------------------------------------------------------------------
+
+As described in `TriBITS-Compliant Internal Packages`_, it is possible to
+create a raw CMake build system for a CMake package that can build under a
+TriBITS 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 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:
+
+.. include:: ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.raw.cmake
+   :literal:
+
+**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`_).
+
+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
+IMPORTED target in the generated ``Package1ConfigTargets.cmake`` file and also
+the ``Package1::all_libs`` will exist so it can be lined to by downstream
+TriBITS packages.
+
+The code at the end of the above ``CMakeLists.txt`` file shows the generation
+of the installed ``Package1Config.cmake`` file.  This file is configured from
+the input file ``Package1Config.cmake.in``:
+
+.. include:: ../../examples/TribitsExampleProject2/packages/package1/cmake/raw/Package1Config.cmake.in
+   :literal:
+
+and is installed into the proper location of the location under
+``${CMAKE_INSTALL_LIBDIR}/`` and itself includes the CMake generated and
+installed ``Package1ConfigTargets.cmake`` file.
+
+Creating library and executable targets for a TriBITS-compliant package
+requires more that just calling ``add_library()``, ``add_executable()``,
+``target_include_directories()`` and ``target_link_libraries()`` like a simple
+CMake project.  It also requires setting some target properties and calling
+``install()`` with the correct EXPORT set and include destination.
+
+**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/``):
+
+.. include:: ../../examples/TribitsExampleProject2/packages/package1/CMakeLists.tribits.cmake
+   :literal:
+
+and the TriBITS ``CMakeLists.txt`` file (called ``CMakeLists.tribits.cmake``
+in the directory ``package1/src/``):
+
+.. include:: ../../examples/TribitsExampleProject2/packages/package1/src/CMakeLists.tribits.cmake
+   :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
+---------------------------------------------------------
+
+
 How to check for and tweak TriBITS "ENABLE" cache variables
 -----------------------------------------------------------