diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index e3409cf..42d17c3 100644 --- a/.bazelci/presubmit.yml +++ b/.bazelci/presubmit.yml @@ -30,3 +30,7 @@ tasks: test_targets: - "//..." - "//tests:all_versions" + check_docs_match_stardoc: + platform: ubuntu1804 + test_targets: + - "//tests:docs_test" diff --git a/README.md b/README.md index 776ca79..564e988 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ a dependency in other rules via the Bazel toolchain system. Currently, the only implementation of m4 supported by this ruleset is [GNU M4]. +API reference: [docs/rules_m4.md](docs/rules_m4.md) + [m4]: https://en.wikipedia.org/wiki/M4_(computer_language) [Bison]: https://www.gnu.org/software/bison/ [Flex]: https://github.com/westes/flex diff --git a/WORKSPACE b/WORKSPACE index eef9c03..9fb2831 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -21,3 +21,21 @@ http_archive( strip_prefix = "googletest-release-1.12.1", urls = ["https://github.com/google/googletest/archive/release-1.12.1.tar.gz"], ) + +http_archive( + name = "bazel_skylib", + sha256 = "f7be3474d42aae265405a592bb7da8e171919d74c16f082a5457840f06054728", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.2.1/bazel-skylib-1.2.1.tar.gz", + "https://github.com/bazelbuild/bazel-skylib/releases/download/1.2.1/bazel-skylib-1.2.1.tar.gz", + ], +) + +http_archive( + name = "io_bazel_stardoc", + sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz", + ], +) diff --git a/docs/BUILD b/docs/BUILD new file mode 100644 index 0000000..10df6b8 --- /dev/null +++ b/docs/BUILD @@ -0,0 +1,5 @@ +filegroup( + name = "docs", + srcs = glob(["*.md"]), + visibility = ["//:__subpackages__"], +) diff --git a/docs/rules_m4.md b/docs/rules_m4.md new file mode 100644 index 0000000..079805d --- /dev/null +++ b/docs/rules_m4.md @@ -0,0 +1,194 @@ + + +# rules_m4 + +Bazel rules for the m4 macro expander. + + + + +## m4 + +
+m4(name, freeze_state, m4_options, output, reload_state, srcs)
+
+ +Perform macro expansion to produce an output file. + +This rule blocks the of execution shell commands (such as `syscmd`) by default. +To enable expansion of a file containing shell commands, set the `m4_syscmd` +target feature. + +### Example + +```starlark +load("@rules_m4//m4:m4.bzl", "m4") + +m4( + name = "m4_example.txt", + srcs = ["m4_example.in.txt"], +) +``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| freeze_state | Optional output file for GNU M4 frozen state. Must have extension .m4f. | Label | optional | | +| m4_options | Additional options to pass to the m4 command.

