How c3lang/c3c works
Main Components
• Compiler Core – This includes the front-end and back-end stages found in the “src/compiler” directory. Highlight modules such as the lexer, parser, AST construction, semantic analysis (sema_* files), and multiple code generation modules (e.g. LLVM codegen, assembly code generation, C code generation). Also note auxiliary compiler components such as the module system, macro system, and error handling (for “Result”-based error handling and contracts).
• Standard Library – Point out the “lib/std” directory which houses the implementation of the standard library for C3 and covers many subdomains (collections, crypto, io, math, net, etc.).
• Build and Infrastructure Systems – Include directories like “src/build”, “CMakeLists.txt”, “build-with-docker.sh”, “flake.nix”, and “nix/” which pertain to building the compiler and its libraries for various platforms.
• Testing Suite – Emphasize the “test” directory with its unit tests, compiler tests, and regression tests. This demonstrates how the compiler is verified using extensive test cases spread over many categories (e.g., tests for expressions, macros, and language features).
• Dependencies and External Libraries – Mention the “dependencies” folder (for instance, the miniz library) and the “wrapper” directory for C++ interoperability (e.g., LLVM wrappers), which indicate integration with third-party code.
• Documentation and Examples – Include “README.md” and “resources” (examples, grammar, images, etc.) that provide context, usage examples, and visual aids for the language.
Relationships and Data Flow
• Out the compiler pipeline starting from source file input, progressing through lexical analysis (lexer, tokens), followed by syntactic parsing to build an AST, then semantic analysis, and culminating in multiple code generation paths (LLVM backend and/or assembly/C code generation).
– From “src/main.c” and driver code launching the compiler.
– Between “src/compiler/lexer”, “src/compiler/parser”, and subsequent semantic modules.
– From these modules into various code generation components such as “llvm_codegen”, “asm”, and “codegen_asm”.
• Connections between the compiler core and the standard library (lib/std) to indicate that the standard library is not only part of the runtime ecosystem but also integrated into some compile-time reflection and error handling.
Architectural Patterns and Design Principles
• Pipeline Model: The compiler’s structure follows a linear pipeline pattern – starting with lexing, parsing, semantic analysis, and then branching into different code generation techniques.
• Modularization: Clearly identify that the project splits concerns into separate modules (compiler, standard library, tests, build systems). Also, highlight the use of generics and modules in the language itself as inspiration for how the project’s own architecture is organized.
• Integration & Compatibility: Include a note about the deliberate design to stay close to C – which is visible in the build scripts, dependency handling, and the integration points (e.g., C interoperability modules in the “dependencies” and “wrapper” folders).
Relevant Technologies and Tools
• CMake (and related build configurations)
• Docker (via build-with-docker.sh)
• Nix (flake.nix, nix/ directories)
• LLVM and LLD integration (as seen in the “src/compiler/llvm_codegen” modules and the wrapper/)
• Unit testing frameworks and regression tests (via the “test” directory)
• Code style and quality tools (such as .clang-tidy, .editorconfig)