add initial readme and generation scripts (#20)

Change-Id: I0e236fede5a2f0c3ef4e31fa85ce668f4b34004a

BUILD.bazel

@@ -2,6 +2,8 @@ load("@rules_cc//cc:defs.bzl", "cc_library")
 
 package(default_visibility = ["//:__subpackages__"])
 
+exports_files(["README.md"])
+
 filegroup(
     name = "format_config",
     srcs = [".clang-format"],

README.md

@@ -0,0 +1,56 @@
+# skytest
+
+A non-allocating[^1] C++17+ unit test framework.
+
+## overview
+
+A minimal unit test example
+
+```cpp:example/minimal_pass.cpp
+#include "skytest/skytest.hpp"
+
+auto main() -> int
+{
+  using namespace skytest::literals;
+  using ::skytest::expect;
+
+  "truthy"_test = [] { return expect(true); };
+}
+
+```
+
+when run, will print
+
+```console:example/minimal_pass.log
+test `truthy`...[CONSTEXPR PASS]
+all tests passed (1 test)
+
+```
+
+A test that fails
+
+```cpp:example/minimal_fail.cpp
+#include "skytest/skytest.hpp"
+
+auto main(int argc, char*[]) -> int
+{
+  using namespace skytest::literals;
+  using ::skytest::eq;
+  using ::skytest::expect;
+
+  "falsy"_test = [&] { return expect(eq(0, argc)); };
+}
+
+```
+
+will print
+
+```console:example/minimal_fail.log
+test `falsy`...[FAIL] example/minimal_fail.cpp:9
+(0 == 1)
+
+0 tests passed | 1 test failed
+
+```
+
+[^1]: The default printer uses `std::cout` and `skytest::aborts` calls `fork`.

WORKSPACE.bazel

@@ -150,3 +150,57 @@ exports_files(glob(["**/*"]))
     strip_prefix = "lcov-1.16",
     url = "https://github.com/linux-test-project/lcov/releases/download/v1.16/lcov-1.16.tar.gz",
 )
+
+http_archive(
+    name = "rules_python",
+    sha256 = "e85ae30de33625a63eca7fc40a94fea845e641888e52f32b6beea91e8b1b2793",
+    strip_prefix = "rules_python-0.27.1",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/0.27.1/rules_python-0.27.1.tar.gz",
+)
+
+load("@rules_python//python:repositories.bzl", "py_repositories", "python_register_toolchains")
+
+py_repositories()
+
+python_register_toolchains(
+    name = "python3_11",
+    python_version = "3.11",
+)
+
+load("@python3_11//:defs.bzl", "interpreter")
+load("@rules_python//python:pip.bzl", "pip_parse")
+
+pip_parse(
+    name = "pip",
+    python_interpreter_target = interpreter,
+    requirements_lock = "//tools:requirements.lock",
+)
+
+load("@pip//:requirements.bzl", "install_deps")
+
+install_deps()
+
+MARKDOWN_EMBED_CODE_COMMIT = "8b81fe2e5585c5e1d14772d8e712ecb7a69c74c8"
+
+http_archive(
+    name = "markdown-embed-code",
+    build_file_content = """
+load("@rules_python//python:defs.bzl", "py_library")
+load("@pip//:requirements.bzl", "requirement")
+
+py_library(
+    name = "markdown-embed-code",
+    srcs = ["markdown_embed_code/__init__.py"],
+    imports = ["."],
+    deps = [requirement("marko")],
+    visibility = ["//visibility:public"],
+)
+""",
+    sha256 = "a7ebe1beb55e24e0f6a7700f287da561b459055fc1c70729291c14ae8118fd1d",
+    strip_prefix = "markdown-embed-code-{commit}".format(
+        commit = MARKDOWN_EMBED_CODE_COMMIT,
+    ),
+    url = "https://github.com/tokusumi/markdown-embed-code/archive/{commit}.tar.gz".format(
+        commit = MARKDOWN_EMBED_CODE_COMMIT,
+    ),
+)

scripts/BUILD.bazel

@@ -0,0 +1,53 @@
+load("@rules_python//python:defs.bzl", "py_binary")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@local_config_info//:defs.bzl", "BAZEL_WORKSPACE_ROOT")
+
+py_binary(
+    name = "markdown-update",
+    srcs = ["markdown-update.py"],
+    visibility = ["//visibility:private"],
+    deps = ["@markdown-embed-code"],
+)
+
+genrule(
+    name = "gen_readme",
+    srcs = ["README.md.tmpl"],
+    outs = ["README.md.generated"],
+    cmd = """
+export BUILD_WORKSPACE_DIRECTORY={workspace_dir}
+$(execpath :markdown-update) $(rootpath :README.md.tmpl)> $@
+""".format(
+        workspace_dir = BAZEL_WORKSPACE_ROOT,
+    ),
+    tags = ["manual"],
+    tools = [":markdown-update"],
+    visibility = ["//visibility:private"],
+)
+
+genrule(
+    name = "readme.update_sh",
+    srcs = ["README.md.tmpl"],
+    outs = ["readme.update.sh"],
+    cmd = """
+set -euo pipefail
+echo "set -euo pipefail" > $@
+echo "" >> $@
+echo "cd \\$$BUILD_WORKSPACE_DIRECTORY" >> $@
+echo "$(execpath :markdown-update) $(rootpath :README.md.tmpl) > README.md" >> $@
+""",
+    tags = ["manual"],
+    tools = [":markdown-update"],
+    visibility = ["//visibility:private"],
+)
+
+sh_binary(
+    name = "readme.update",
+    srcs = [":readme.update.sh"],
+)
+
+diff_test(
+    name = "readme.check",
+    failure_message = "To update, run:\n\nbazel run //scripts:readme.update",
+    file1 = "//:README.md",
+    file2 = "README.md.generated",
+)

scripts/README.md.tmpl

@@ -0,0 +1,28 @@
+# skytest
+
+A non-allocating[^1] C++17+ unit test framework.
+
+## overview
+
+A minimal unit test example
+
+
+```cpp:example/minimal_pass.cpp
+```
+
+when run, will print
+
+```console:example/minimal_pass.log
+```
+
+A test that fails
+
+```cpp:example/minimal_fail.cpp
+```
+
+will print
+
+```console:example/minimal_fail.log
+```
+
+[^1]: The default printer uses `std::cout` and `skytest::aborts` calls `fork`.

scripts/markdown-update.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+ # -*- coding: utf-8 -*-
+
+import argparse
+import os
+from pathlib import Path
+import sys
+
+from markdown_embed_code import get_code_emb
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="embed code into a markdown file.")
+    parser.add_argument("filename")
+    args = parser.parse_args()
+
+    os.chdir(os.environ.get("BUILD_WORKSPACE_DIRECTORY"))
+
+    with open(Path(args.filename), "r") as f:
+        indoc = f.read()
+
+    outdoc = get_code_emb()(indoc)
+
+    sys.stdout.buffer.write(outdoc.encode())
+

tools/BUILD.bazel

@@ -5,6 +5,7 @@ load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
 load("@bazel_skylib//lib:selects.bzl", "selects")
 load("//rules:incompatible.bzl", "incompatible_with_sanitizers")
 load("//rules:lcov.bzl", "lcov")
+load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 
 config_setting_group = selects.config_setting_group
 
@@ -154,3 +155,9 @@ lcov(
     lcov_tool = "genhtml",
     test_targets = lcov_attrs["test_targets"],
 )
+
+compile_pip_requirements(
+    name = "requirements",
+    src = "requirements.in",
+    requirements_txt = "requirements.lock",
+)

tools/requirements.in

@@ -0,0 +1 @@
+marko

tools/requirements.lock

@@ -0,0 +1,10 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    bazel run //tools:requirements.update
+#
+marko==2.0.2 \
+    --hash=sha256:2ebd448ac82636765db49777e735923c799a6d66c75bc4997a922bb4c12e4563 \
+    --hash=sha256:502df6d827139ea7265d819f4fe3664589f4774997eff758dc38bea4f52350e6
+    # via -r tools/requirements.in