|
1 | | -;; SPDX-License-Identifier: PMPL-1.0-or-later |
2 | | -;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
3 | | -;; META.a2ml — Meta-level information for nimiser |
4 | | - |
5 | | -(meta |
6 | | - (version "0.1.0") |
7 | | - (last-updated "2026-03-21") |
8 | | - |
9 | | - (architecture-decisions |
10 | | - (adr "001-iser-pattern" |
11 | | - (status "accepted") |
12 | | - (context "Need to make Nim's powerful metaprogramming accessible without requiring users to learn Nim") |
13 | | - (decision "Use manifest-driven code generation: user describes library interface in nimiser.toml, tool generates Nim templates/macros/generics that compile to optimised C") |
14 | | - (consequences "Users write zero Nim code; all complexity in nimiser's codegen pipeline")) |
15 | | - |
16 | | - (adr "002-abi-ffi-standard" |
17 | | - (status "accepted") |
18 | | - (context "Need verified interop between Rust CLI, Nim-generated C library, and Zig FFI bridge") |
19 | | - (decision "Idris2 ABI for formal proofs (NimTemplate, NimMacro, CompileTimeAST, CBackend types), Zig FFI for C-ABI bridge (nimiser_* functions)") |
20 | | - (consequences "Compile-time correctness guarantees for the Nim-to-C ABI; zero runtime overhead from proofs")) |
21 | | - |
22 | | - (adr "003-nim-metaprogramming-pipeline" |
23 | | - (status "accepted") |
24 | | - (context "Nim offers three compile-time metaprogramming mechanisms: templates, macros, and generics") |
25 | | - (decision "Generate all three: templates for zero-cost abstractions, macros for AST-level transforms (loop unrolling, pragma injection), generics for monomorphised specialisation") |
26 | | - (consequences "Maximum optimisation through compile-time code specialisation; output C code is as fast as hand-written")) |
27 | | - |
28 | | - (adr "004-nim-c-backend" |
29 | | - (status "accepted") |
30 | | - (context "Nim can compile to C, C++, Objective-C, or JavaScript") |
31 | | - (decision "Primary target is C backend (nim c --app:lib), with C++ and JS as secondary backends selectable via manifest") |
32 | | - (consequences "Generated libraries are portable C with clean headers; no Nim runtime dependency in the output")) |
33 | | - |
34 | | - (adr "005-rsr-template" |
35 | | - (status "accepted") |
36 | | - (context "Need consistent project structure across 29+ -iser repos") |
37 | | - (decision "All repos cloned from rsr-template-repo with full CI/CD and governance") |
38 | | - (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one"))) |
39 | | - |
40 | | - (development-practices |
41 | | - (language "Rust" (purpose "CLI orchestration, manifest parsing, codegen pipeline")) |
42 | | - (language "Nim" (purpose "Generated target — templates, macros, generics compiled to C")) |
43 | | - (language "Idris2" (purpose "ABI formal proofs for Nim type/layout/calling-convention correctness")) |
44 | | - (language "Zig" (purpose "FFI C-ABI bridge between Rust CLI and Nim-generated libraries")) |
45 | | - (build-tool "cargo" (purpose "Rust CLI")) |
46 | | - (build-tool "nim c" (purpose "Nim -> C compilation of generated code")) |
47 | | - (build-tool "zig build" (purpose "Zig FFI layer")) |
48 | | - (ci "GitHub Actions (17 workflows)")) |
49 | | - |
50 | | - (design-rationale |
51 | | - (principle "Nim templates for zero-cost abstractions" |
52 | | - (explanation "Templates expand inline at compile time with no function-call overhead; ideal for buffer management, type adapters, and calling convention wrappers")) |
53 | | - (principle "Nim macros for AST-level optimisation" |
54 | | - (explanation "Macros rewrite the Nim AST before compilation, enabling loop unrolling, dead code elimination, and automatic {.exportc.} pragma injection")) |
55 | | - (principle "Nim generics for type specialisation" |
56 | | - (explanation "Generics are monomorphised at compile time, producing specialised code for each concrete type without runtime dispatch")) |
57 | | - (principle "Formally verified C ABI" |
58 | | - (explanation "Idris2 dependent types prove that generated Nim {.exportc.} structs match C struct layout expectations across platforms")))) |
| 1 | +# SPDX-License-Identifier: PMPL-1.0-or-later |
| 2 | +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
| 3 | +# |
| 4 | +# META.a2ml — Nimiser meta-level information |
| 5 | +[metadata] |
| 6 | +version = "0.1.0" |
| 7 | +last-updated = "2026-03-21" |
| 8 | + |
| 9 | +[project-info] |
| 10 | +license = "PMPL-1.0-or-later" |
| 11 | +author = "Jonathan D.A. Jewell (hyperpolymath)" |
| 12 | + |
| 13 | +[architecture-decisions] |
| 14 | +decisions = [ |
| 15 | + # No ADRs recorded |
| 16 | +] |
| 17 | + |
| 18 | +[development-practices] |
| 19 | +versioning = "SemVer" |
| 20 | +documentation = "AsciiDoc" |
| 21 | +build-tool = "just" |
| 22 | + |
| 23 | +[maintenance-axes] |
| 24 | +scoping-first = true |
| 25 | +axis-1 = "must > intend > like" |
| 26 | +axis-2 = "corrective > adaptive > perfective" |
| 27 | +axis-3 = "systems > compliance > effects" |
0 commit comments