|
|
@@ -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.
|