diff --git a/README.md b/README.md index 081d9f5..2ee4f8c 100644 --- a/README.md +++ b/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). diff --git a/execute_tests.sh b/execute_tests.sh new file mode 100755 index 0000000..854c8d8 --- /dev/null +++ b/execute_tests.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# +# Execute all tests + +set -euo pipefail +bazelisk test //... diff --git a/lang/cc/README.md b/lang/cc/README.md new file mode 100644 index 0000000..c23ff49 --- /dev/null +++ b/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. diff --git a/lang/cc/build_error.bzl b/lang/cc/build_error.bzl index f653b1d..04c4c14 100644 --- a/lang/cc/build_error.bzl +++ b/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], diff --git a/matcher/README.md b/matcher/README.md new file mode 100644 index 0000000..c1fe6f8 --- /dev/null +++ b/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 | diff --git a/matcher/matcher.bzl b/matcher/matcher.bzl index aa300c7..19b79f0 100644 --- a/matcher/matcher.bzl +++ b/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")