How buildit-lang/buildit works
Project type and purpose
• BuildIt is a C++ library/framework (not a standalone application) for multi‑stage code generation and rapid DSL development.
• It exposes a header‑only API (in include/) and a compiled implementation (in src/) that works with any standard C++ compiler.
Top‑level architectural components
a. BuildIt Core Library
• API Layer (include/)
– builder/ : public types and functions for dyn_var, static_var, builder_context, annotations, generics
– blocks/ : definitions of AST nodes (block, stmt, expr, var), matchers, visitors, replacers
– util/ : auxiliary components (printer, tracer, var_finder)
• Implementation Layer (src/)
– src/builder/ : actual implementations of builder methods, context support, generics
– src/blocks/ : implementations of block visitors, code generator, loop finders, extract_cuda, var_namer, etc.
– src/util/ : tracer and var_finder implementations
b. External Dependencies
– deps/d2x : optional debugging library that plugs into BuildIt core via util/tracer
– Standard C++ toolchain (g++, GNU make)
c. Build System
– Makefiles and build rules (make/, make/buildit_rules.mk, make/deps.mk, etc.)
– CI workflows under .github/workflows and Travis config
d. Sample DSLs and Tests
– samples/ : dozens of example .cpp files written with dyn_var/static_var APIs
– samples/outputs/ : expected generated code outputs and var name mappings to validate correctness
Relationships and Data Flow
• A user’s .cpp that includes <builder/dyn_var.h> invokes the Builder API
→ Builder constructs a lightweight AST of “blocks” and “stmts”
→ AST passes through block visitors & matchers that perform rewrites (loop_finder, if_switcher, rce, etc.)
→ c_code_generator (in blocks/) emits final target code (C++ loops, CUDA pragmas, etc.)
→ util/printer formats generated code; util/tracer can instrument runtime for debugging (via d2x)
• BuilderContext orchestrates multi‑stage code specialization using static_var, dyn_var and generics
Architectural Patterns and Principles
• Visitor Pattern: src/blocks/block_visitor operates over AST node types
• Builder Pattern: builder::Builder constructs AST incrementally, supports annotations
• Multi‑stage Programming: separation of “definition stage” (dyn_var expressions) vs. “codegen stage” (static code)
• Modular Design: well‑defined modules (builder, blocks, util) each with clear responsibilities
• Extensibility Points: custom matchers/replacers can be plugged into the blocks pipeline
Detail Checklist
• AST (blocks) as a first‑class component with edges to visitors and the code generator