These will be added to the command args immediately before the source files. | List of strings | optional | [] | +| output | File to write output to. If unset, defaults to the rule name. | Label | optional | | +| reload_state | Optional input file for GNU M4 frozen state. Must have extension .m4f. | Label | optional | None | +| srcs | List of source files to macro-expand. | List of labels | required | | + + + + +## m4_repository + +
+m4_repository(name, extra_copts, repo_mapping, version)
+
+ + +Repository rule for GNU M4. + +The resulting repository will have a `//bin:m4` executable target. + +### Example + +```starlark +load("@rules_m4//m4:m4.bzl", "m4_repository") + +m4_repository( + name = "m4_v1.4.18", + version = "1.4.18", +) +``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| extra_copts | Additional C compiler options to use when building GNU M4. | List of strings | optional | [] | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | +| version | A supported version of GNU M4. | String | required | | + + + + +## m4_toolchain_repository + +
+m4_toolchain_repository(name, m4_repository, repo_mapping)
+
+ + +Toolchain repository rule for m4 toolchains. + +Toolchain repositories add a layer of indirection so that Bazel can resolve +toolchains without downloading additional dependencies. + +The resulting repository will have the following targets: +- `//bin:m4` (an alias into the underlying [`m4_repository`](#m4_repository)) +- `//:toolchain`, which can be registered with Bazel. + +### Example + +```starlark +load("@rules_m4//m4:m4.bzl", "m4_repository", "m4_toolchain_repository") + +m4_repository( + name = "m4_v1.4.18", + version = "1.4.18", +) + +m4_toolchain_repository( + name = "m4", + m4_repository = "@m4_v1.4.18", +) + +register_toolchains("@m4//:toolchain") +``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| m4_repository | The name of an [m4_repository](#m4_repository). | String | optional | "" | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | + + + + +## M4ToolchainInfo + +
+M4ToolchainInfo(all_files, m4_tool, m4_env)
+
+ +Provider for an m4 toolchain. + +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| all_files | A depset containing all files comprising this m4 toolchain. | +| m4_tool | A FilesToRunProvider for the m4 binary. | +| m4_env | Additional environment variables to set when running m4_tool. | + + + + +## m4_register_toolchains + +
+m4_register_toolchains(version, extra_copts)
+
+ +A helper function for m4 toolchains registration. + +This workspace macro will create a [`m4_repository`](#m4_repository) named +`m4_v{version}` and register it as a Bazel toolchain. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| version | A supported version of GNU M4. | "1.4.18" | +| extra_copts | Additional C compiler options to use when building GNU M4. | [] | + + + + +## m4_toolchain + +
+m4_toolchain(ctx)
+
+ +Returns the current [`M4ToolchainInfo`](#M4ToolchainInfo). + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| ctx | A rule context, where the rule has a toolchain dependency on [M4_TOOLCHAIN_TYPE](#M4_TOOLCHAIN_TYPE). | none | + +**RETURNS** + +An [`M4ToolchainInfo`](#M4ToolchainInfo). + + diff --git a/m4/BUILD b/m4/BUILD index 60f95af..11efba1 100644 --- a/m4/BUILD +++ b/m4/BUILD @@ -1,5 +1,14 @@ load("@rules_m4//m4/internal:toolchain_alias.bzl", "m4_toolchain_alias") +filegroup( + name = "bzl_srcs", + srcs = glob(["*.bzl"]) + [ + "//m4/internal:bzl_srcs", + "//m4/rules:bzl_srcs", + ], + visibility = ["//:__subpackages__"], +) + toolchain_type( name = "toolchain_type", visibility = ["//visibility:public"], diff --git a/m4/internal/BUILD b/m4/internal/BUILD index c60b342..8a46cf3 100644 --- a/m4/internal/BUILD +++ b/m4/internal/BUILD @@ -1,3 +1,12 @@ +filegroup( + name = "bzl_srcs", + srcs = glob([ + "*.bzl", + "gnulib/*.bzl", + ]), + visibility = ["//:__subpackages__"], +) + cc_binary( name = "capture_stdout", srcs = ["capture_stdout.c"], diff --git a/m4/rules/BUILD b/m4/rules/BUILD index e69de29..e1ac657 100644 --- a/m4/rules/BUILD +++ b/m4/rules/BUILD @@ -0,0 +1,5 @@ +filegroup( + name = "bzl_srcs", + srcs = glob(["*.bzl"]), + visibility = ["//:__subpackages__"], +) diff --git a/tests/BUILD b/tests/BUILD index 15e0599..2c86dec 100644 --- a/tests/BUILD +++ b/tests/BUILD @@ -66,3 +66,13 @@ alias( actual = "@rules_m4_testutil//:all_versions", tags = ["manual"], ) + +sh_test( + name = "docs_test", + srcs = ["docs_test.sh"], + data = [ + "//docs", + "//tools/stardoc:stardoc_outputs", + ], + tags = ["manual"], +) diff --git a/tests/docs_test.sh b/tests/docs_test.sh new file mode 100755 index 0000000..8398bd3 --- /dev/null +++ b/tests/docs_test.sh @@ -0,0 +1,22 @@ +#!/bin/sh + +set -eu + +docs="docs" +stardoc_outputs="tools/stardoc" + +rc=0 +for filename in "${stardoc_outputs}/"*.md; do + diff -uN "${docs}/${filename#"${stardoc_outputs}"}" "${filename}" || rc=1 +done +for filename in "${docs}/"*.md; do + if grep -q -- 'Generated with Stardoc' "${filename}"; then + stardoc_out="${stardoc_outputs}/${filename#"${docs}"}" + if [ ! -f "${stardoc_out}" ]; then + diff -uN "${filename}" "${stardoc_out}" + rc=1 + fi + fi +done + +exit $rc diff --git a/tools/stardoc/BUILD b/tools/stardoc/BUILD new file mode 100644 index 0000000..667d1e6 --- /dev/null +++ b/tools/stardoc/BUILD @@ -0,0 +1,20 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") + +bzl_library( + name = "rules_m4_bzl_srcs", + srcs = ["//m4:bzl_srcs"], +) + +stardoc( + name = "rules_m4_md", + out = "rules_m4.md", + input = "rules_m4_md.bzl", + deps = [":rules_m4_bzl_srcs"], +) + +filegroup( + name = "stardoc_outputs", + srcs = [":rules_m4.md"], + visibility = ["//:__subpackages__"], +) diff --git a/tools/stardoc/rules_m4_md.bzl b/tools/stardoc/rules_m4_md.bzl new file mode 100644 index 0000000..086d2ce --- /dev/null +++ b/tools/stardoc/rules_m4_md.bzl @@ -0,0 +1,21 @@ +"""# rules_m4 + +Bazel rules for the m4 macro expander. +""" + +load( + "//m4:m4.bzl", + _M4ToolchainInfo = "M4ToolchainInfo", + _m4 = "m4", + _m4_register_toolchains = "m4_register_toolchains", + _m4_repository = "m4_repository", + _m4_toolchain = "m4_toolchain", + _m4_toolchain_repository = "m4_toolchain_repository", +) + +m4 = _m4 +m4_register_toolchains = _m4_register_toolchains +m4_repository = _m4_repository +m4_toolchain = _m4_toolchain +m4_toolchain_repository = _m4_toolchain_repository +M4ToolchainInfo = _M4ToolchainInfo