… changes (#582)

This is really a very general function so I updated the documentation to be
general.  This will allow this function to be moved to tribits/core/utils/.

I also renamed some local vars to be camelCase.

#582)

This is a generic function (see comments and documentation from previous
commit).

NOTE: This move of the module was done in a separate commit from the last
commit so as to not confuse Git in tracing filename changes.

…ject (#582)

Now we can update TriBITS and the raw Package1 build system for it to work as
a TriBITS package but without calling any TriBITS macros or functions.

This makes the documentation ad code a little more clear.

As part of this, I renamed the function
`tribits_write_package_client_export_files_install_targets()` to `
tribits_write_package_client_export_files_export_and_install_targets()`.  That
makes it a little more clear what these functions are doing.

Allow TriBITS package TribitsExampleProject/Package1 to use 100% raw CMake and
update TriBITS to allow that.

This raw CMake build mode for Package1 uses no TriBITS macros, functions, or
other functionality at all.

The only changes to TriBITS-proper needed to allow this were:

* Skip check for not calling tribits_package_postprocess() if the
  `<Package>::all_libs` target is already defined.

* Build up the list of package libraries target for the `<Project>_libs`
  target from `<Package>::all_libs` instead of `<Package>_libs` (since the
  latter does not exist for a raw CMake package).

However, this also required some changes to the
TribitsExampleProject2/Package1 raw build system:

* Use `${CMAKE_PROJECT_NAME}_INSTALL_LIB_DIR}` as the library install location
  instead of `${CMAKE_INSTALL_LIBDIR}` when building as a TriBITS package.

This seems to pass all of the TriBITS tests.

NOTE: This commit does **not** yet contain the changes to TriBITS to allow
calling project() in the package's CMakeLists.txt files and still use TriBITS
macros in the package's CMakeLists.txt files.  Those changes will come later
as we add an example that calls some TriBITS functions.

This avoids the special logic in the file package1/CMakeLists.txt by having
TribitsExampleProject2/CMakeLists.txt set the var
${PROJECT_NAME}_USE_GNUINSTALLDIRS=ON.  This resulted in everything being
installed under <prefix>/lib64/ on my current machine automatically.

However, to get this to work I had to set:

  -DCMAKE_INSTALL_LIBDIR:STRING=lib

or the find_package(...) command with CMake 3.23.1 would no longer find
<Package>Config.cmake files under:

  <prefix>/lib64/

This seems inconsistent with CMake documentation for find_package() as of
CMake 3.23.1 that suggests that it will look under the location:

  <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/

Well that should pick up the directory:

  <prefix>/lib*/cmake/<name>*/

But that was not the case :-(

Perhaps this is fixed in the latest CMake?  In any case, we get around this by
by setting CMAKE_INSTALL_LIBDIR=lib.

Other changes made in this commit:

* Fixed the 'TribitsExampleApp2' tests to correctly switch between searching
  for the top project-level package-config file or the individual
  package-config files.  (This required passing in
  -DTribitsExApp2_FIND_INDIVIDUAL_PACKAGES=ON and updating the regex.)

…582)

This avoids having to add:

  -DCMAKE_INSTALL_LIBDIR:STRING=lib

for all of the TribitsExampleProject2_find_package tests.

If it was not for the CMake defect with find_package() documented in the new
updated comment, then we could set TribitsExProj2_USE_GNUINSTALLDIRS=ON and
not have to set CMAKE_INSTALL_LIBDIR=lib.

…ge1 build under TriBITS project (#582)

This test sets up to use the TriBITS test management functions from inside of
a raw CMake package under a TriBITS project.

…ect (#582)

This will allow me to define and run the tests for Package1 using
tribits_add_test().

This addeds the macros:

  tribits_advanced_set_cache_var_and_default()
  tribits_set_cache_var_and_default()

This will make it easy to refactor code that sets a cache var and its default.

This makes it usable in a project that does not use all of TriBITS.

…e project build (#582)

This makes the failing test added in the last commit to pass.

This commit updates TriBITS to allow a raw CMake project to just include:

  include("<tribitsDir>/core/package_arch/TribitsAddTest.cmake")

and then use tribits_add_test() without having to append CMAKE_MODULE_PATH.

To make this work, I had to change from:

  include(<fileName>)

to use explicit file include with base dir:

  include("<baseDir>/<fileName>.cmake")

This also makes the locations of these files more explicit, which I think is
good actually.

I updated TribitsExampleProject2/Package1 to use tribits_add_test() in a
stand-alone raw CMake build.

A few other things done:

* Removed the include of TribitsGeneralMacros.cmake from
  TribitsAddTestHelpers.cmake since none of its macros/functions are used
  any longer.

* Shortened 'PACKAGE1_USE_TRIBITS_TEST_FUCNTIONS' to
  'PACKAGE1_USE_TRIBITS_TEST_FUNCS' to shorten the test name some.

This breaks some test support related modules for the function
tribits_add_test() into their own subdirectory:

  tribits/core/test_support/

and include them with explicit relative and absolute includes and not relying
on CMAKE_MODULE_PATH.  (By using explicit includes we can better see and
manage the dependencies between modules on these separate subdirs and better
partition TriBITS.)

To cleanly break out these test_support modules, I created a new subidr:

  tribits/core/common/

and put the modules TribitsCMakePolicies.cmake and TribitsConstants.cmake into
them.  And I also did not add this new subdir to CMAKE_MODULE_PATH for the
same reason as above for test_support.  This allows some non-test-related
modules in tribits/core/package_arch/ to depend on tribits/core/common/ but
not tribits/core/test_support/.

Technically, this commit is the start of the componitization of TriBITS Core
as per #368.

This shortens the names of tests.  I have used the acronym 'PBP' in
ctest_driver tests already.

…#582)

Changes to TriBITS:

* Changed explicit includes from TribitsAddAdvancedTest.cmake (this module and
  its included modules will be moved to tribits/core/test_support/ in next
  commit).

* Remove option to prefix test base name in tribits_add_advanced_test() by
  '${PROJECT_NAME}_' (since tribits_set_tribits_package_name() is now being
  called to set PACKAGE_NAME give PROJECT_NAME).

* Changed tribits_add_advanced_test() to set explicit include of
  DriveAdvancedTest.cmake without setting CMAKE_MODULE_PATH.

* Use more explicit includes in tribits/core/utils/*.cmake mdoules needed to
  get above to work.

Changes to TribitsExampleProject2/Packages1:

* Updated package1-prg to accept command-line arguments that are echoed to
  STDOUT.

* Added new test Package1_Prg-advanced taking in command-line arguments using
  tribits_add_advanced_test() and in raw CMake build.

Changes to tests:

* Removed regex for CMAKE_MODULE_PATH from driver file for
  tribits_add_advanced_test() (which reduces the total number of checks by 1).

…#582)

…roject (#368, #582)

This makes it easier to compare the TriBITS build system for a package with a
raw CMake build system that is TriBITS-compliant.

)

Makes it more clear what is needed for an internal package and an external
package.

)

This will allow me to exclude parts that I don't want to show in the
developers guide.

NOTE: The only reas the test file TribitsExampleProject2_Tests.cmake is
updated is because I took 'a' out of 'in a raw'.

This change was made several years ago but we forgot to update this
documentation.

Several things were done here:

* Added new section "How to implement a TriBITS-compliant internal package
  using raw CMake"

* Added new section "How to implement a TriBITS-compliant external package
  using raw CMake"

* Added subsection on example project TribitsExampleProject2 under the "Example
  TriBITS Projects" section.

* Added generation of reduced versions of the package1/CMakeLists.raw.cmake
  file for different cases.  (But will only trigger a re-make if the generated
  files change.)

* Added make dependencies on generated *.cmake files

* generate-guide.sh: Added time to 'make' command and discard STDOUT for 'cd
-' command (makes output look better)

…t' (#368)

Caught by @KyleFromKitware

Caught by @KyleFromKitware

)

Now just calls tribits_set_cache_var_and_default() then mark_as_advanced().

Suggested by @KyleFromKitware