How coding-pelican/dasae-headers works
Project Type and Purpose
• This is a C-language extension library (header+source), plus a CLI build/test tool (dh-c), documentation in Markdown, example/sample code, and a small runtime (BlocksRuntime) for language extensions (blocks).
• Purpose: Provide modern safety, generics, error handling, testing framework, and a transpiler-like macro layer on top of C17, plus a project generator/build orchestrator and docs.
A. dh-c CLI Tool
– File: dh-c.c
– Responsibilities:
• “dh-c project” scaffolds new user projects
• “dh-c build/run/test” invokes the C compiler, runs tests, and orchestrates includes and macros.
– Interacts with configuration files (.clang-format, BUILD.md, install scripts).
B. Core Library
– Headers: dh/include/dh/**/*.h (API definitions, macros, builtin, core, debug, fs, heap, etc.)
– Sources: dh/src/*.c (implementations of runtime helpers, allocators, sort, time, etc.)
– Organization pattern: modular C code organized by feature (Arr, Err, TEST, heap, time, etc.)
C. External Runtime Library
– BlocksRuntime under dh/libs (provides micro-runtime support for “blocks” syntax).
– Compiled and linked into the core library or user binaries as needed.
D. Examples & Samples
– dh/examples/* and dh/samples/*: demonstration programs (Barnes-Hut N-body, engine samples, Game of Life, etc.)
– Show how users include “dh/*.h” and invoke macros.
– Built and run by dh-c or manually via Makefiles/clang commands.
E. Tests
– dh/tests/unit and dh/tests/integration:
• Unit tests for individual modules
• Integration tests using mockups
– They include “dh/TEST.h”, run by dh-c test or via C test harness.
F. Documentation
– dh/docs: Markdown docs in English/ Korean (home, quick-start, API, tutorials)
– Static content; consumed by docs generator (e.g., MkDocs, Docusaurus) or served as GitHub Pages.
Relationships & Data Flows
• dh-c CLI → reads configuration (install scripts, .clang‐*, BUILD.md) → orchestrates build/test tasks
• dh-c CLI → invokes C preprocessor + compiler (clang/gcc/msvc) on:
1. Core Library Sources (dh/src → object files)
2. Examples/Samples & Tests (dh/examples, dh/samples, dh/tests) linking against core library
• Core Library Headers → are #included by user code (examples/tests/scaffolded projects) → macros expand at compile time
• BlocksRuntime → compiled into core library or linked into executables requiring “blocks” support
• Documentation → authored in Markdown → consumed by doc generator (outside current build pipeline)
Architectural Patterns and Design Principles
• Modular C architecture: each feature is a separate module under dh/include & dh/src
• Header‐only API + optional compiled sources: user can include only headers or link compiled runtime
• Macro‐based transpiler: extensive use of C preprocessor for language extensions (defer, errdefer, union enum, etc.)
• Built-in test runner combined with macros for succinct test definitions
• CLI orchestrator (dh-c) implements the builder pattern for project scaffolding and reproducible builds
Essential Elements to Capture
– Component labels: dh-c CLI, C Compiler/Linker, Core Library (dh/include + dh/src), BlocksRuntime, Examples/Samples, Tests, Documentation.
• Tool → Compiler (build tasks)
• User code ← includes from Library
• Library → Compiled object/static lib
• Tests & Examples → Link against library