Skip to content

Commit ddc682c

Browse files
committed
docs: the README says only what is true about modules, and drops the moving numbers
Four corrections asked for, plus the module paragraph rewritten: * no "on this machine" — the closure is described as a typical `import std;` program (384 files, 4.85 MB rendering), not as a fact about the reader's disk; * the fifth differentiator (hover reconstruction) is gone; it is a property of one handler, not of the design; * "2,000+ tests" instead of an exact count that moves with every commit (the number was 2,545 when written); * the module point now states what the **language** defines — partition semantics, `export import` re-export, the implementation-provided `std` module — and what it does not: which file holds a unit, and the compiled format. So `import std;` reads the implementation's own module source (libstdc++'s `bits/std.cc`, MSVC's `modules/std.ixx`, both declaring `export module std;`), and a project's unit is identified by **reading it** and rejecting a file that does not declare the module it was a candidate for. The conventions are a search order, not an assumption — which is the design `sema::modules` already documents. Also corrected: the comparison table's Modules row said "MSVC's headers"; the standard module is `modules/std.ixx`, and "modules cooked" (internal jargon) is now "resolved from their interface units".
1 parent 3f7165b commit ddc682c

1 file changed

Lines changed: 15 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,38 +16,36 @@ layer and the LSP server are all in this repository. **No clangd, no libclang, n
1616
| | clangd | cpp_ls |
1717
| --- | --- | --- |
1818
| Project model | a compilation database, or heuristics | nothing, or `.cppls.toml`, or a compilation database |
19-
| Unit of work | a file with flags | **the program**: includes inlined, `#if` resolved, macros expanded, modules cooked |
20-
| Modules | needs BMIs produced by the build | reads the interface's **source** (`import std;` → GCC's `bits/std.cc`, MSVC's headers); partitions resolved by naming convention |
19+
| Unit of work | a file with flags | **the program**: includes inlined, `#if` resolved, macros expanded, modules resolved from their interface units |
20+
| Modules | needs BMIs produced by the build | reads the interface's **source** (`import std;` → libstdc++'s `bits/std.cc`, MSVC's `modules/std.ixx`); a unit is identified by the `export module` it declares |
2121
| Answers in | a file that compiles | a file being edited — half-typed lines included |
2222
| Diagnostics | Clang's | its own 26 checks, measured at **zero false positives** on libstdc++'s own sources |
2323

2424
## What makes it different
2525

2626
**1. The program is the unit of work, not the file.** A C++ file does not mean what its characters say until a
2727
preprocessor has run, so one runs: `#include`s are inlined, the `#if` branch actually in force is taken, macros are
28-
expanded, and the parser reads the text a compiler would see. The closure of `import std;` on this machine is **384
29-
files** and a **4.85 MB** rendering; every answer after that comes from **one** parse of it, shared by every file that
30-
imports the module.
31-
32-
**2. Modules are cooked from source, partitions included.** `import std;` is answered by resolving the module's
33-
interface unit (GCC's `<include>/bits/std.cc`, MSVC's header tree), not by asking for a BMI the build never produced.
34-
`export module geometry:shapes;` is resolved through the naming conventions projects actually use
35-
(`<module>_<partition>.cppm`, `-`, `/`, `.`), an `export import :part;` re-exports that partition's names to importers,
36-
and an implementation unit (`module geometry;`) sees them all.
28+
expanded, and the parser reads the text a compiler would see. A typical `import std;` program is a **384-file,
29+
4.85 MB** rendering parsed **once**, and every file that imports the module answers from that parse.
30+
31+
**2. Modules follow the standard, and the units are identified by what they *declare*.** The language defines the
32+
semantics — a partition is internal to its module, `export import :part;` re-exports it, an implementation unit
33+
(`module geometry;`) sees its module's names, and `std` is an implementation-provided module — and those are the rules
34+
this server implements; what the language does **not** define is which *file* holds a unit (that mapping belongs to the
35+
build) or the compiled module format. So `import std;` reads the implementation's own module source — libstdc++'s
36+
`bits/std.cc`, MSVC's `modules/std.ixx`, each of which declares `export module std;` — and a project's units are
37+
found by reading each candidate file: a file that does not declare `export module geometry:shapes;` is **rejected**, so
38+
the naming conventions are a search order, not an assumption.
3739

3840
**3. No build system required.** Includes that no compiler ever looked at are found by a bounded fuzzy search under the
3941
project root, so a Visual Studio solution and an unconfigured checkout both work. A compilation database, when present,
4042
is used for exact per-file flags.
4143

42-
**4. Every claim in this repository is measured.** **2,545 tests across 167 suites**, plus probes that run against real
44+
**4. Every claim in this repository is measured.** **2,000+ tests**, plus probes that run against real
4345
headers rather than fixtures. [`docs/buglist.md`](docs/buglist.md) is a record of before/after numbers: a sweep of
4446
libstdc++'s 2,500 headers, MSVC's 166 STL headers, and a construct-by-construct table of compiler extensions
4547
(**GCC 40, Clang 29, MSVC 62**) all run in CI.
4648

47-
**5. Hover is reconstructed, never a text slice.** A hover card is built from the indexed fact — signature, deduced type
48-
(`auto`, `decltype`, structured bindings), doc comment — and a type is answered by its **definition**, not by whichever
49-
forward declaration happens to sit in `<format>`.
50-
5149
## Crates
5250

5351
| Crate | What it is |
@@ -107,7 +105,7 @@ exists. Both are described in [`docs/configuration.md`](docs/configuration.md).
107105
## Working on it
108106

109107
```bash
110-
cargo test --workspace --release # 2,545 tests; the latency ones only measure in --release
108+
cargo test --workspace --release # 2,000+ tests; the latency ones only measure in --release
111109
cargo clippy --workspace --all-targets --all-features -- -D warnings
112110
cargo fmt --all
113111
```

0 commit comments

Comments
 (0)