trilinos · srbdev · Aug 24, 2023 · Aug 26, 2023 · Aug 29, 2023 · Aug 29, 2023
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -91,6 +91,9 @@ SET(${PROJECT_NAME}_ENABLE_CPACK_PACKAGING_DEFAULT ON)
 # Don't allow disabled subpackages to be excluded from tarball
 SET(${PROJECT_NAME}_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION_DEFAULT FALSE)
 
+# See https://docs.trilinos.org/files/TrilinosBuildReference.html#setting-the-install-prefix
+SET(Trilinos_USE_GNUINSTALLDIRS ON)
+
 # Set up C++ language standard selection
 include(SetTrilinosCxxStandard)
 

diff --git a/cmake/SimpleTesting/README.md b/cmake/SimpleTesting/README.md
@@ -0,0 +1,139 @@
+CMake File Structure
+====================
+This CMake structure attempts to capture the structure of the original
+`TFW_testing_single_configure_prototype` that is used by the current / old Trilinos
+Pull-Request (PR) framework.
+
+**Note**: _Trilinos uses the **`pull_request_changes`** branch from this repository_.
+
+Specifically, this new configuration will replace the existing `simple_testing.cmake`
+script.
+
+This diagram describes the current structure of the CMake files and how they
+interact with each other.
+<center>
+     <img src="img/CMake-structure.png" alt="CMake Structure Diagram" height="600"/>
+</center>
+
+CMake Files
+-----------
+
+| Filename                      | Guarded? | Purpose                                                                  |
+|-------------------------------|:--------:|--------------------------------------------------------------------------|
+| `ctest-driver.cmake`          |          | Main driver script / entry-point                                         |
+| `ctest-common.cmake`          |    X     | Common activities such as option handling, etc.                          |
+| `ctest-cdash-setup.cmake`     |    X     | Handle CDash configurations                                              |
+| `ctest-stage-configure.cmake` |          | Handle the _configuration_ stage of the test                             |
+| `ctest-stage-build.cmake`     |          | Handle the _build_ stage of the test                                     |
+| `ctest-stage-test.cmake`      |          | Handle the _test_ stage of the test.                                     |
+| `ctest-functions.cmake`       |    X     | Functions and macros                                                     |
+| `ctest-CTestConfig.cmake`     |          | Required file that is copied into the build directory at configure time. |
+
+The _guarded_ files use the CMake command [`include_guard()`][1] which should prevent that file
+from being include more than once in an include chain.
+
+Options and Variables (`simple_testing.cmake`)
+----------------------------------------------
+The `simple_testing.cmake` file has a number of optional parameters that can be sent into the
+CMake system via `-D<VARNAME>:BOOL=<ON|OFF>` parameters:
+
+| Option                     | Required? | Default                                     | PR Override | Purpose                          |
+|----------------------------|:---------:|---------------------------------------------|-------------|----------------------------------|
+| `build_name`               |    YES    | N/A                                         | YES         | Sets `CTEST_BUILD_NAME`          |
+| `ctest_submit_retry_count` |    NO     | 5                                           |             |                                  |
+| `ctest_submit_retry_delay` |    NO     | 3                                           |             |                                  |
+| `dashboard_model`          |    NO     | `Experimental`                              | YES but NO  | Set to the same value as default |
+| `dashboard_track`          |    NO     | `Experimental`                              | YES but NO  | Set to the same value as default |
+| `skip_by_parts_submit`     |    NO     | `ON`                                        | YES         |                                  |
+| `skip_clean_build_dir`     |    NO     | `ON`                                        |             |                                  |
+| `skip_single_submit`       |    NO     | `ON`                                        |             |                                  |
+| `skip_update_step`         |    NO     | `OFF`                                       | YES         |                                  |
+| `skip_upload_config_files` |    NO     | `OFF`                                       |             |                                  |
+| `PARALLEL_LEVEL`           |    NO     | _num cores_                                 | YES         |                                  |
+| `TEST_PARALLEL_LEVEL`      |    NO     | `${PARALLEL_LEVEL}`                         | YES         |                                  |
+| `build_root`               |    NO     | `${CTEST_SOURCE_DIRECTORY}/nightly_testing` |             |                                  |
+| `build_dir`                |    NO     | `${build_root}/${CTEST_BUILD_NAME}`         | YES         | The CMake build dir              |
+| `configure_script`         |    YES    | N/A                                         | YES         | See note below table             |
+| `package_enables`          |    YES    | N/A                                         | YES         | `packageEnables.cmake`           |
+| `subprojects_file`         |    YES    | N/A                                         | YES         | `package_subproject_list.cmake`  |
+
+1. `configure_script` points to the `cmake/std/PullRequestLinux<COMPILER><COMPILER_VERSION>TestingSettings.cmake` file.
+    - Example: `${WORKSPACE}/Trilinos/cmake/std/PullRequestLinuxGCC8.3.0TestingSettings.cmake`
+
+See `TrilinosPRConfigurationStandard.py`[2] for information on what options are set to something
+other than the default during normal Trilinos PR operations.
+
+Expected Operation
+------------------
+The expected operation of this set of files to replace the old `simple_testing.cmake` is to load
+the [`ctest-driver.cmake`](ctest-driver.cmake) file in its place.
+
+
+`ctest-driver.cmake` Options
+----------------------------
+
+| Option                     | Type   | Required? | Default                                       | Description                                                        |
+|----------------------------|--------|:---------:|-----------------------------------------------|--------------------------------------------------------------------|
+| `build_name`               | STRING |    YES    | N/A                                           | The build name, see Jenkins' `${JOB_NAME}` envvar.                 |
+| `subprojects_file`         | STRING |    YES    | N/A                                           | This is the `package_subproject_list.cmake` file.                  |
+| `source_dir`               | PATH   |    YES    | N/A                                           | Path to the source directory.                                      |
+| `configure_script`         | STRING |    YES    | N/A                                           | Test settings CMake script.                                        |
+| `package_enables`          | STRING |    YES    | N/A                                           | This is the `packageEnables.cmake` file.                           |
+| `ctest_submit_retry_count` | STRING |    NO     | 5                                             | Number of times to retry a ctest submssion.                        |
+| `ctest_submit_retry_delay` | STRING |    NO     | 3                                             | Delay (seconds) between attempts to submit to cdash.               |
+| `dashboard_model`          | STRING |    NO     | Experimental                                  | CDash model                                                        |
+| `dashboard_track`          | STRING |    NO     | Experimental                                  | CDash track                                                        |
+| `skip_clean_build_dir`     | BOOL   |    NO     | ON                                            | Skip cleaning the build directory (`ctest_empty_binary_directory`) |
+| `skip_update_step`         | BOOL   |    NO     | OFF                                           | Skip the update step (`ctest_update()`) of the repository.         |
+| `skip_by_parts_submit`     | BOOL   |    NO     | ON                                            | Skip submission to CDash after each phase.                         |
+| `skip_single_submit`       | BOOL   |    NO     | ON                                            | Skip single submission                                             |
+| `skip_upload_config_files` | BOOL   |    NO     | OFF                                           | Skip upload config files (???)                                     |
+| `build_root`               | STRING |    NO     | `${source_dir}/nightly_testing`               | Used to generate `build_dir` if `build_dir` is not defined.        |
+| `build_dir`                | STRING |    NO     | `${build_root}/${CTEST_BUILD_NAME}`           | Path to the build directory.                                       |
+| `PARALLEL_LEVEL`           | STRING |    NO     | `<num cores>`                                 |                                                                    |
+| `TEST_PARALLEL_LEVEL`      | STRING |    NO     | `${PARALLEL_LEVEL}`                           |                                                                    |
+
+1. It might worthwhile to remove `build_root` since it's only used to create `build_dir` IF `build_dir` is not passed in
+   via a `-D` option.
+2. Related to (1), we might also change `build_dir` to be `BUILD_DIR` and pass that in.
+
+
+
+Example CTest call from a Trilinos PR
+-------------------------------------
+This is an example, for reference, of how the `ctest` command is invoked in the current/old Trilinos
+PR test driver.
+```bash
+ctest \
+   -S simple_testing.cmake \
+   -Dsource_dir=${WORKSPACE}/Trilinos \
+   -Dbuild_name=PR-9495-test-Trilinos_pullrequest_gcc_8.3.0-5164 \
+   -Dskip_by_parts_submit=OFF \
+   -Dskip_update_step=ON \
+   -Ddashboard_model=Experimental \
+   -Ddashboard_track=Pull Request \
+   -DPARALLEL_LEVEL=20 \
+   -DTEST_PARALLEL_LEVEL=4 \
+   -Dbuild_dir=${WORKSPACE}/pull_request_test \
+   -Dconfigure_script=${WORKSPACE}/Trilinos/cmake/std/PullRequestLinuxGCC8.3.0TestingSettings.cmake \
+   -Dpackage_enables=../packageEnables.cmake \
+   -Dsubprojects_file=../package_subproject_list.cmake
+```
+
+Additional Notes and Pitfalls
+=============================
+
+`ctest_test()` and `CAPTURE_CMAKE_ERROR`
+----------------------------------------
+For Trilinos testing we should avoid checking the value returned by `ctest_test()`
+for the `CAPTURE_CMAKE_ERROR` parameter. The reason for this is that CTest will
+flag this as an error (i.e., -1 is returned) if there were _no tests run_.
+
+The _no tests were run_ though is a valid 'success' result for Trilinos PR tests since
+this project enables packages dynamically based on what packages have modifications.
+This allows some PR's to go through without building Trilinos, which is advantageous
+when only documentation or perhaps the testing framework itself is modified and we do
+not need to spend O(5 hours) for the test suite to run.
+
+[1]: https://cmake.org/cmake/help/latest/command/include_guard.html
+[2]: https://github.com/trilinos/Trilinos/blob/master/cmake/std/trilinosprhelpers/TrilinosPRConfigurationStandard.py
diff --git a/cmake/SimpleTesting/cmake/ctest-CTestConfig.cmake b/cmake/SimpleTesting/cmake/ctest-CTestConfig.cmake
@@ -0,0 +1,38 @@
+# This file will be copied to "CTestConfig.cmake" and should be placed
+# in the ${CTEST_BINARY_DIRECTORY} directory.
+#
+# https://cmake.org/cmake/help/latest/module/CTest.html
+message(">>> CTestConfig.cmake STARTED")
+
+# Must match what is in CDash project 'Trilinos'
+set(CTEST_NIGHTLY_START_TIME "04:00:00 UTC") # 10 PM MDT or 9 PM MST
+
+
+if (NOT DEFINED CTEST_DROP_METHOD)
+    set(CTEST_DROP_METHOD "http")
+endif()
+
+
+# Temporarily changing TEST_DROP_SITE from testing-vm.sandia.gov to
+# testing.sandia.gov due to the broken CDash installation
+if (CTEST_DROP_METHOD STREQUAL "http")
+    set(CTEST_PROJECT_NAME "Trilinos")
+    if (NOT DEFINED CTEST_DROP_SITE)
+        set(CTEST_DROP_SITE "testing.sandia.gov")
+    endif()
+
+    if (${CTEST_DROP_SITE} STREQUAL "testing.sandia.gov")
+    	set(CTEST_DROP_LOCATION "/cdash/submit.php?project=${CTEST_PROJECT_NAME}")
+    else()
+	set(CTEST_DROP_METHOD "https")
+	set(CTEST_DROP_LOCATION "/submit.php?project=${CTEST_PROJECT_NAME}")
+    endif()
+
+    set(CTEST_TRIGGER_SITE "")
+    set(CTEST_DROP_SITE_CDASH TRUE)
+    message(">>> CTEST_DROP_SITE     : ${CTEST_DROP_SITE}")
+    message(">>> CTEST_DROP_LOCATION : ${CTEST_DROP_LOCATION}")
+    message(">>> CTEST_PROJECT_NAME  : ${CTEST_PROJECT_NAME}")
+endif()
+
+message(">>> CTestConfig.cmake FINISHED")
diff --git a/cmake/SimpleTesting/cmake/ctest-cdash-setup.cmake b/cmake/SimpleTesting/cmake/ctest-cdash-setup.cmake
@@ -0,0 +1,142 @@
+include_guard()
+message("+--------------------------------------+")
+message("| ctest-cdash-setup.cmake START        |")
+message("+--------------------------------------+")
+include(${CMAKE_CURRENT_LIST_DIR}/ctest-functions.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/ctest-common.cmake)
+
+
+
+# ===============================================================================
+# --
+# -- Set up the Dashboard and Testing Infrastructure
+# --
+# ===============================================================================
+print_options_list()
+
+# -----------------------------------------------------------
+# -- Specify the Generator
+# -----------------------------------------------------------
+set(CTEST_CMAKE_GENERATOR "Ninja")
+
+
+set(CTEST_CONFIGURE_COMMAND_ARGS
+    "${CMAKE_COMMAND}"
+    "-C \"${configure_file}\""
+    "-C \"${package_enables_file}\""
+    "-G \"${CTEST_CMAKE_GENERATOR}\""
+    "${CTEST_SOURCE_DIRECTORY}"
+)
+
+list(JOIN CTEST_CONFIGURE_COMMAND_ARGS " " CTEST_CONFIGURE_COMMAND)
+
+banner("CMake Configuration Command")
+message(">>> CTEST_CONFIGURE_COMMAND : ${CTEST_CONFIGURE_COMMAND}")
+message(">>>")
+
+
+
+# -----------------------------------------------------------
+# -- Configure Preparation
+# -----------------------------------------------------------
+
+# Optionally skip cleaning the build directory
+if(NOT skip_clean_build_dir)
+    ctest_empty_binary_directory(${CTEST_BINARY_DIRECTORY})
+endif()
+
+# Optionally upload the config files
+# TODO: Note how this works / what it's doing in CMake-land.
+message(">>> Write `configure_command_file`:")
+if(skip_upload_config_files)
+    message(">>> - SKIPPED")
+else()
+    message(">>> - WRITTEN")
+    #message(">>> - configure_command_file : ${configure_command_file}")
+    #message(">>> - CTEST_CONFIGURE_COMMAND: ${CTEST_CONFIGURE_COMMAND}")
+    file(WRITE ${configure_command_file} ${CTEST_CONFIGURE_COMMAND})
+endif()
+message(">>>")
+
+
+# -----------------------------------------------------------
+# -- COPY files
+# -- ctest-CTestConfig.cmake -> ${CTEST_BINARY_DIRECTORY}/CTestConfig.cmake
+# -- See: https://cmake.org/cmake/help/latest/command/configure_file.html
+# -----------------------------------------------------------
+banner("Copy CTestConfig.cmake to BUILD dir")
+configure_file(${CMAKE_CURRENT_LIST_DIR}/ctest-CTestConfig.cmake ${CTEST_BINARY_DIRECTORY}/CTestConfig.cmake COPYONLY)
+
+
+# -----------------------------------------------------------
+# -- Start the testing engine
+# -- CTEST_DROP_LOCATION defined in ctest-CTestConfig.cmake
+# -- See: https://cmake.org/cmake/help/latest/command/ctest_start.html
+# -----------------------------------------------------------
+banner("ctest_start() START")
+ctest_start(${dashboard_model} GROUP ${dashboard_track})
+banner("ctest_start() FINISH")
+message(">>> CTEST_DROP_LOCATION = ${CTEST_DROP_LOCATION}")
+message(">>>")
+
+# -----------------------------------------------------------
+# -- Configure CDash Drop URLs
+# -- CTEST_DROP_SITE is defined in ctest-CTestConfig.cmake
+# -- CTEST_PROJECT_NAME is defined in ctest-CTestConfig.cmake
+# -- CTEST_BUILD_NAME is defined in ctest-common.cmake
+# -- URL_location is defined here
+# -- build_stamp is defined here
+# -- machine_name is defined here
+# -----------------------------------------------------------
+
+string(FIND ${CTEST_DROP_LOCATION} submit.php index)
+string(SUBSTRING ${CTEST_DROP_LOCATION} 0 ${index} URL_location)
+
+file(STRINGS ${CTEST_BINARY_DIRECTORY}/Testing/TAG tag_strings LIMIT_COUNT 2)
+foreach(item ${tag_strings})
+    set(build_stamp_tmp "${build_stamp_tmp}-${item}")
+endforeach()
+# strip initial "-" using this method to avoid having to calculate string length
+string(SUBSTRING ${build_stamp_tmp} 1 1024 build_stamp)
+
+generate_build_url1(build_url1 ${CTEST_DROP_SITE} ${URL_location} ${CTEST_PROJECT_NAME} ${CTEST_BUILD_NAME} ${build_stamp} ${machine_name})
+generate_build_url2(build_url2 ${CTEST_DROP_SITE} ${URL_location} ${CTEST_PROJECT_NAME} ${CTEST_BUILD_NAME} ${build_stamp})
+generate_build_url3(build_url3 ${CTEST_DROP_SITE} ${URL_location} ${CTEST_PROJECT_NAME} ${CTEST_BUILD_NAME} ${build_stamp})
+message(">>> CDash URL1 = ${build_url1}")
+message(">>> CDash URL2 = ${build_url2}")
+message(">>> CDash URL3 = ${build_url3}")
+
+# -----------------------------------------------------------
+# -- Optionally update the repository
+# -- skip_update_step defined in ctest-common.cmake
+# -- skip_by_parts_submit defined in ctest-common.cmake
+# -----------------------------------------------------------
+# TODO: Do we really do this in the Trilinos CTest framework?
+#       Or is this all handled by the framework code around
+#       pulling in the source/target branches and merging them?
+#       If we don't use this, consider removing.
+banner("Update repository START")
+if(NOT skip_update_step)
+    message(">>> Updating repository")
+    ctest_update(RETURN_VALUE update_error)
+    if(${update_error} EQUAL -1)
+        message(WARNING ">>> Update failed. ")
+    else()
+        message(">>> Updated ${update_error} files.")
+    endif()
+    submit_by_parts("Update")
+else()
+    set(CTEST_UPDATE_VERSION_ONLY ON)
+    ctest_update(RETURN_VALUE update_error)
+    if(${update_error} EQUAL -1)
+        message(WARNING ">>> Update failed. ")
+    else()
+        message(">>> Updated ${update_error} files.")
+    endif()
+    submit_by_parts("Update")
+endif()
+banner("Update repository FINISH")
+
+message("+--------------------------------------+")
+message("| ctest-cdash-setup.cmake FINISH       |")
+message("+--------------------------------------+")