Bump version to 1.26.0

Author: karkhaz

.github/actions/build/action.yaml

@@ -17,6 +17,7 @@ runs:
     - name: Setup directory for deb package
       run: |
         echo ${{ inputs.version }}
+        sudo apt-get update
         sudo apt-get install -y mandoc scdoc ninja-build
         mkdir -p litani-${{ inputs.version }}/{DEBIAN,usr/{bin,libexec/litani,share/{doc/litani,man/{man1,man5,man7}}}}
         touch litani-${{ inputs.version }}/DEBIAN/control

.github/workflows/run-tests.yaml

@@ -9,25 +9,30 @@ jobs:
   test-litani:
     if: "!contains(github.event.pull_request.labels.*.name, 'no-test')"
     name: Run Litani Tests
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - name: Install dependencies
         run: |
-          brew install ninja
+          sudo apt-get install -y ninja-build
           python3 -m pip install jinja2
 
       - name: Run Unit and e2e tests
-        run: ./test/run
-        continue-on-error: true
-        timeout-minutes: 5
+        run: |
+          ./test/run
+          exit $?
 
-      - name: Get absolute path to report dir
-        run: echo "REPORT_PATH=$(readlink test/output/latest/html)" >> $GITHUB_ENV
+  test-build-documentation:
+    name: Test Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y mandoc scdoc ninja-build
 
-      - name: Upload report as artifact
-        uses: actions/upload-artifact@main
-        if: always()
-        with:
-          name: Report
-          path: ${{ env.REPORT_PATH }}
+      - name: Test Documentation
+        run: |
+          ./doc/configure
+          ninja

CHANGELOG

