Add missing docs and doc links; update bazel.build links (#387)
This commit is contained in:
Alexandre Rostovtsev
GitHub
parent
31ab4c8bd2
commit
d7e9dbb31f
|
|
@ -60,8 +60,14 @@ s = shell.quote(p)
|
|||
|
||||
* [analysis_test](docs/analysis_test_doc.md)
|
||||
* [build_test](docs/build_test_doc.md)
|
||||
* [common_settings](docs/common_settings_doc.md)
|
||||
* [copy_directory](docs/copy_directory_doc.md)
|
||||
* [copy_file](docs/copy_file_doc.md)
|
||||
* [diff_test](docs/diff_test_doc.md)
|
||||
* [expand_template](docs/expand_template_doc.md)
|
||||
* [native_binary and native_test](docs/native_binary_doc.md)
|
||||
* [run_binary](docs/run_binary_doc.md)
|
||||
* [select_file](docs/select_file_doc.md)
|
||||
* [write_file](docs/write_file_doc.md)
|
||||
|
||||
## Writing a new module
|
||||
|
|
|
|||
|
|
@ -77,6 +77,11 @@ stardoc_with_diff_test(
|
|||
out_label = "//docs:selects_doc.md",
|
||||
)
|
||||
|
||||
stardoc_with_diff_test(
|
||||
bzl_library_target = "//rules:select_file",
|
||||
out_label = "//docs:select_file_doc.md",
|
||||
)
|
||||
|
||||
stardoc_with_diff_test(
|
||||
bzl_library_target = "//lib:shell",
|
||||
out_label = "//docs:shell_doc.md",
|
||||
|
|
|
|||
|
|
@ -36,6 +36,6 @@ Typical usage:
|
|||
| :------------- | :------------- | :------------- |
|
||||
| <a id="build_test-name"></a>name | The name of the test rule. | none |
|
||||
| <a id="build_test-targets"></a>targets | A list of targets to ensure build. | none |
|
||||
| <a id="build_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none |
|
||||
| <a id="build_test-kwargs"></a>kwargs | The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. | none |
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ These rules return a BuildSettingInfo with the value of the build setting.
|
|||
For label-typed settings, use the native label_flag and label_setting rules.
|
||||
|
||||
More documentation on how to use build settings at
|
||||
https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings
|
||||
https://bazel.build/extending/config#user-defined-build-settings
|
||||
|
||||
|
||||
<a id="bool_flag"></a>
|
||||
|
|
|
|||
|
|
@ -28,6 +28,6 @@ The test succeeds if the files' contents match.
|
|||
| <a id="diff_test-file1"></a>file1 | Label of the file to compare to <code>file2</code>. | none |
|
||||
| <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none |
|
||||
| <a id="diff_test-failure_message"></a>failure_message | Additional message to log if the files' contents do not match. | <code>None</code> |
|
||||
| <a id="diff_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none |
|
||||
| <a id="diff_test-kwargs"></a>kwargs | The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>. | none |
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ in genrule.tools for example. You can also augment the binary with runfiles.
|
|||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <a id="native_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
|
||||
| <a id="native_binary-data"></a>data | data dependencies. See https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
|
||||
| <a id="native_binary-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
|
||||
| <a id="native_binary-out"></a>out | An output name for the copy of the binary | String | required | |
|
||||
| <a id="native_binary-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ the binary with runfiles.
|
|||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <a id="native_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
|
||||
| <a id="native_test-data"></a>data | data dependencies. See https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
|
||||
| <a id="native_test-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
|
||||
| <a id="native_test-out"></a>out | An output name for the copy of the binary | String | required | |
|
||||
| <a id="native_test-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
|
||||
|
||||
|
|
|
|||
|
|
@ -22,8 +22,8 @@ Runs a binary as a build action.<br/><br/>This rule does not require Bash (unlik
|
|||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <a id="run_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
|
||||
| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | List of strings | optional | [] |
|
||||
| <a id="run_binary-env"></a>env | Environment variables of the action.<br/><br/>Subject to <code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
|
||||
| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://bazel.build/reference/be/make-variables#predefined_label_variables">$(location)</a></code> expansion. | List of strings | optional | [] |
|
||||
| <a id="run_binary-env"></a>env | Environment variables of the action.<br/><br/>Subject to <code><a href="https://bazel.build/reference/be/make-variables#predefined_label_variables">$(location)</a></code> expansion. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
|
||||
| <a id="run_binary-outs"></a>outs | Output files generated by the action.<br/><br/>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | List of labels | required | |
|
||||
| <a id="run_binary-srcs"></a>srcs | Additional inputs of the action.<br/><br/>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
|
||||
| <a id="run_binary-tool"></a>tool | The tool to run in the action.<br/><br/>Must be the label of a *_binary rule, of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,28 @@
|
|||
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
|
||||
|
||||
|
||||
select_file() build rule implementation.
|
||||
|
||||
Selects a single file from the outputs of a target by given relative path.
|
||||
|
||||
|
||||
<a id="select_file"></a>
|
||||
|
||||
## select_file
|
||||
|
||||
<pre>
|
||||
select_file(<a href="#select_file-name">name</a>, <a href="#select_file-srcs">srcs</a>, <a href="#select_file-subpath">subpath</a>)
|
||||
</pre>
|
||||
|
||||
Selects a single file from the outputs of a target by given relative path
|
||||
|
||||
**ATTRIBUTES**
|
||||
|
||||
|
||||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <a id="select_file-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
|
||||
| <a id="select_file-srcs"></a>srcs | The target producing the file among other outputs | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
|
||||
| <a id="select_file-subpath"></a>subpath | Relative path to the file | String | required | |
|
||||
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ def build_test(name, targets, **kwargs):
|
|||
Args:
|
||||
name: The name of the test rule.
|
||||
targets: A list of targets to ensure build.
|
||||
**kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.
|
||||
**kwargs: The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>.
|
||||
"""
|
||||
if len(targets) == 0:
|
||||
fail("targets must be non-empty", "targets")
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ These rules return a BuildSettingInfo with the value of the build setting.
|
|||
For label-typed settings, use the native label_flag and label_setting rules.
|
||||
|
||||
More documentation on how to use build settings at
|
||||
https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings
|
||||
https://bazel.build/extending/config#user-defined-build-settings
|
||||
"""
|
||||
|
||||
BuildSettingInfo = provider(
|
||||
|
|
|
|||
|
|
@ -164,7 +164,7 @@ def diff_test(name, file1, file2, failure_message = None, **kwargs):
|
|||
file1: Label of the file to compare to <code>file2</code>.
|
||||
file2: Label of the file to compare to <code>file1</code>.
|
||||
failure_message: Additional message to log if the files' contents do not match.
|
||||
**kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.
|
||||
**kwargs: The <a href="https://bazel.build/reference/be/common-definitions#common-attributes-tests">common attributes for tests</a>.
|
||||
"""
|
||||
_diff_test(
|
||||
name = name,
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ _ATTRS = {
|
|||
"data": attr.label_list(
|
||||
allow_files = True,
|
||||
doc = "data dependencies. See" +
|
||||
" https://docs.bazel.build/versions/main/be/common-definitions.html#typical.data",
|
||||
" https://bazel.build/reference/be/common-definitions#typical.data",
|
||||
),
|
||||
# "out" is attr.string instead of attr.output, so that it is select()'able.
|
||||
"out": attr.string(mandatory = True, doc = "An output name for the copy of the binary"),
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ run_binary = rule(
|
|||
),
|
||||
"env": attr.string_dict(
|
||||
doc = "Environment variables of the action.<br/><br/>Subject to " +
|
||||
" <code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" +
|
||||
" <code><a href=\"https://bazel.build/reference/be/make-variables#predefined_label_variables\">$(location)</a></code>" +
|
||||
" expansion.",
|
||||
),
|
||||
"srcs": attr.label_list(
|
||||
|
|
@ -91,7 +91,7 @@ run_binary = rule(
|
|||
),
|
||||
"args": attr.string_list(
|
||||
doc = "Command line arguments of the binary.<br/><br/>Subject to" +
|
||||
"<code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" +
|
||||
"<code><a href=\"https://bazel.build/reference/be/make-variables#predefined_label_variables\">$(location)</a></code>" +
|
||||
" expansion.",
|
||||
),
|
||||
},
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@
|
|||
"""
|
||||
select_file() build rule implementation.
|
||||
|
||||
Selects a single file from the outputs of some target by given relative path.
|
||||
Selects a single file from the outputs of a target by given relative path.
|
||||
"""
|
||||
|
||||
def _impl(ctx):
|
||||
|
|
@ -38,8 +38,7 @@ def _impl(ctx):
|
|||
|
||||
select_file = rule(
|
||||
implementation = _impl,
|
||||
doc = "Selects a single file from the outputs of some target \
|
||||
by given relative path",
|
||||
doc = "Selects a single file from the outputs of a target by given relative path",
|
||||
attrs = {
|
||||
"srcs": attr.label(
|
||||
allow_files = True,
|
||||
|
|
|
|||
Loading…
Reference in New Issue