olcf · hagertnl · Dec 19, 2024 · Dec 19, 2024 · Dec 19, 2024 · Dec 27, 2024
diff --git a/doc-sphinx/source/user_guide/adding_new_test.rst b/doc-sphinx/source/user_guide/adding_new_test.rst
@@ -26,11 +26,15 @@ The application repository must be structured as shown below:
 
 .. code-block::
 
-    <application name>/<test name>/Scripts/
+    <application name>/<test name>/
+                                   Scripts/
                                           /rgt_test_input.ini
                                           /<check script>
                                           /<report script>
                                           /<job script template>
+                                   Source/ (optional)
+                                         /<an alternate build script just for this test>
+                                         /<a modified source file>
     <application name>/Source/
                              /<build script>
                              /<other application source and build files>
@@ -44,6 +48,8 @@ and other required scripts (see :ref:`required-application-test-scripts` below).
 This directory contains templates and input files for the test -- a test must not modify files in this directory.
 
 Second, the application's source code and required build script should reside within the *Source* directory of the repository.
+Optionally, a test may add or override files from the application's *Source* tree by providing a *Source* directory within the test directory.
+This directory will be overlayed over the application *Source* directory, so it may use the same internal directory structure.
 
 Example Repository Structure
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -59,6 +65,7 @@ To add a single node test and a two node test, we would create a separate subdir
              /Source
 
 Note that the test names are not required to follow any specific naming convention, but you should avoid spaces and special characters in the names.
+Since these tests are going to share the same source and build script, we are not going to create a *Source* subdirectory in either of the tests' subdirectories.
 
 .. _application-test-input:
 
@@ -207,7 +214,8 @@ An example SLURM template script for the *hello_mpi* application follows:
     cd $WORK_DIR
 
     env &> job.environ
-    scontrol show hostnames > job.nodes
+    scontrol show hostnames &> job.nodes
+    ldd $BUILD_DIR/bin/$EXECUTABLE &> ldd.log
 
     # Run the executable.
     log_binary_execution_time.py --scriptsdir $SCRIPTS_DIR --uniqueid $HARNESS_ID --mode start

diff --git a/doc-sphinx/source/user_guide/envvars.rst b/doc-sphinx/source/user_guide/envvars.rst
@@ -89,6 +89,7 @@ These variables are detailed below:
     RGT_APP_SOURCE_DIR          Path to the 'Source' directory of the current application.
     RGT_TEST_BUILD_DIR          Path to the build directory of the currently-running test.
     RGT_TEST_RUNARCHIVE_DIR     Path to the run archive directory of the currently-running test.
+    RGT_TEST_SOURCE_DIR         Path to the source overlay directory of the currently-running test.
     RGT_TEST_SCRIPTS_DIR        Path to the scripts directory of the currently-running test.
     RGT_TEST_STATUS_DIR         Path to the status directory of the currently-running test.
     RGT_TEST_WORK_DIR           Path to the work (scratch) directory of the currently-running test.

diff --git a/doc-sphinx/source/user_guide/launching.rst b/doc-sphinx/source/user_guide/launching.rst
@@ -19,8 +19,8 @@ This can be done in two ways: by obtaining your own copy of the code or using th
 Option 1: Using the centralized (pre-built) OTH
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On Andes, Crusher, Frontier, and Summit
-"""""""""""""""""""""""""""""""""""""""
+On Andes and Frontier
+"""""""""""""""""""""
 
 On most OLCF machines, the code is already installed in: */sw/acceptance/olcf-test-harness*
 
@@ -31,7 +31,7 @@ Setup the environment:
     export OLCF_HARNESS_DIR=/sw/acceptance/olcf-test-harness
     module use $OLCF_HARNESS_DIR/modulefiles
     module load olcf_harness
-    # Machine name examples: andes, crusher, frontier, summit
+    # Machine name examples: andes, frontier, odo
     # Check ${OLCF_HARNESS_DIR}/configs/*.ini to see all available machines
     export OLCF_HARNESS_MACHINE=<machine_name>
 

