TriBITS snapshot on 6/7/2019 to bring in Trilinos_ENABLE_INSTALLATION_TESTING documentation (#5097)

cmake/tribits/ci_support/CDashQueryAnalyzeReport.py

@@ -1055,8 +1055,8 @@ def dateFromBuildStartTime(buildStartTime):
 #
 # Inputs:
 #
-#   testHistoryLOD [in]: List of test dicts for the same test.  This input
-#   list nore its elements are modified in this call.  The base list object is
+#   testHistoryLOD [in]: List of test dicts for the same test.  Neigher this
+#   list nor its elements are modified in this call.  The base list object is
 #   shallow copied before it is sorted and returned.
 #
 #   currentTestDate [in]: The current testing day (as a string "YYYY-MM-DD").

cmake/tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -3347,6 +3347,58 @@ This will ensure that every package that builds correctly will get installed.
 (The default 'install' target aborts on the first file install failure.)
 
 
+Installation Testing
+====================
+
+The CMake project <Project> has built-in support for testing an installation
+of itself using its own tests and examples.  The way it works is to configure,
+build, and install just the libraries and header files using::
+
+  $ mkdir BUILD_LIBS
+  $ cd BUILD_LIBS/
+
+  $ cmake \
+    -DCMAKE_INSTLAL_PREFIX=<install-dir> \
+    -D<Project>_ENABLE_ALL_PACKAGES=ON \
+    -D<Project>_ENABLE_TESTS=OFF \
+    [other options] \
+    <projectDir>
+
+  $ make -j16 install   # or ninja -j16
+
+and then create a different build directory to configure and build just the
+tests and examples (not the libraries) against the pre-installed libraries and
+header files using::
+
+  $ mkdir BUILD_TESTS
+  $ cd BUILD_TESTS/
+
+  $ cmake \
+    -D<Project>_ENABLE_ALL_PACKAGES=ON \
+    -D<Project>_ENABLE_TESTS=ON \
+    -D<Project>_ENABLE_INSTALLATION_TESTING=ON \
+    -D<Project>_INSTALLATION_DIR=<install-dir> \
+    [other options] \
+    <projectDir>
+
+  $ make -j16  # or ninja -j16
+
+  $ ctest -j16
+
+If that second project builds and all the tests pass, then the project was
+installed correctly.  This uses the project's own tests and examples to test
+the installation of the project.  The library source and header files are
+unused in the second project build.  In fact, you can delete them and ensure
+that they are not used in the build and testing of the tests and examples!
+
+This can also be used for testing backward compatibility of the project (or
+perhaps for a subset of packages).  In this case, build and install the
+libraries and header files for a newer version of the project and then
+configure, build, and run the tests and examples for an older version of the
+project sources pointing to the installed header files and libraries from the
+newer version.
+
+
 Packaging
 =========
 

cmake/tribits/examples/TribitsExampleProject/packages/mixed_lang/src/CMakeLists.txt

@@ -1,17 +1,20 @@
 TRIBITS_CONFIGURE_FILE(${PACKAGE_NAME}_config.h)
-INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
+
 
 SET(HEADERS "")
 SET(SOURCES "")
 
-INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
+INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
+APPEND_SET(HEADERS
+  ${CMAKE_CURRENT_BINARY_DIR}/${PACKAGE_NAME}_config.h
+  )
 
+INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
 APPEND_SET(HEADERS
   MixedLang.hpp
   Ray_Tracer.hh
   Ray.hh
   )
-
 APPEND_SET(SOURCES
   MixedLang.cpp
   Ray_Tracer.cc

cmake/tribits/examples/TribitsExampleProject/packages/simple_cxx/src/CMakeLists.txt

@@ -11,15 +11,15 @@ TRIBITS_CONFIGURE_FILE(${PACKAGE_NAME}_config.h)
 SET(HEADERS "")
 SET(SOURCES "")
 
-# To include the configured header above
 INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
+APPEND_SET(HEADERS
+  ${CMAKE_CURRENT_BINARY_DIR}/${PACKAGE_NAME}_config.h
+  )
 
 INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
-
 APPEND_SET(HEADERS
   SimpleCxx_HelloWorld.hpp
   )
-
 APPEND_SET(SOURCES
   SimpleCxx_HelloWorld.cpp
   )

cmake/tribits/examples/TribitsExampleProject/packages/with_subpackages/b/src/CMakeLists.txt

@@ -3,10 +3,11 @@ INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
 
 INCLUDE(${CMAKE_CURRENT_LIST_DIR}/ShowLibErrors.cmake)
 
+INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})
 INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
 TRIBITS_ADD_LIBRARY(pws_b
   SOURCES B.cpp
-  HEADERS B.hpp
+  HEADERS B.hpp ${CMAKE_CURRENT_BINARY_DIR}/${PACKAGE_NAME}_config.h
   ADDED_LIB_TARGET_NAME_OUT pws_b_TARGET_NAME
   ${EXTRA_TAL_ARGS}
   )

cmake/tribits/python_utils/gitdist-setup.sh

@@ -0,0 +1,11 @@
+# Source this with bash to load useful env for using gitdist
+alias gitdist-status="gitdist dist-repo-status"
+alias gitdist-mod="gitdist --dist-mod-only"
+alias gitdist-mod-status="gitdist --dist-mod-only dist-repo-status"
+function gitdist-repo-versions {
+  gitdist "$@" --dist-no-color log -1 --pretty=format:"%h [%ad] <%ae>%n%s" | grep -v "^$"
+}
+
+# Setup for completions for git command and gitdist options commands!
+complete -o default -o nospace -F _git -W "dist-repo-status --dist-help --dist-use-git --dist-repos --dist-not-repos --dist-version-file --dist-version-file2 --dist-no-color --dist-debug --dist-no-opt --dist-mod-only --dist-legend" gitdist gitdist-mod
+complete -o default -o nospace -W "--dist-use-git --dist-repos --dist-not-repos --dist-no-color --dist-debug --dist-no-opt --dist-mod-only" gitdist-repo-versions

cmake/tribits/python_utils/gitdist.py

@@ -383,6 +383,9 @@ def getHelpTopicsStr():
   $ gitdist --dist-no-color log -1 --pretty=format:"%h [%ad] <%ae>" \
     | grep -v "^$" &> RepoVersion.txt
 
+(See the alias 'gitdist-repo-versions' defined in the file
+'gitdist-setup.sh'.)
+
 This allows checking out consistent versions of the set git repos, diffing two
 consistent versions of the set of git repos, etc.
 
@@ -438,14 +441,18 @@ def getHelpTopicsStr():
 usefulAliasesHelp =r"""
 USEFUL ALIASES:
 
-A few very useful (bash) shell aliases to use along with the gitdist script
-are:
+A few very useful (bash) shell aliases and setup commands to use with gitdist
+include:
 
   $ alias gitdist-status="gitdist dist-repo-status"
   $ alias gitdist-mod="gitdist --dist-mod-only"
   $ alias gitdist-mod-status="gitdist dist-repo-status --dist-mod-only"
+  $ alias gitdist-repo-versions="gitdist --dist-no-color log -1 \
+    --pretty=format:\"%h [%ad] <%ae>%n%s\" | grep -v \"^$\""
 
-(i.e. add these to your ~/.bash_profile file.)
+These are added by sourcing the provided file 'gitdist-setup.sh' as well as
+some useful commandline tab completion (which be sourced in you
+~/.bash_profile file.)
 
 This avoids lots of extra typing as these gitdist arguments are used a lot.
 For example, to see the compact status table of all your local git repos, do: