aws-crt 0.1.5 → 0.1.6

data/aws-crt-ffi/crt/s2n/tests/litani/README.md

@@ -1,34 +1,56 @@
-AWS Build Accumulator
+Litani
 =
 
-AWS Build Accumulator collects build jobs from multiple sources before executing them
-concurrently. It provides platform-independent job control (timeouts,
-return code control) and an output format that is easy to render into
-reports (for example, using the built-in renderer).  AWS Build Accumulator
-shines where your project uses multiple different build systems or requires
-a unified interface describing heterogeneous build jobs.
+Litani is a build system that provides an HTML dashboard of job results, as well
+as a JSON-formatted record of job results. It provides platform-independent job
+control (timeouts, return code control) and an output format that is easy to
+render into reports (for example, using the built-in renderer).
 
 ### Documentation
 
-Hosted [here](https://awslabs.github.io/aws-build-accumulator/).
+Hosted [here](https://awslabs.github.io/aws-build-accumulator/). The Homebrew
+and Debian packages also install the man pages locally, try
+`man litani-add-job`.
 
 
-### Requirements
+### Installation
 
-* Python 3
+To install with [Homebrew](https://brew.sh):
+
+```bash
+brew install litani
+```
+
+On Ubuntu, Install Litani by downloading the `*.deb` package built by each release,
+available on the
+[releases](https://github.com/awslabs/aws-build-accumulator/releases) page and
+run
+
+```bash
+apt install -y litani-x.xx.x.deb  # where x.xx.x is the release version.
+```
+
+
+### Dependencies
+
+If you are cloning the source code, you will need the following dependencies:
+
+#### Required
+
+* Python3
 * [Ninja](https://ninja-build.org/)
   * `apt-get install ninja-build`, `brew install ninja`
 * [Jinja](https://jinja.palletsprojects.com/en/2.11.x/)
   * `pip3 install jinja2`
-* [Graphviz DOT](https://graphviz.org/)
-  * `apt-get install graphviz`, `brew install graphviz`
 
-Recommended:
+#### Recommended
 
+* [Graphviz DOT](https://graphviz.org/)
+  * `apt-get install graphviz`, `brew install graphviz`
 * [Gnuplot](http://www.gnuplot.info/) to generate graphs on the dashboard
   * `apt-get install gnuplot`, `brew install gnuplot`
 
-Optional:
+#### Optional
 
 * [Voluptuous](https://pypi.org/project/voluptuous/) to perform
   sanity-checking on internal data structures

data/aws-crt-ffi/crt/s2n/tests/litani/THIRD-PARTY

@@ -1,44 +1,208 @@
-** ninja; version 1.8.2-1 -- https://ninja-build.org/
-
-Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Name: ninja
-Upstream-Contact: martine@danga.com
-Source: https://ninja-build.org/
-
-Files: *
-Copyright: 2011-2014 Google
-License: Apache-2.0
-
-Files: src/getopt.*
-Copyright: 1997 Gregory Pietsch
-License: other
- This file and the accompanying getopt.h header file are hereby placed in the
- public domain without restrictions.  Just give the author credit, don't
- claim you wrote it or prevent anyone else from using it.
- .
- Gregory Pietsch's current e-mail address:
- gpietsch@comcast.net
-
-Files: debian/*
-Copyright: 2012 Gary Kramlich
-           2016 Felix Geyer
-License: Apache-2.0
-
-License: Apache-2.0
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
- .
- http://www.apache.org/licenses/LICENSE-2.0
- .
- Unless required by applicable law or agreed to in writing, software
- distributed under the License 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.
- .
- On Debian systems, the complete text of the Apache version 2.0 license
- can be found in "/usr/share/common-licenses/Apache-2.0".
+** ninja; version 1.10.2 -- https://ninja-build.org/
+ 
+
+                                 Apache License
+                           Version 2.0, January 2010
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License 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.
 
 * For ninja see also this required NOTICE:
     Copyright 2015 Google Inc. All Rights Reserved
+

data/aws-crt-ffi/crt/s2n/tests/litani/doc/bin/build-html-doc

@@ -33,7 +33,7 @@ def get_args():
             "required": True,
             "type": pathlib.Path,
     }, {
-            "flags": ["--roff-html-dir"],
+            "flags": ["--man-html-dir"],
             "required": True,
             "type": pathlib.Path,
     }, {
@@ -50,12 +50,12 @@ def get_args():
     return pars.parse_args()
 
 
-def get_manual(man, roff_html_dir):
+def get_manual(man, man_html_dir):
     record = {
         "title": re.sub("litani-", "litani ", man.stem),
         "anchor": man.stem,
         "body": [],
-        "chapter": get_chapter(roff_html_dir / man.name),
+        "chapter": get_chapter(man_html_dir / man.name),
     }
     with open(man) as handle:
         for line in handle:
@@ -70,14 +70,14 @@ def get_chapter(man_html):
             if m:
                 return int(m["chap"])
     raise UserWarning(
-        f"No line of roff html output '{man_html}' matched chapter pattern "
+        f"No line of man html output '{man_html}' matched chapter pattern "
         f"'{CHAPTER_PAT_STR}'")
 
 
-def get_manuals(html_manuals, roff_html_dir):
+def get_manuals(html_manuals, man_html_dir):
     ret = []
     for man in html_manuals:
-        ret.append(get_manual(man, roff_html_dir))
+        ret.append(get_manual(man, man_html_dir))
     return ret
 
 
@@ -88,7 +88,7 @@ def main():
         autoescape=jinja2.select_autoescape(
             enabled_extensions=('html'),
             default_for_string=True))
-    manuals = get_manuals(args.html_manuals, args.roff_html_dir)
+    manuals = get_manuals(args.html_manuals, args.man_html_dir)
 
     templ = env.get_template("index.jinja.html")
     page = templ.render(manuals=manuals)

data/aws-crt-ffi/crt/s2n/tests/litani/doc/configure

@@ -17,8 +17,6 @@
 import sys
 import pathlib
 
-import jinja2
-
 
 DOC_DIR = pathlib.Path(sys.path[0]).resolve()
 sys.path.insert(1, str(DOC_DIR.parent))
@@ -36,19 +34,19 @@ SRC_DIR = DOC_DIR / "src"
 TEMPLATE_DIR = DOC_DIR / "templates"
 TMP_DIR = DOC_DIR / "tmp"
 
-ROFF_DIR = OUT_DIR / "man"
+MAN_DIR = OUT_DIR / "man"
 
-HTML_MAN_SRC_DIR = TMP_DIR / "roff_to_html"
+HTML_MAN_SRC_DIR = TMP_DIR / "man_to_html"
 HTML_UNIQUE_DIR = TMP_DIR / "html_unique"
 
 
 RULES = [{
-    "name": "sc_to_roff",
-    "description": "converting ${man-name} to roff",
+    "name": "sc_to_man",
+    "description": "converting ${man-name} to man",
     "command": "scdoc < ${in} > ${out}"
 }, {
-    "name": "voluptuous_to_roff",
-    "description": "converting ${man-name} to roff",
+    "name": "voluptuous_to_man",
+    "description": "converting ${man-name} to man",
     "command": f"{BIN_DIR / 'schema-to-scdoc'}"
                f" --project-root { DOC_DIR.parent }"
                " --page-name ${man-name}"
@@ -57,8 +55,8 @@ RULES = [{
                f" { TEMPLATE_DIR / 'voluptuous-man.jinja.scdoc' }"
                " | scdoc > ${out}"
 }, {
-    "name": "roff_to_html",
-    "description": "converting ${man-name}.roff HTML",
+    "name": "man_to_html",
+    "description": "converting ${man-name} HTML",
     "command": "mandoc -O fragment -Thtml < ${in} > ${out}"
 }, {
     "name": "uniquify_header_ids",
@@ -79,7 +77,7 @@ RULES = [{
                "  --html-manuals ${html-mans}"
                f" --template-dir {TEMPLATE_DIR}"
                "  --out-file ${out}"
-               "  --roff-html-dir ${roff-html-dir}"
+               "  --man-html-dir ${man-html-dir}"
 }]
 
 
@@ -97,12 +95,12 @@ def make_html_unique(man, html_man, html_mans, builds):
     html_mans.append(html_unique)
 
 
-def roff_to_html(man, roff_out, builds):
+def man_to_html(man, man_out, builds):
     html_man = HTML_MAN_SRC_DIR / f"{man.stem}.html"
     builds.append({
-        "inputs": [roff_out],
+        "inputs": [man_out],
         "outputs": [html_man],
-        "rule": "roff_to_html",
+        "rule": "man_to_html",
         "variables": {
             "man-name": man.stem,
             "in-file": html_man,
@@ -111,19 +109,25 @@ def roff_to_html(man, roff_out, builds):
     return html_man
 
 
-def convert_man_dir_to_roff(src_dir, dst_dir, rule, html_mans, builds):
+def convert_man_dir_to_man(src_dir, dst_dir, rule, html_mans, builds):
     for man in (src_dir).iterdir():
-        roff_out = dst_dir / f"{man.stem}.roff"
+        if man.suffix == ".scdoc":
+            with open(man) as fp:
+                line = fp.readline().rstrip()
+            index = line[line.find('(')+1:line.find(')')]
+            man_out = dst_dir / f"{man.stem}.{index}"
+        else:
+            man_out = dst_dir / f"{man.stem}.5"
         builds.append({
             "inputs": [man],
-            "outputs": [roff_out],
+            "outputs": [man_out],
             "rule": rule,
             "variables": {
                 "man-name": man.stem,
                 "data-path": man.resolve(),
             }
         })
-        html_man = roff_to_html(man, roff_out, builds)
+        html_man = man_to_html(man, man_out, builds)
         make_html_unique(man, html_man, html_mans, builds)
 
 
@@ -131,10 +135,10 @@ def main():
     builds = []
     html_mans = []
 
-    convert_man_dir_to_roff(
-        SRC_DIR / "man", ROFF_DIR, "sc_to_roff", html_mans, builds)
-    convert_man_dir_to_roff(
-        SRC_DIR / "voluptuous-man", ROFF_DIR, "voluptuous_to_roff", html_mans,
+    convert_man_dir_to_man(
+        SRC_DIR / "man", MAN_DIR, "sc_to_man", html_mans, builds)
+    convert_man_dir_to_man(
+        SRC_DIR / "voluptuous-man", MAN_DIR, "voluptuous_to_man", html_mans,
         builds)
 
     builds.append({
@@ -146,7 +150,7 @@ def main():
         "rule": "build_html_doc",
         "variables": {
             "html-mans": " ".join([str(h) for h in html_mans]),
-            "roff-html-dir": HTML_MAN_SRC_DIR,
+            "man-html-dir": HTML_MAN_SRC_DIR,
         }
     })
 

data/aws-crt-ffi/crt/s2n/tests/litani/doc/src/man/litani-add-job.scdoc

@@ -125,6 +125,13 @@ configure times.
 	job's list of tags is included in its _run.json_ and is intended to help with
 	analyzing run data.
 
+	If 'literal-stdout' is provided as a tag, then the report will render the
+	job's stdout underneath the boxes that indicate the command and its
+	statistics within the associated pipeline's page. If 'front-page-text' is
+	provided as a tag, then the report will render the job's stdout on the
+	front page of the report. These 2 tags allow users to render custom HTML
+	data, e.g. tables, graphs. Examples can be found at 'examples/rich-output'.
+
 *--pipeline-name* _P_
 	The 'pipeline' that this job is part of. A pipeline is a subgraph of the
 	overall build, representing a single 'end-to-end' set of related jobs. A job's

data/aws-crt-ffi/crt/s2n/tests/litani/doc/src/man/litani-dump-run.scdoc

@@ -22,18 +22,18 @@ litani dump-run - Print the current run as a JSON document to stdout
 # SYNOPSIS
 
 *litani dump-run*
-	\[*--retries* _N_]
+	\[*-r*/*--retries* _N_]
+	\[*-o*/*--out-file* _F_]
 
 
 # DESCRIPTION
 
-This program prints the _run.json_ file for an in-progress Litani run to stdout.
+This program prints the run.json file for a Litani run to stdout or to the specified output file.
 The JSON file's schema is documented in *litani-run.json(5)*.
 
 This program is intended to be used while an invocation of *litani-run-build(1)*
-is running. After the *run-build* process has terminated, this program will not
-work (though this may change in future versions). Instead, you can access the
-_run.json_ file in the run's output directory.
+is running. You can access the _run.json_ file in the run's output directory
+both during and after termination of the *run-build* process.
 
 This program may be run as a Litani job, and it may be run as a subprocess from
 a command that is part of a Litani job. This allows commands to 'introspect' on
@@ -63,6 +63,8 @@ _"complete"_ field set to *true*.
 	every second up to the limit given in this flag. If _N_ is *0*, this program
 	will retry indefinitely---this is not recommended.
 
+*-o* _F_, *--out-file* _F_
+	Print the run to _F_ instead of stdout
 
 # OUTPUT