Public API for write_source_files
Macros and Functions
write_source_file
Write a file or directory to the source tree.
By default, diff_test
targets are generated that ensure the source tree file or directory to be written to
is up to date and the rule also checks that the source tree file or directory to be written to exists.
To disable the exists check and up-to-date test set diff_test
to False
.
Example usage (generated)
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_file")
write_source_file(
# Name of the runnable target that creates or updates the source tree file or directory.
name = "",
)
name
Name of the runnable target that creates or updates the source tree file or directory.
in_file
File or directory to use as the desired content to write to out_file
.
This is typically a file or directory output of another target. If in_file
is a directory then entire directory contents are copied.
out_file
The file or directory to write to in the source tree. Must be within the same bazel package as the target.
executable
Whether source tree file or files within the source tree directory written should be made executable.
additional_update_targets
List of other write_source_files
or write_source_file
targets to call in the same run.
suggested_update_target
Label of the write_source_files
or write_source_file
target to suggest running when files are out of date.
diff_test
Test that the source tree file or directory exist and is up to date.
kwargs
Other common named parameters such as tags
or visibility
write_source_files
Write one or more files and/or directories to the source tree.
By default, diff_test
targets are generated that ensure the source tree files and/or directories to be written to
are up to date and the rule also checks that all source tree files and/or directories to be written to exist.
To disable the exists check and up-to-date tests set diff_test
to False
.
Usage:
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_foobar",
files = {
"foobar.json": "//some/generated:file",
},
)
To update the source file, run:
bazel run //:write_foobar
The generated diff_test
will fail if the file is out of date and print out instructions on
how to update it.
If the file does not exist, Bazel will fail at analysis time and print out instructions on how to create it.
You can declare a tree of generated source file targets:
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_all",
additional_update_targets = [
# Other write_source_files targets to run when this target is run
"//a/b/c:write_foo",
"//a/b:write_bar",
]
)
And update them with a single run:
bazel run //:write_all
When a file is out of date, you can leave a suggestion to run a target further up in the tree by specifying suggested_update_target
.
For example,
write_source_files(
name = "write_foo",
files = {
"foo.json": ":generated-foo",
},
suggested_update_target = "//:write_all"
)
A test failure from foo.json
being out of date will yield the following message:
//a/b:c:foo.json is out of date. To update this and other generated files, run:
bazel run //:write_all
To update *only* this file, run:
bazel run //a/b/c:write_foo
If you have many write_source_files
targets that you want to update as a group, we recommend wrapping
write_source_files
in a macro that defaults suggested_update_target
to the umbrella update target.
NOTE: If you run formatters or linters on your codebase, it is advised that you exclude/ignore the outputs of this rule from those formatters/linters so as to avoid causing collisions and failing tests.
name
Name of the runnable target that creates or updates the source tree files and/or directories.
files
A dict where the keys are files or directories in the source tree to write to and the values are labels pointing to the desired content, typically file or directory outputs of other targets.
Source tree files and directories must be within the same bazel package as the target.
executable
Whether source tree files written should be made executable.
This applies to all source tree files written by this target. This attribute is not propagated to additional_update_targets
.
To set different executable permissions on different source tree files use multiple write_source_files
targets.
additional_update_targets
List of other write_source_files
or write_source_file
targets to call in the same run.
suggested_update_target
Label of the write_source_files
or write_source_file
target to suggest running when files are out of date.
diff_test
Test that the source tree files and/or directories exist and are up to date.
kwargs
Other common named parameters such as tags
or visibility