mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-24 19:30:12 +01:00
Adjust tool usage notes (#6853)
Trying to work on some behaviors: - Using `black` to format Python files (using `pre-commit` makes better use of allow-listed commands) - Writing Python code over 80 columns (adding more style notes) - Running `bazel` (being more emphatic about `bazelisk`, splitting tool usage out to its own skill to try making clear it's not toolchain-specific) Assisted-by: Google Antigravity with Gemini
This commit is contained in:
@@ -21,18 +21,25 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
||||
|
||||
## Formatting
|
||||
|
||||
- **C++**: Always check `clang-format` on C++ files.
|
||||
- **Bazel**: Use `pre-commit run buildifier --files <file.bzl>` to format
|
||||
Bazel files.
|
||||
- **C++**: Use `pre-commit run clang-format --files <file.cpp>` to format C++
|
||||
files.
|
||||
- **Carbon**: The toolchain's `format` command doesn't work well right now.
|
||||
Instead, try to format Carbon code based on other Carbon files and the C++
|
||||
style.
|
||||
- **Markdown**: Use `pre-commit run prettier --files <file.md>` to format
|
||||
markdown files correctly.
|
||||
markdown files.
|
||||
- **Python**: Use `pre-commit run black --files <file.py>` to format Python
|
||||
files.
|
||||
|
||||
## Style Guides
|
||||
|
||||
Carbon's toolchain uses LLVM-style C++ with some specific conventions.
|
||||
|
||||
- **Style Guide**: Follow the
|
||||
- **C++ style**: Follow the
|
||||
[Carbon C++ Project Style Guide](/docs/project/cpp_style_guide.md).
|
||||
- **Markdown style**: Follow the
|
||||
[Google developer documentation style guide](https://developers.google.com/style).
|
||||
- **Python style**: Follow the [PEP 8](https://peps.python.org/pep-0008/)
|
||||
style guide.
|
||||
- Wrap code and comments to 80 columns.
|
||||
- Run `pre-commit run flake8 --files <file.py>` to check Python style.
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: Tool usage
|
||||
description:
|
||||
Instructions for AI assistants on what tools to use in the carbon-lang
|
||||
project.
|
||||
---
|
||||
|
||||
# Tool 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
|
||||
-->
|
||||
|
||||
## Bazelisk and Bazel
|
||||
|
||||
We use `bazelisk` for build and test.
|
||||
|
||||
**IMPORTANT**: AI assistants use `bazelisk` instead of `bazel`.
|
||||
|
||||
## Pre-commit
|
||||
|
||||
Running `pre-commit` is mandatory. To run it on all files:
|
||||
|
||||
```bash
|
||||
pre-commit run -a
|
||||
```
|
||||
|
||||
To validate a specific list of files:
|
||||
|
||||
```bash
|
||||
pre-commit run --files <files>
|
||||
```
|
||||
@@ -41,11 +41,6 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
||||
- **Iteration**: Prefer iterative algorithms over recursive ones to prevent
|
||||
stack exhaustion on complex codebases.
|
||||
|
||||
## Building and testing
|
||||
|
||||
AI assistants should use `bazelisk` instead of `bazel` for build and test
|
||||
commands, because some AI editors won't see `bazel` aliases.
|
||||
|
||||
### Essential commands
|
||||
|
||||
- **Test everything**: `bazelisk test //...`
|
||||
@@ -67,20 +62,6 @@ of expected output.** Use the script:
|
||||
./toolchain/autoupdate_testdata.py toolchain/check/testdata/my_test.carbon
|
||||
```
|
||||
|
||||
### Pre-commit
|
||||
|
||||
Running `pre-commit` is mandatory. To run it on all files:
|
||||
|
||||
```bash
|
||||
pre-commit run -a
|
||||
```
|
||||
|
||||
To validate a specific list of files:
|
||||
|
||||
```bash
|
||||
pre-commit run --files <files>
|
||||
```
|
||||
|
||||
## Debugging and diagnostics
|
||||
|
||||
- **Printing to stderr**: Use `llvm::errs() << "debug info\n";`.
|
||||
|
||||
@@ -35,6 +35,11 @@ assistant, **read this first** to avoid common pitfalls.
|
||||
- **[`toolchain/`](toolchain/)**: The C++ implementation of the compiler
|
||||
(Toolchain).
|
||||
|
||||
## Tool usage
|
||||
|
||||
See the "Tool usage" skill for instructions on what tools to use in the
|
||||
carbon-lang project.
|
||||
|
||||
## Code style
|
||||
|
||||
See the "Code style" skill for instructions on formatting, style guides, and
|
||||
|
||||
Reference in New Issue
Block a user