diff --git a/.agents/skills/bazel/SKILL.md b/.agents/skills/bazel/SKILL.md new file mode 100644 index 000000000000..6c40a1ea5ff2 --- /dev/null +++ b/.agents/skills/bazel/SKILL.md @@ -0,0 +1,83 @@ +--- +name: Bazel usage +description: + Instructions for using Bazel or Bazelisk to build, test, and debug in the + Carbon repository. +--- + +# Bazel usage + + + +This skill documents how best to use Bazel when building, testing, or +manipulating the Carbon repository's Bazel in any way. + +## Bazel wrappers + +Carbon uses Bazel for its build system. To ensure consistent versions, the +project uses Bazelisk. + +> [!IMPORTANT] Always use `bazelisk` whenever you want to run Bazel. Never run +> `bazel` directly in the Carbon project. Anything you want to do with `bazel` +> can be done with the `bazelisk` command instead. + +- **Bazelisk**: Try to use `bazelisk` in your existing `$PATH` if available. + - **`run_bazelisk.py`**: If `bazelisk` isn't available, use + `./scripts/run_bazelisk.py` to run bazelisk without it being installed. + +## Essential commands + +### Building + +- **Build all**: `bazelisk build //...` +- **Build toolchain**: `bazelisk build //toolchain/...` +- **Build specific target**: `bazelisk build //toolchain:carbon` + +### Testing + +- **Test all**: `bazelisk test //...:all` +- **Test toolchain**: `bazelisk test //toolchain/...` +- **Test examples**: `bazelisk test //examples/...` + +> [!TIP] Running all of the tests can be slow, so try to narrowly test the +> immediately relevant parts of the project first, and only expand coverage as +> necessary to be confident in the changes. + +> [!TIP] For specialized instructions on testing and developing the Carbon +> toolchain, consult these skills: +> +> - [Toolchain tests](/.agents/skills/toolchain_tests/SKILL.md): For +> authoring, structuring, and running `file_test` tests. +> - [Toolchain development](/.agents/skills/toolchain_development/SKILL.md): +> For architecture, essential commands, and debugging the toolchain. + +### Running binaries built by Bazel + +> [!IMPORTANT] Always manually run binaries built by Bazel using the +> `bazelisk run` command. Never run the binary directly from `bazel-bin/`. + +You can run the Carbon driver or command line directly via Bazel: + +- `bazelisk run //toolchain -- compile --phase=parse toolchain/parse/testdata/basics/empty.carbon` + +## Advanced configurations + +### AddressSanitizer (ASan) + +To enable ASan for local testing: + +- Pass `--config=asan`: `bazelisk test --config=asan //...` + +## Common pitfalls and troubleshooting + +### `bazel clean` + +Changes to packages installed on your system (like changing LLVM versions or +installing `libc++`) may not be noticed by Bazel. + +- Run `bazelisk clean` to force cached state to be rebuilt when environment + changes occur. diff --git a/AGENTS.md b/AGENTS.md index e7eda9ca3d10..383ef396e03b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ assistant, **read this first** to avoid common pitfalls. - [General instructions](#general-instructions) - [Project structure](#project-structure) +- [Bazel usage](#bazel-usage) - [Toolchain development](#toolchain-development) ## General instructions @@ -40,6 +41,12 @@ assistant, **read this first** to avoid common pitfalls. See the "Tool usage" skill for instructions on what tools to use in the carbon-lang project. +## Bazel usage + +> [!IMPORTANT] Always use `bazelisk` instead of `bazel` for all commands in the +> Carbon project. Refer to the +> [Bazel usage skill](/.agents/skills/bazel/SKILL.md) for detailed instructions. + ## Code style See the "Code style" skill for instructions on formatting, style guides, and