mirror of https://github.com/carbon-language/carbon-lang.git synced 2026-09-24 19:50:14 +01:00

Files

T

Chandler CarruthandRichard Smith b1e9ced0c9 Add a design for rendering diagnostics on a terminal (#7668 )

The diagnostics documentation covers how a diagnostic is produced and
worded, not the form it takes on a terminal. This adds
`toolchain/docs/diagnostics_rendering.md`: what a diagnostic is made
of, its layout, color, character set, and width, and how each degrades
when the terminal can't render it.

A diagnostic is one message plus labels read against the code they
mark, `Primary` or `Info`; a context and a path are set out apart. It
renders as one frame, anchored per file, with no headline: the message
hangs off the range that is wrong, led by the level word on a heavy
mark, with `->` in the margin on the reported lines. Labels read in
the order of their ranges, connectors that cross earlier rows break
around them, and a path draws only for the message's own location.
Ten rows on the shared example, against Clang's six and rustc's eleven.

Nothing a diagnostic says is dropped for width: source is windowed,
words wrap past the level word, connectors slide, and a label that
still can't hang is out-dented. Under sixty columns the compact form
takes over, one located line per part. Color is named per element with
a ramp per level and a light-background palette; ASCII keeps every
distinction with `^`, `.`, and the level word. The `file:line:column:`
header is the road not taken: structure comes from the language
server, and the compact form covers a grep-able line.

Assisted-by: Claude Code

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>

2026-09-11 07:15:40 +00:00

4.2 KiB

Raw Blame History

Toolchain architecture

Goals
High-level architecture
- Design patterns
Adding features
Design docs
Videos
- Talks
  - 2025
- Implementation walkthroughs

Goals

The toolchain represents the production portion of Carbon. At a high level, the toolchain's top priorities are:

Correctness.
Quality of generated code, including performance.
Compilation performance.
Quality of diagnostics for incorrect or questionable code.

TODO: Add an expanded document that details the goals and priorities and link to it here.

High-level architecture

The main components are:

Driver: Provides commands and ties together compilation flow.
Diagnostics: Produces diagnostic output.
Diagnostics rendering: Draws diagnostics on a terminal.
Compilation flow:
1. Source: Load the file into a SourceBuffer.
2. Lex: Transform a SourceBuffer into a Lex::TokenizedBuffer.
3. Parse: Transform a TokenizedBuffer into a Parse::Tree.
4. Check: Transform a Tree to produce SemIR::File.
5. Lower: Transform the SemIR to an LLVM Module.
6. CodeGen: Transform the LLVM Module into an Object File.

Design patterns

A few common design patterns are:

Distinct steps: Each step of processing produces an output structure, avoiding callbacks passing data between structures.
- For example, the parser takes a Lex::TokenizedBuffer as input and produces a Parse::Tree as output.
- Performance: It should yield better locality versus a callback approach.
- Understandability: Each step has a clear input and output, versus callbacks which obscure the flow of data.
Vectorized storage: Data is stored in vectors and flyweights are passed around, avoiding more typical heap allocation with pointers.
- For example, the parse tree is stored as a llvm::SmallVector<Parse::Tree::NodeImpl> indexed by Parse::Node which wraps an int32_t.
- Performance: Vectorization both minimizes memory allocation overhead and enables better read caching because adjacent entries will be cached together.
Iterative processing: We rely on state stacks and iterative loops for parsing, avoiding recursive function calls.
- For example, the parser has a Parse::State enum tracked in state_stack_, and loops in Parse::Tree::Parse.
- Scalability: Complex code must not cause recursion issues. We have experience in Clang seeing stack frame recursion limits being hit in unexpected ways, and non-recursive approaches largely avoid that risk.

See also Idioms for abbreviations and more implementation techniques.

Adding features

We have a walkthrough for adding features.

Design docs

We have design docs.

Videos

Talks

These talks are focused on implementation details of the toolchain, and can be helpful for learning how the toolchain internals work.

2025

How we compile, Google tech talk (video, slides)

Implementation walkthroughs

These are recordings of implementing PRs.

PR #4173: Parsing extern library syntax (video)
PR #4149: Implementing syntactic merge checks (video)

4.2 KiB Raw Blame History