Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: updated .aspect/bazelrc/README.md
- Loading branch information
1 parent
fde705b
commit 2cd06c4
Showing
1 changed file
with
70 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,73 @@ | ||
# Aspect Recommended Bazel Options | ||
|
||
The Bazel options found here are the source-of-truth for our recommended set of settings. | ||
The `.bazelrc` files found here are the source-of-truth for our recommended Bazel options. | ||
|
||
They are mirrored on our docsite at https://docs.aspect.build/guides/bazelrc. | ||
|
||
## Using these Bazel options in your project | ||
|
||
To use these files in your project, simply vendor them in and reference them from your `.bazelrc` file. | ||
|
||
For example, | ||
|
||
``` | ||
# Import Aspect recommended Bazel convenience settings for all projects | ||
import %workspace%/.aspect/bazelrc/convenience.bazelrc | ||
# Import Aspect recommended Bazel correctness settings for all projects | ||
import %workspace%/.aspect/bazelrc/correctness.bazelrc | ||
# Import Aspect recommended Bazel performance settings for all projects | ||
import %workspace%/.aspect/bazelrc/performance.bazelrc | ||
# Import Aspect recommended Bazel debug settings for all projects | ||
import %workspace%/.aspect/bazelrc/debug.bazelrc | ||
# Import Aspect recommended Bazel javascript settings for all projects | ||
import %workspace%/.aspect/bazelrc/javascript.bazelrc | ||
# Import Aspect recommended Bazel 6 settings for all projects | ||
import %workspace%/.aspect/bazelrc/bazel6.bazelrc | ||
### YOUR PROJECT SPECIFIC SETTINGS GO HERE ### | ||
# Load any settings & overrides specific to the current user from `.aspect/bazelrc/user.bazelrc`. | ||
# This file should appear in `.gitignore` so that settings are not shared with team members. This | ||
# should be last statement in this config so the user configuration is able to overwrite flags from | ||
# this file. See https://bazel.build/configure/best-practices#bazelrc-file. | ||
try-import %workspace%/.aspect/bazelrc/user.bazelrc | ||
``` | ||
|
||
## Automatic updates | ||
|
||
A convenient way to automatically keep your vendored copy up-to-date is to use | ||
[`write_source_files`](https://docs.aspect.build/rules/aspect_bazel_lib/docs/write_source_files): | ||
|
||
``` | ||
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files") | ||
# Keep up-to-date with Aspect recommended .bazelrc settings. | ||
# See https://github.com/aspect-build/bazel-lib/tree/main/.aspect/bazelrc for the most up to date | ||
# version of Aspect's recommended Bazel options. These are mirrored on our | ||
# [docsite](https://docs.aspect.build/guides/bazelrc) for easier consumption. | ||
write_source_files( | ||
name = "aspect_recommended_bazel_options", | ||
files = { | ||
"bazel5.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:bazel5.bazelrc", | ||
"bazel6.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:bazel6.bazelrc", | ||
"ci.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:ci.bazelrc", | ||
"convenience.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:convenience.bazelrc", | ||
"correctness.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:correctness.bazelrc", | ||
"debug.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:debug.bazelrc", | ||
"javascript.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:javascript.bazelrc", | ||
"performance.bazelrc": "@aspect_bazel_lib//.aspect/bazelrc:performance.bazelrc", | ||
}, | ||
) | ||
``` | ||
|
||
When `@aspect_bazel_lib` is upgraded in your `WORKSPACE.bazel` or your `MODULE.bazel` file, a `diff_test` | ||
stamped out by `write_source_files` will fail if your vendored copy is out-of-date and print the Bazel command | ||
to run to update it. For example, `bazel run //.aspect/bazelrc:aspect_recommended_bazel_options`. | ||
|
||
See the [bazelrc](https://github.com/aspect-build/bazel-examples/blob/main/bazelrc/.aspect/bazelrc/BUILD.bazel) example | ||
in our [bazel-examples](https://github.com/aspect-build/bazel-examples) repository for a working example. |