feat: expand_template allows inline template content (#533)

Co-authored-by: thesayyn <thesayyn@gmail.com>
This commit is contained in:
Alex Eagle 2023-09-20 18:32:05 -07:00 committed by GitHub
parent b7a3ea534e
commit 882bc95615
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 97 additions and 47 deletions

View File

@ -2,41 +2,6 @@
Public API for expanding variables
<a id="expand_template"></a>
## expand_template
<pre>
expand_template(<a href="#expand_template-name">name</a>, <a href="#expand_template-data">data</a>, <a href="#expand_template-is_executable">is_executable</a>, <a href="#expand_template-out">out</a>, <a href="#expand_template-stamp">stamp</a>, <a href="#expand_template-stamp_substitutions">stamp_substitutions</a>, <a href="#expand_template-substitutions">substitutions</a>, <a href="#expand_template-template">template</a>)
</pre>
Template expansion
This performs a simple search over the template file for the keys in substitutions,
and replaces them with the corresponding values.
Values may also use location templates as documented in
[expand_locations](https://github.com/aspect-build/bazel-lib/blob/main/docs/expand_make_vars.md#expand_locations)
as well as [configuration variables](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#var)
such as `$(BINDIR)`, `$(TARGET_CPU)`, and `$(COMPILATION_MODE)` as documented in
[expand_variables](https://github.com/aspect-build/bazel-lib/blob/main/docs/expand_make_vars.md#expand_variables).
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="expand_template-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="expand_template-data"></a>data | List of targets for additional lookup information. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="expand_template-is_executable"></a>is_executable | Whether to mark the output file as executable. | Boolean | optional | False |
| <a id="expand_template-out"></a>out | Where to write the expanded file. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="expand_template-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br> - <code>stamp = 1</code>: Always stamp the build information into the output, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - <code>stamp = 0</code>: Never stamp, instead replace build information by constant values. This gives good build result caching. - <code>stamp = -1</code>: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | -1 |
| <a id="expand_template-stamp_substitutions"></a>stamp_substitutions | Mapping of strings to substitutions.<br><br> There are overlayed on top of substitutions when stamping is enabled for the target.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template-substitutions"></a>substitutions | Mapping of strings to substitutions.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template-template"></a>template | The template file to expand. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
<a id="expand_locations"></a>
## expand_locations
@ -84,6 +49,26 @@ The deprecated `$(location)` and `$(locations)` expansions returns either the ex
The expanded path or the original path
<a id="expand_template"></a>
## expand_template
<pre>
expand_template(<a href="#expand_template-name">name</a>, <a href="#expand_template-template">template</a>, <a href="#expand_template-kwargs">kwargs</a>)
</pre>
Wrapper macro for `expand_template_rule`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="expand_template-name"></a>name | name of resulting rule | none |
| <a id="expand_template-template"></a>template | the label of a template file, or a list of strings which are lines representing the content of the template. | none |
| <a id="expand_template-kwargs"></a>kwargs | other named parameters to <code>expand_template_rule</code>. | none |
<a id="expand_variables"></a>
## expand_variables

View File

@ -2,12 +2,13 @@
Public API for expand template
<a id="expand_template"></a>
<a id="expand_template_rule"></a>
## expand_template
## expand_template_rule
<pre>
expand_template(<a href="#expand_template-name">name</a>, <a href="#expand_template-data">data</a>, <a href="#expand_template-is_executable">is_executable</a>, <a href="#expand_template-out">out</a>, <a href="#expand_template-stamp">stamp</a>, <a href="#expand_template-stamp_substitutions">stamp_substitutions</a>, <a href="#expand_template-substitutions">substitutions</a>, <a href="#expand_template-template">template</a>)
expand_template_rule(<a href="#expand_template_rule-name">name</a>, <a href="#expand_template_rule-data">data</a>, <a href="#expand_template_rule-is_executable">is_executable</a>, <a href="#expand_template_rule-out">out</a>, <a href="#expand_template_rule-stamp">stamp</a>, <a href="#expand_template_rule-stamp_substitutions">stamp_substitutions</a>, <a href="#expand_template_rule-substitutions">substitutions</a>,
<a href="#expand_template_rule-template">template</a>)
</pre>
Template expansion
@ -27,13 +28,33 @@ such as `$(BINDIR)`, `$(TARGET_CPU)`, and `$(COMPILATION_MODE)` as documented in
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="expand_template-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="expand_template-data"></a>data | List of targets for additional lookup information. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="expand_template-is_executable"></a>is_executable | Whether to mark the output file as executable. | Boolean | optional | False |
| <a id="expand_template-out"></a>out | Where to write the expanded file. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="expand_template-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br> - <code>stamp = 1</code>: Always stamp the build information into the output, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - <code>stamp = 0</code>: Never stamp, instead replace build information by constant values. This gives good build result caching. - <code>stamp = -1</code>: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | -1 |
| <a id="expand_template-stamp_substitutions"></a>stamp_substitutions | Mapping of strings to substitutions.<br><br> There are overlayed on top of substitutions when stamping is enabled for the target.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template-substitutions"></a>substitutions | Mapping of strings to substitutions.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template-template"></a>template | The template file to expand. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="expand_template_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="expand_template_rule-data"></a>data | List of targets for additional lookup information. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="expand_template_rule-is_executable"></a>is_executable | Whether to mark the output file as executable. | Boolean | optional | False |
| <a id="expand_template_rule-out"></a>out | Where to write the expanded file. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="expand_template_rule-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br> - <code>stamp = 1</code>: Always stamp the build information into the output, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - <code>stamp = 0</code>: Never stamp, instead replace build information by constant values. This gives good build result caching. - <code>stamp = -1</code>: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | -1 |
| <a id="expand_template_rule-stamp_substitutions"></a>stamp_substitutions | Mapping of strings to substitutions.<br><br> There are overlayed on top of substitutions when stamping is enabled for the target.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template_rule-substitutions"></a>substitutions | Mapping of strings to substitutions.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="expand_template_rule-template"></a>template | The template file to expand. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
<a id="expand_template"></a>
## expand_template
<pre>
expand_template(<a href="#expand_template-name">name</a>, <a href="#expand_template-template">template</a>, <a href="#expand_template-kwargs">kwargs</a>)
</pre>
Wrapper macro for `expand_template_rule`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="expand_template-name"></a>name | name of resulting rule | none |
| <a id="expand_template-template"></a>template | the label of a template file, or a list of strings which are lines representing the content of the template. | none |
| <a id="expand_template-kwargs"></a>kwargs | other named parameters to <code>expand_template_rule</code>. | none |

View File

@ -78,6 +78,8 @@ bzl_library(
"//lib/private/docs:expand_locations",
"//lib/private/docs:expand_template",
"//lib/private/docs:expand_variables",
"@bazel_skylib//lib:types",
"@bazel_skylib//rules:write_file",
],
)

View File

@ -1,5 +1,31 @@
"Public API for expand template"
load("@bazel_skylib//lib:types.bzl", "types")
load("@bazel_skylib//rules:write_file.bzl", "write_file")
load("//lib/private:expand_template.bzl", _expand_template = "expand_template")
expand_template = _expand_template
expand_template_rule = _expand_template
def expand_template(name, template, **kwargs):
"""Wrapper macro for `expand_template_rule`.
Args:
name: name of resulting rule
template: the label of a template file, or a list of strings
which are lines representing the content of the template.
**kwargs: other named parameters to `expand_template_rule`.
"""
if types.is_list(template):
write_target = "_{}.tmpl".format(name)
write_file(
name = write_target,
out = "{}.txt".format(write_target),
content = template,
)
template = write_target
_expand_template(
name = name,
template = template,
**kwargs
)

View File

@ -58,3 +58,19 @@ assert_contains(
actual = ":a_tmpl_stamp",
expected = "WORKSPACE:",
)
expand_template(
name = "inline_template",
out = "inline.txt",
substitutions = {"line2": "line3"},
template = [
"line1",
"line2",
],
)
assert_contains(
name = "inline_template_test",
actual = ":inline.txt",
expected = "line3",
)