From caa88a9b36d9e1dfae40ecb31aee05bc2891fa17 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 27 Oct 2026 14:07:24 +0000 Subject: docs(preprocessor): document switches and library regions Add manuals and aliases for all five PP directives, replace the retired #LIB page, and update compiler and shared-editor architecture notes. Co-Authored-By: Claude Opus 5.5 --- AGENTS/ARCH/DRIVER.md | 3 ++- AGENTS/ARCH/LAYOUT.md | 1 + AGENTS/ARCH/OVERVIEW.md | 10 +++++----- 3 files changed, 8 insertions(+), 6 deletions(-) (limited to 'AGENTS/ARCH') diff --git a/AGENTS/ARCH/DRIVER.md b/AGENTS/ARCH/DRIVER.md index ef739b2..974c0dc 100644 --- a/AGENTS/ARCH/DRIVER.md +++ b/AGENTS/ARCH/DRIVER.md @@ -6,7 +6,8 @@ style is in [CONVENTIONS/SYMBOLS_AND_ERRORS.md](../CONVENTIONS/SYMBOLS_AND_ERROR - One or more source files, with optional `-S`, `-o path`, `-r`, `-no-std` and `-fdiagnostics-color[=auto|always|never]` / `-fno-diagnostics-color`; options may appear among inputs. - Each stream is parsed independently. INCLUDE paths are relative to the including file, + Each input is preprocessed independently before parsing. PP_* switches are file-local; + masked source retains line numbers, and SourceUnit owns the per-line __LIB map. INCLUDE paths are relative to the including file, matched against command-line inputs with fs::equivalent. The driver rejects repeated inputs and computes transitive symbol visibility; cycles do not copy statements. CodeGen records owners for signatures, types and exported constants/globals and filters diff --git a/AGENTS/ARCH/LAYOUT.md b/AGENTS/ARCH/LAYOUT.md index c2cfee2..44a8f51 100644 --- a/AGENTS/ARCH/LAYOUT.md +++ b/AGENTS/ARCH/LAYOUT.md @@ -3,6 +3,7 @@ | Path | Contents | |---|---| | `include/cps/` | All headers, included as `"cps/Foo.h"` | +| `lib/Lexer/Preprocessor.cc`, `include/cps/Preprocessor.h` | File-local switch preprocessing, conditional masking and original-line library metadata | | `lib/Lexer/Lexer.cc` | Token scanning and payload-preserving lookahead; `gettok()` consumes and `peekToken`/`peekLine` inspect buffered tokens | | `lib/Parser/Parser.cc` | Entry point, statement dispatch, assignment parsing and error recovery | | `lib/Parser/ParserExpression.cc`, `ParserControlFlow.cc` | Expressions/designators and control-flow statement parsing (including ordered CASE branches) | diff --git a/AGENTS/ARCH/OVERVIEW.md b/AGENTS/ARCH/OVERVIEW.md index 820c5bb..ee3fc12 100644 --- a/AGENTS/ARCH/OVERVIEW.md +++ b/AGENTS/ARCH/OVERVIEW.md @@ -1,14 +1,14 @@ # Overview and value representation -`cpsc` compiles CIE A-Level 9618 pseudocode to native executables or LLVM IR. Classic three-stage -Kaleidoscope-style design, C++17, built with LLVM 23 and Clang 23. CMake rejects +`cpsc` compiles CIE A-Level 9618 pseudocode to native executables or LLVM IR. A line preprocessor feeds a +Kaleidoscope-style lexer/parser/codegen pipeline, C++17, built with LLVM 23 and Clang 23. CMake rejects other major versions and non-Clang compilers. Execution is selected at build time: external lli, an embedded static LLVM engine, or disabled. ``` -files ──> Lexer ──> Parser ──> vector> ──> CodeGen ──> LLVM IR ──> NativeCompiler (object emission + embedded LLD) - (istream) (recursive (flat program list; (one llvm::Module "cps_module", - descent) FunctionDefAST mixed in) entry code inside i32 main()) +files -> Preprocessor -> Lexer -> Parser -> AST statements -> CodeGen -> LLVM IR -> NativeCompiler + (per-file (istream) (recursive descent) (one module) (object + embedded LLD) + switches and source-line library metadata) ``` Fixed value representation (ABI — much code infers types backwards from these): -- cgit v1.3.1-4-g156e