mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-24 19:40:10 +01:00
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
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user