@@ -1,6 +1,29 @@
                               CHANGELOG
                               `````````
 
+Version 1.26.0 -- 2022-05-18
+----------------------------
+
+This release fixes an important bug and contains several other fixes
+and improvements.
+
+- Fix incorrect RC with --fail-on-pipeline-failure
+
+  This fixes an important bug in --fail-on-pipeline-failure.  Prior to
+  this commit, litani run-build would only terminate abnormally with
+  this flag set when ninja terminated abnormally. This commit fixes
+  this behavior so that litani run-build instead checks whether any
+  pipeline failed, and terminates abnormally if so.
+
+  When using --fail-on-pipeline-failure, `litani run-build` will now
+  terminate with an exit code of 0 if all pipelines passed, and 10 if
+  at least one of them failed.
+
+- Fix litani(7) HTML documentation and improve font size and choice
+
+
+
+
 Version 1.25.0 -- 2022-05-18
 ----------------------------
 - Fix litani run.json and litani outcome-table.json man pages

doc/bin/build-html-doc

@@ -57,6 +57,8 @@ def get_manual(man, man_html_dir):
         "body": [],
         "chapter": get_chapter(man_html_dir / man.name),
     }
+    if record["title"] == "litani.7":
+        record["title"] = "litani"
     with open(man) as handle:
         for line in handle:
             record["body"].append(line.rstrip())

doc/src/man/litani-run-build.scdoc

@@ -66,7 +66,10 @@ parallel.
 
 # RETURN CODE
 
-Unless there was a crash, this program should return _0_ upon exit
-unless the *--fail-on-pipeline-failure* flag was supplied. In that case,
-this program will return _0_ if all pipelines were successful and _1_
-otherwise.
+This program will return _1_ if it terminates abnormally. On normal
+termination:
+
+- If the *--fail-on-pipeline-failure* flag was passed, this program will
+  return _0_ if all pipelines were successful and _10_ otherwise.
+- Otherwise, this program will always return _0_ upon normal
+  termination, regardless of the pipelines' success or failure.

doc/templates/index.jinja.html

@@ -56,10 +56,10 @@
     padding-left: 1em;
   }
   body {
-		line-height: 24pt;
     margin: 0;
     font-family: Helvetica, sans-serif;
-    font-size: 16pt;
+    font-size: 12pt;
+		line-height: 14pt;
     color: #3d4d53;
     background-color: #fdf6e3;
     letter-spacing: 1px;
@@ -92,7 +92,7 @@
     color: #fdf6e3; background-color: #859900;
   }
   code {
-    font-size: 13pt;
+    font-size: 10pt;
   }
   pre br {
     display: block;
@@ -137,6 +137,7 @@
     min-height: 2em;
   }
   #corner-email {
+    z-index: 2;
     font-family: Helvetica;
     font-weight: bold;
     letter-spacing: 2px;
@@ -353,8 +354,8 @@
     padding-top: 0.0em;
   }
   h1 {
-    font-size: 48pt;
-    line-height: 48pt;
+    font-size: 33pt;
+    line-height: 54pt;
     text-align: center;
   }
 }

lib/capabilities.py

@@ -36,6 +36,19 @@
 }
 
 
+def add_subparser(subparsers):
+    caps_pars = subparsers.add_parser("print-capabilities",
+            help="Print out Litani's capabilities in a list")
+    caps_pars.set_defaults(func=dump)
+    for arg in [{
+            "flags": ["-r", "--human-readable"],
+            "help": "also print out capabilities with their descriptions",
+            "action": "store_true"
+    }]:
+        flags = arg.pop("flags")
+        caps_pars.add_argument(*flags, **arg)
+
+
 def _human_readable_dump():
     longest_capability = 0
     for capability in _CAPABILITIES:

lib/exec.py

@@ -0,0 +1,161 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the "license" file accompanying this file. This file is distributed
+# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+# express or implied. See the License for the specific language governing
+# permissions and limitations under the License
+
+import __main__
+
+import json
+import logging
+import os
+import pathlib
+import shutil
+import shlex
+import sys
+
+from lib import litani
+import lib.jobs
+import lib.output_artifact
+import lib.util
+
+
+def get_exec_job_args():
+    exec_job_args = list(lib.jobs.get_add_job_args())
+    exec_job_args.append((
+        "`litani exec`-specific flags", [{
+            "flags": ["--status-file"],
+            "metavar": "F",
+            "required": True,
+            "help": "JSON file to write command status to",
+    }, {
+            "flags": ["--job-id"],
+            "metavar": "ID",
+            "required": True,
+            "help": "the globally unique job ID",
+    }]))
+    return exec_job_args
+
+
+def add_subparser(subparsers):
+    exec_job_pars = subparsers.add_parser("exec")
+    exec_job_pars.set_defaults(func=exec_job)
+    for group_name, args in get_exec_job_args():
+        group = exec_job_pars.add_argument_group(title=group_name)
+        for arg in args:
+            flags = arg.pop("flags")
+            group.add_argument(*flags, **arg)
+
+
+def make_litani_exec_command(add_args):
+    cmd = [os.path.realpath(__main__.__file__), "exec"]
+    # strings
+    for arg in [
+            "command", "pipeline_name", "ci_stage", "cwd", "job_id",
+            "stdout_file", "stderr_file", "description", "timeout",
+            "status_file", "outcome_table", "pool",
+            "profile_memory_interval",
+    ]:
+        if arg in add_args and add_args[arg]:
+            cmd.append("--%s" % arg.replace("_", "-"))
+            cmd.append(shlex.quote(str(add_args[arg]).strip()))
+
+    # lists
+    for arg in [
+            "inputs", "outputs", "ignore_returns", "ok_returns",
+            "tags", "phony_outputs",
+    ]:
+        if arg not in add_args or add_args[arg] is None:
+            continue
+        cmd.append("--%s" % arg.replace("_", "-"))
+        for item in add_args[arg]:
+            cmd.append(shlex.quote(str(item).strip()))
+
+    # switches
+    for arg in [
+            "timeout_ignore", "timeout_ok", "interleave_stdout_stderr",
+            "profile_memory",
+    ]:
+        if arg in add_args and add_args[arg]:
+            cmd.append("--%s" % arg.replace("_", "-"))
+
+    return " ".join(cmd)
+
+
+async def exec_job(args):
+    args_dict = vars(args)
+    args_dict.pop("func")
+    out_data = {
+        "wrapper_arguments": args_dict,
+        "complete": False,
+    }
+    lib.util.timestamp("start_time", out_data)
+    with litani.atomic_write(args.status_file) as handle:
+        print(json.dumps(out_data, indent=2), file=handle)
+
+    run = lib.process.Runner(
+        args.command, args.interleave_stdout_stderr, args.cwd,
+        args.timeout, args.profile_memory, args.profile_memory_interval,
+        args_dict["job_id"])
+    await run()
+    lib.job_outcome.fill_in_result(run, out_data, args)
+
+    for out_field, proc_pipe, arg_file in [
+        ("stdout", run.get_stdout(), args.stdout_file),
+        ("stderr", run.get_stderr(), args.stderr_file)
+    ]:
+        if proc_pipe:
+            out_data[out_field] = proc_pipe.splitlines()
+        else:
+            out_data[out_field] = []
+
+        if arg_file:
+            out_str = proc_pipe if proc_pipe else ""
+            with litani.atomic_write(arg_file) as handle:
+                print(out_str, file=handle)
+
+    if out_data["stderr"]:
+        print(
+            "\n".join([l.rstrip() for l in out_data["stderr"]]),
+            file=sys.stderr)
+
+    lib.util.timestamp("end_time", out_data)
+    out_str = json.dumps(out_data, indent=2)
+    logging.debug("run status: %s", out_str)
+    with litani.atomic_write(args.status_file) as handle:
+        print(out_str, file=handle)
+
+    artifacts_dir = (litani.get_artifacts_dir() /
+         out_data["wrapper_arguments"]["pipeline_name"] /
+         out_data["wrapper_arguments"]["ci_stage"])
+    artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+    copier = lib.output_artifact.Copier(
+        artifacts_dir, out_data["wrapper_arguments"])
+    for fyle in out_data["wrapper_arguments"]["outputs"] or []:
+        try:
+            copier.copy_output_artifact(fyle)
+        except lib.output_artifact.MissingOutput:
+            logging.warning(
+                "Output file '%s' of pipeline '%s' did not exist upon job "
+                "completion. Not copying to artifacts directory. "
+                "If this job is not supposed to emit the file, pass "
+                "`--phony-outputs %s` to suppress this warning", fyle,
+                out_data["wrapper_arguments"]["pipeline_name"], fyle)
+        except IsADirectoryError:
+            artifact_src = pathlib.Path(fyle)
+            try:
+                shutil.copytree(
+                    fyle, str(artifacts_dir / artifact_src.name))
+            except FileExistsError:
+                logging.warning(
+                    "Multiple files with same name in artifacts directory")
+
+    sys.exit(out_data["wrapper_return_code"])

lib/graph.py

@@ -22,6 +22,18 @@
 import lib.litani_report
 
 
+def add_subparser(subparsers):
+    graph_pars = subparsers.add_parser("graph")
+    graph_pars.set_defaults(func=print_graph)
+    for arg in [{
+            "flags": ["-p", "--pipelines"],
+            "help": "only display the graph for these pipelines (default: all)",
+            "nargs": "+",
+            "metavar": "P",
+    }]:
+        flags = arg.pop("flags")
+        graph_pars.add_argument(*flags, **arg)
+
 
 class Node:
     @staticmethod