Răsfoiți Sursa

Add a Bazel skill (#7061)

Hopefully this significantly reduces how often agents try to run `bazel`
directly without repeatedly including that in prompts. Also tried to
generally give useful skills for building, testing, and running things.

Also added a specific admonition to the `AGENTS.md` as there is a chance
that agents don't think they need to look at any skills for "standard"
build system commands like `bazel`, as those are "trivial". It seems
like a small chunk of context to spend to avoid churning with bad build
commands.

Assisted-by: Antigravity with Gemini
Chandler Carruth 2 săptămâni în urmă
părinte
comite
327cb2396a
2 a modificat fișierele cu 90 adăugiri și 0 ștergeri
  1. 83 0
      .agents/skills/bazel/SKILL.md
  2. 7 0
      AGENTS.md

+ 83 - 0
.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
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+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.

+ 7 - 0
AGENTS.md

@@ -14,6 +14,7 @@ assistant, **read this first** to avoid common pitfalls.
 
 
 -   [General instructions](#general-instructions)
 -   [General instructions](#general-instructions)
 -   [Project structure](#project-structure)
 -   [Project structure](#project-structure)
+-   [Bazel usage](#bazel-usage)
 -   [Toolchain development](#toolchain-development)
 -   [Toolchain development](#toolchain-development)
 
 
 ## General instructions
 ## 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
 See the "Tool usage" skill for instructions on what tools to use in the
 carbon-lang project.
 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
 ## Code style
 
 
 See the "Code style" skill for instructions on formatting, style guides, and
 See the "Code style" skill for instructions on formatting, style guides, and