diff --git a/docs/_sources/user_guide/adding_new_test.rst.txt b/docs/_sources/user_guide/adding_new_test.rst.txt
@@ -26,11 +26,15 @@ The application repository must be structured as shown below:
 
 .. code-block::
 
-    <application name>/<test name>/Scripts/
+    <application name>/<test name>/
+                                   Scripts/
                                           /rgt_test_input.ini
                                           /<check script>
                                           /<report script>
                                           /<job script template>
+                                   Source/ (optional)
+                                         /<an alternate build script just for this test>
+                                         /<a modified source file>
     <application name>/Source/
                              /<build script>
                              /<other application source and build files>
@@ -44,6 +48,8 @@ and other required scripts (see :ref:`required-application-test-scripts` below).
 This directory contains templates and input files for the test -- a test must not modify files in this directory.
 
 Second, the application's source code and required build script should reside within the *Source* directory of the repository.
+Optionally, a test may add or override files from the application's *Source* tree by providing a *Source* directory within the test directory.
+This directory will be overlayed over the application *Source* directory, so it may use the same internal directory structure.
 
 Example Repository Structure
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -59,6 +65,7 @@ To add a single node test and a two node test, we would create a separate subdir
              /Source
 
 Note that the test names are not required to follow any specific naming convention, but you should avoid spaces and special characters in the names.
+Since these tests are going to share the same source and build script, we are not going to create a *Source* subdirectory in either of the tests' subdirectories.
 
 .. _application-test-input:
 
@@ -207,7 +214,8 @@ An example SLURM template script for the *hello_mpi* application follows:
     cd $WORK_DIR
 
     env &> job.environ
-    scontrol show hostnames > job.nodes
+    scontrol show hostnames &> job.nodes
+    ldd $BUILD_DIR/bin/$EXECUTABLE &> ldd.log
 
     # Run the executable.
     log_binary_execution_time.py --scriptsdir $SCRIPTS_DIR --uniqueid $HARNESS_ID --mode start

diff --git a/docs/_sources/user_guide/envvars.rst.txt b/docs/_sources/user_guide/envvars.rst.txt
@@ -89,6 +89,7 @@ These variables are detailed below:
     RGT_APP_SOURCE_DIR          Path to the 'Source' directory of the current application.
     RGT_TEST_BUILD_DIR          Path to the build directory of the currently-running test.
     RGT_TEST_RUNARCHIVE_DIR     Path to the run archive directory of the currently-running test.
+    RGT_TEST_SOURCE_DIR         Path to the source overlay directory of the currently-running test.
     RGT_TEST_SCRIPTS_DIR        Path to the scripts directory of the currently-running test.
     RGT_TEST_STATUS_DIR         Path to the status directory of the currently-running test.
     RGT_TEST_WORK_DIR           Path to the work (scratch) directory of the currently-running test.

diff --git a/docs/_sources/user_guide/launching.rst.txt b/docs/_sources/user_guide/launching.rst.txt
@@ -19,8 +19,8 @@ This can be done in two ways: by obtaining your own copy of the code or using th
 Option 1: Using the centralized (pre-built) OTH
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On Andes, Crusher, Frontier, and Summit
-"""""""""""""""""""""""""""""""""""""""
+On Andes and Frontier
+"""""""""""""""""""""
 
 On most OLCF machines, the code is already installed in: */sw/acceptance/olcf-test-harness*
 
@@ -31,7 +31,7 @@ Setup the environment:
     export OLCF_HARNESS_DIR=/sw/acceptance/olcf-test-harness
     module use $OLCF_HARNESS_DIR/modulefiles
     module load olcf_harness
-    # Machine name examples: andes, crusher, frontier, summit
+    # Machine name examples: andes, frontier, odo
     # Check ${OLCF_HARNESS_DIR}/configs/*.ini to see all available machines
     export OLCF_HARNESS_MACHINE=<machine_name>
 

