add readme files

README.md

@@ -6,12 +6,38 @@ Bazel implementations to test a build error.
 
 There's a situation where a developer wants to test if particular code doesn't compile. However, when using ordinary testing rules, such as `cc_test`, `bazel test` results in an error if the test code doesn't compile.
 
-`rules_build_error` is the repository to address such an issue. It provides some implementations to test the compilation error for each programming language. When the code written in a particular **does** compile,  `bazel build` should fail.
+`rules_build_error` is the repository to address such a problem. It provides some implementations to test the compilation error for each programming language. When the code written in a particular **does** compile, `bazel build` should fail for the associated target.
 
 ## Usage
 
+### C/C++ usage
+
+```bazel
+load("@rules_build_error//lang/cc:defs.bzl", "cc_build_error")
+load("@rules_build_error//matcher:defs.bzl", "matcher")
+
+cc_build_error(
+    name = "cause_compile_error",
+    src = "cause_compile_error.cpp",
+    deps = [":library_to_successfully_link"], # `:library_to_successfully_link` must provide `CcInfo`, like `cc_library`
+    compile_stderr = matcher.has_substr("static assertion failed"),
+)
+```
+
 ## Language-specific implementations
 
-### C/C++
+The implementations to check the build error in a particular language is available.
+
+### C/C++ implementation
+
+Refer to [its readme](lang/cc/README.md)
 
 ## Matcher
+
+In order to specify how to validate the error message, a struct `matcher` is available. Refer to [its readme](matcher/README.md) for more details.
+
+## Development
+
+### How to test
+
+Execute [`execute_tests.sh`](execute_tests.sh) after installing [`bazelisk`](https://github.com/bazelbuild/bazelisk).

execute_tests.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#
+# Execute all tests
+
+set -euo pipefail
+bazelisk test //...

lang/cc/README.md

@@ -0,0 +1,27 @@
+# C/C++ build error
+
+Defines some implementations to check build error in C/C++.
+
+## `cc_build_error`
+
+`cc_build_error` is a wrapper macro for rules, providing [`CcBuildErrorInfo`](#ccbuilderrorinfo).
+
+In addition to the common rule attributes listed [here](https://bazel.build/reference/be/common-definitions#common-attributes), it can receive the following attributes (regarding the specific matcher, please refer to [its readme](../../matcher/README.md)):
+
+| Attribute                | Description                                                        | Type             | Is this attribute required? | Other constraints                                   |
+| ------------------------ | ------------------------------------------------------------------ | ---------------- | --------------------------- | --------------------------------------------------- |
+| name                     | Name of the target.                                                | str              | Yes                         |                                                     |
+| src                      | C/C++ source file to check build                                   | label            | Yes                         | Must be a single file having an extension for C/C++ |
+| additional_linker_inputs | Pass these files to the linker command                             | list of labels   | No (defaults to `[]`)       |                                                     |
+| copts                    | C/C++ compilation options                                          | list of str      | No (defaults to `[]`)       |                                                     |
+| deps                     | The list of CcInfo libraries to be linked in to the binary target. | list of label    | No (defaults to `[]`)       | Each list element must provide `CcInfo`             |
+| linkopts                 | C/C++ linking options                                              | list of str      | No (defaults to `[]`)       |                                                     |
+| local_defines            | Pre-processor macro definitions                                    | list of str      | No (defaults to `[]`)       |                                                     |
+| compile_stderr           | Matcher for the stderr message while compiling                     | specific matcher | No (defaults to no-op)      |                                                     |
+| compile_stdout           | Matcher for the stdout message while compiling                     | specific matcher | No (defaults to no-op)      |                                                     |
+| link_stderr              | Matcher for the stderr message while compiling                     | specific matcher | No (defaults to no-op)      |                                                     |
+| link_stdout              | Matcher for the stdout message while compiling                     | specific matcher | No (defaults to no-op)      |                                                     |
+
+## `CcBuildErrorInfo`
+
+`CcBuildErrorInfo` is a provider describing the build error in C/C++. See its definition in [its bzl file](./build_error.bzl) for its details.

lang/cc/build_error.bzl

@@ -335,6 +335,7 @@ _try_build = rule(
         "additional_linker_inputs": attr.label_list(
             doc = "Pass these files to the linker command",
             allow_empty = True,
+            allow_files = True,
             mandatory = False,
         ),
         "copts": attr.string_list(
@@ -343,7 +344,7 @@ _try_build = rule(
             mandatory = False,
         ),
         "deps": attr.label_list(
-            doc = "The list of CcInfo libraries to be linked in to the binary target.",
+            doc = "The list of CcInfo libraries to be linked in to the target",
             allow_empty = True,
             mandatory = False,
             providers = [CcInfo],

matcher/README.md

@@ -0,0 +1,13 @@
+# Matcher
+
+Defines a struct `matcher`.
+
+`matcher` has some member functions each of which receives a pattern string as a positional string argument, and which returns its specific matcher. Each specific matcher can be used to specify the way of validating the build error message (stderr or stdout).
+
+The member functions of `matcher` are as follows
+
+| Member                  | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| contains_basic_regex    | Check if the message contains the basic regular expression pattern    |
+| contains_extended_regex | Check if the message contains the extended regular expression pattern |
+| has_substr              | Check if the message has the sub-string                               |

matcher/matcher.bzl

@@ -8,16 +8,6 @@ and return a struct with the following members:
                         $1: Pattern string
                         $2: Text file path to investigate
                     and exits with an error if the pattern doesn't match the content of the test file.
-
-The matcher function is registered to the global struct `matcher`. The user uses it such as
-```bazel
-
-cc_build_error(
-    name = "compile_error",
-    src = "cpp_compile_error.cpp",
-    compile_stderr = matcher.has_substr("error message pattern"),
-)
-```
 """
 
 visibility("private")