Explorar o código

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 hai 2 semanas
pai
achega
327cb2396a
Modificáronse 2 ficheiros con 90 adicións e 0 borrados
  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)
 -   [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