diff --git a/docs/_static/basic.css b/docs/_static/basic.css
@@ -236,16 +236,6 @@ div.body p, div.body dd, div.body li, div.body blockquote {
 a.headerlink {
     visibility: hidden;
 }
-a.brackets:before,
-span.brackets > a:before{
-    content: "[";
-}
-
-a.brackets:after,
-span.brackets > a:after {
-    content: "]";
-}
-
 
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
@@ -334,11 +324,15 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
+nav.contents,
+aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
+nav.contents,
+aside.topic,
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -377,13 +371,17 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
 }
 
 div.sidebar::after,
 aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -608,19 +606,26 @@ ol.simple p,
 ul.simple p {
     margin-bottom: 0;
 }
-dl.footnote > dt,
-dl.citation > dt {
+aside.footnote > span,
+div.citation > span {
     float: left;
-    margin-right: 0.5em;
 }
-
-dl.footnote > dd,
-dl.citation > dd {
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
     margin-bottom: 0em;
 }
-
-dl.footnote > dd:after,
-dl.citation > dd:after {
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
     content: "";
     clear: both;
 }
@@ -636,10 +641,6 @@ dl.field-list > dt {
     padding-left: 0.5em;
     padding-right: 5px;
 }
-dl.field-list > dt:after {
-    content: ":";
-}
-
 
 dl.field-list > dd {
     padding-left: 0.5em;

diff --git a/docs/_static/pygments.css b/docs/_static/pygments.css
@@ -17,7 +17,6 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left:
 .highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
 .highlight .gd { color: #A00000 } /* Generic.Deleted */
 .highlight .ge { font-style: italic } /* Generic.Emph */
-.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
 .highlight .gr { color: #FF0000 } /* Generic.Error */
 .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
 .highlight .gi { color: #00A000 } /* Generic.Inserted */

diff --git a/docs/developer_guide/intro.html b/docs/developer_guide/intro.html
@@ -4,7 +4,8 @@
 <html class="writer-html5" lang="en" >
 <head>
   <meta charset="utf-8" />
-
+  <meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
   <title>Introduction &mdash; NCCS_Test_Harness 1.0 documentation</title>
@@ -108,7 +109,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../user_guide/launching.html">Quick-Start Guide</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="../user_guide/launching.html#installation">Installation</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="../user_guide/launching.html#option-1-using-the-centralized-pre-built-oth">Option 1: Using the centralized (pre-built) OTH</a><ul>
-<li class="toctree-l4"><a class="reference internal" href="../user_guide/launching.html#on-andes-crusher-frontier-and-summit">On Andes, Crusher, Frontier, and Summit</a></li>
+<li class="toctree-l4"><a class="reference internal" href="../user_guide/launching.html#on-andes-and-frontier">On Andes and Frontier</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="../user_guide/launching.html#option-2-using-your-own-copy-of-the-harness">Option 2: Using your own copy of the harness</a></li>
@@ -242,11 +243,11 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
 
-  <div class="section" id="introduction">
+  <section id="introduction">
 <h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this heading">¶</a></h1>
 <div class="toctree-wrapper compound">
 </div>
-<div class="section" id="raison-d-etre">
+<section id="raison-d-etre">
 <h2>Raison d’etre<a class="headerlink" href="#raison-d-etre" title="Permalink to this heading">¶</a></h2>
 <p>The OLCF Test Harness, hereafter referred as the Harness, is used for OLCF
 machine acceptances, and is generally designed for Linux
@@ -255,8 +256,8 @@ <h2>Raison d’etre<a class="headerlink" href="#raison-d-etre" title="Permalink
 testing. This is accomplished by repeatedly building applications, submitting these
 applications’ jobs to the job scheduler (PBS, LSF, etc.), and recording the
 results of the applications’ builds and runs.</p>
-</div>
-<div class="section" id="organizational-structure">
+</section>
+<section id="organizational-structure">
 <h2>Organizational Structure<a class="headerlink" href="#organizational-structure" title="Permalink to this heading">¶</a></h2>
 <p>The Harness top-level directory contains the directory <em>.git</em> and is hereafter
 referred to as <em>olcf-test-harness</em>. The Harness organization structure has 4
@@ -278,8 +279,8 @@ <h2>Organizational Structure<a class="headerlink" href="#organizational-structur
     `-- modulefiles/
 </pre></div>
 </div>
-</div>
-<div class="section" id="prequisites">
+</section>
+<section id="prequisites">
 <h2>Prequisites<a class="headerlink" href="#prequisites" title="Permalink to this heading">¶</a></h2>
 <p>The harness requires:</p>
 <blockquote>
@@ -293,16 +294,16 @@ <h2>Prequisites<a class="headerlink" href="#prequisites" title="Permalink to thi
 <li><p>GitLab CI/CD</p></li>
 </ul>
 </div></blockquote>
-</div>
-<div class="section" id="indices-and-tables">
+</section>
+<section id="indices-and-tables">
 <h2>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this heading">¶</a></h2>
 <ul class="simple">
 <li><p><a class="reference internal" href="../genindex.html"><span class="std std-ref">Index</span></a></p></li>
 <li><p><a class="reference internal" href="../py-modindex.html"><span class="std std-ref">Module Index</span></a></p></li>
 <li><p><a class="reference internal" href="../search.html"><span class="std std-ref">Search Page</span></a></p></li>
 </ul>
-</div>
-</div>
+</section>
+</section>
 
 
            </div>

diff --git a/docs/developer_guide/modules.html b/docs/developer_guide/modules.html
@@ -4,7 +4,8 @@
 <html class="writer-html5" lang="en" >
 <head>
   <meta charset="utf-8" />
-
+  <meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
   <title>harness &mdash; NCCS_Test_Harness 1.0 documentation</title>
@@ -108,7 +109,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../user_guide/launching.html">Quick-Start Guide</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="../user_guide/launching.html#installation">Installation</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="../user_guide/launching.html#option-1-using-the-centralized-pre-built-oth">Option 1: Using the centralized (pre-built) OTH</a><ul>
-<li class="toctree-l4"><a class="reference internal" href="../user_guide/launching.html#on-andes-crusher-frontier-and-summit">On Andes, Crusher, Frontier, and Summit</a></li>
+<li class="toctree-l4"><a class="reference internal" href="../user_guide/launching.html#on-andes-and-frontier">On Andes and Frontier</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="../user_guide/launching.html#option-2-using-your-own-copy-of-the-harness">Option 2: Using your own copy of the harness</a></li>
@@ -242,11 +243,11 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
 
-  <div class="section" id="harness">
+  <section id="harness">
 <h1>harness<a class="headerlink" href="#harness" title="Permalink to this heading">¶</a></h1>
 <div class="toctree-wrapper compound">
 </div>
-</div>
+</section>
 
 
            </div>

diff --git a/docs/developer_guide/modules/create_alt_config_file.html b/docs/developer_guide/modules/create_alt_config_file.html
@@ -4,7 +4,8 @@
 <html class="writer-html5" lang="en" >
 <head>
   <meta charset="utf-8" />
-
+  <meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
   <title>create_alt_config_file.py Module Documentation &mdash; NCCS_Test_Harness 1.0 documentation</title>
@@ -108,7 +109,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../user_guide/launching.html">Quick-Start Guide</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="../../user_guide/launching.html#installation">Installation</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="../../user_guide/launching.html#option-1-using-the-centralized-pre-built-oth">Option 1: Using the centralized (pre-built) OTH</a><ul>
-<li class="toctree-l4"><a class="reference internal" href="../../user_guide/launching.html#on-andes-crusher-frontier-and-summit">On Andes, Crusher, Frontier, and Summit</a></li>
+<li class="toctree-l4"><a class="reference internal" href="../../user_guide/launching.html#on-andes-and-frontier">On Andes and Frontier</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="../../user_guide/launching.html#option-2-using-your-own-copy-of-the-harness">Option 2: Using your own copy of the harness</a></li>
@@ -242,9 +243,9 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
 
-  <div class="section" id="create-alt-config-file-py-module-documentation">
+  <section id="create-alt-config-file-py-module-documentation">
 <span id="create-alt-config-file-module"></span><h1>create_alt_config_file.py Module Documentation<a class="headerlink" href="#create-alt-config-file-py-module-documentation" title="Permalink to this heading">¶</a></h1>
-<span class="target" id="module-create_alt_config_file"></span></div>
+<span class="target" id="module-create_alt_config_file"></span></section>
 
 
            </div>