From a04c31248bcc540fd6e033289a9ea326cc709447 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Wed, 19 Apr 2023 06:45:24 -0700 Subject: [PATCH] docs(jq): document empty srcs --- docs/jq.md | 15 ++++++++++++--- docs/stamping.md | 5 +++-- lib/jq.bzl | 15 ++++++++++++--- 3 files changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/jq.md b/docs/jq.md index eb21450e4..b0069656f 100644 --- a/docs/jq.md +++ b/docs/jq.md @@ -27,14 +27,23 @@ Usage examples: ```starlark load("@aspect_bazel_lib//lib:jq.bzl", "jq") -# Remove fields from package.json +# Create a new file bazel-out/.../no_srcs.json +jq( + name = "no_srcs", + srcs = [], + filter = ".name = "Alice"", +) + +# Remove fields from package.json. +# Writes to bazel-out/.../package.json which means you must refer to this as ":no_dev_deps" +# since Bazel doesn't allow a label for the output file that collides with the input file. jq( name = "no_dev_deps", srcs = ["package.json"], filter = "del(.devDependencies)", ) -# Merge bar.json on top of foo.json +# Merge bar.json on top of foo.json, producing foobar.json jq( name = "merged", srcs = ["foo.json", "bar.json"], @@ -108,7 +117,7 @@ jq( | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | Name of the rule | none | -| srcs | List of input files | none | +| srcs | List of input files. May be empty. | none | | filter | Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters). Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, a variable named "STAMP" will be available in the filter.

Be careful to write the filter so that it handles unstamped builds, as in the example above. | None | | filter_file | File containing filter expression (alternative to filter) | None | | args | Additional args to pass to jq | [] | diff --git a/docs/stamping.md b/docs/stamping.md index 08ca86a04..401c497e6 100644 --- a/docs/stamping.md +++ b/docs/stamping.md @@ -60,8 +60,9 @@ load("@aspect_bazel_lib//lib:stamping.bzl", "STAMP_ATTRS", "maybe_stamp") In your rule implementation, call the `maybe_stamp` function. If it returns `None` then this build doesn't have stamping enabled. Otherwise you can use the returned struct to access two files. -The stable_status file contains the keys which were prefixed with `STABLE_`, see above. -The volatile_status file contains the rest of the keys. + +1. The `stable_status` file contains the keys which were prefixed with `STABLE_`, see above. +2. The `volatile_status` file contains the rest of the keys. ```starlark def _rule_impl(ctx): diff --git a/lib/jq.bzl b/lib/jq.bzl index 26bc77ddd..efe5aca4e 100644 --- a/lib/jq.bzl +++ b/lib/jq.bzl @@ -26,14 +26,23 @@ def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, **k ```starlark load("@aspect_bazel_lib//lib:jq.bzl", "jq") - # Remove fields from package.json + # Create a new file bazel-out/.../no_srcs.json + jq( + name = "no_srcs", + srcs = [], + filter = ".name = \"Alice\"", + ) + + # Remove fields from package.json. + # Writes to bazel-out/.../package.json which means you must refer to this as ":no_dev_deps" + # since Bazel doesn't allow a label for the output file that collides with the input file. jq( name = "no_dev_deps", srcs = ["package.json"], filter = "del(.devDependencies)", ) - # Merge bar.json on top of foo.json + # Merge bar.json on top of foo.json, producing foobar.json jq( name = "merged", srcs = ["foo.json", "bar.json"], @@ -102,7 +111,7 @@ def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, **k Args: name: Name of the rule - srcs: List of input files + srcs: List of input files. May be empty. filter: Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters). Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, a variable named "STAMP" will be available in the filter.