dimgigov
10e4ec07d6
- New docs/index.md with language selector - docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration, 04-api-reference, 05-user-guide, 06-roadmap - docs/bg/ — same structure in Bulgarian - Root README.md trimmed to quick-start + links to docs/ - Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.) - Added swap!/reset! examples to getting-started guides
108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
|
|
[← Back to Index](index.md)
|
|
|
|
---
|
|
|
|
# Clojure/Nim Architecture
|
|
|
|
## Overview
|
|
|
|
Clojure/Nim is a **compiler**, not an interpreter. It follows the model of ClojureScript: Clojure source is read, macro-expanded, analyzed, and emitted as Nim source code, which then compiles to C and finally to a native binary.
|
|
|
|
## Compilation Pipeline
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ .clj File │
|
|
└──────┬──────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Reader │ ← EDN parser. Produces Clojure data structures.
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Macros │ ← defmacro expansion. Operates on Clojure data.
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Analyzer│ ← Special forms, locals, closure analysis.
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Emitter │ ← Generates Nim AST / source code.
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Nim CC │ ← Nim → C compilation.
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ C CC │ ← C → machine code (GCC/Clang).
|
|
└────┬────┘
|
|
│
|
|
┌────▼────┐
|
|
│ Binary │ ← Single native executable.
|
|
└─────────┘
|
|
```
|
|
|
|
## Key Design Decisions
|
|
|
|
### 1. AOT Compiler
|
|
We compile ahead-of-time, like ClojureScript. This gives us:
|
|
- Fast runtime execution (C speed)
|
|
- Small binary size
|
|
- No interpreter overhead
|
|
|
|
The trade-off is that REPL compilation is slower (each form is compiled individually).
|
|
|
|
### 2. Clojure Macros on Clojure Data
|
|
Macro expansion happens **before** reaching Nim. Nim never sees Clojure macros:
|
|
|
|
```clojure
|
|
(defmacro unless [condition & body]
|
|
`(if (not ~condition)
|
|
(do ~@body)))
|
|
```
|
|
|
|
This macro operates on `CljVal` objects (Clojure lists, symbols), not Nim AST.
|
|
|
|
### 3. Runtime in Nim
|
|
The `lib/cljnim_runtime.nim` module provides:
|
|
- `CljVal` — tagged union representing all Clojure values
|
|
- `cljAdd`, `cljMul`, etc. — polymorphic arithmetic
|
|
- `cljRepr` — string representation
|
|
|
|
### 4. Nim Interop
|
|
Instead of Java interop, we have direct Nim interop:
|
|
|
|
```clojure
|
|
(nim/math/sin x)
|
|
(nim/strutils/toUpper s)
|
|
```
|
|
|
|
Nim modules are auto-imported when called via the `nim/module/fn` pattern.
|
|
|
|
## Module Responsibilities
|
|
|
|
| Module | Role |
|
|
|---|---|
|
|
| `src/reader.nim` | Parses `.clj` text into `CljVal` AST |
|
|
| `src/emitter.nim` | Transforms `CljVal` AST into Nim source |
|
|
| `src/repl.nim` | Human and AI REPL implementation |
|
|
| `src/eval.nim` | Tree-walking interpreter for fast in-memory eval |
|
|
| `src/deps.nim` | Dependency resolution (deps.edn format) |
|
|
| `src/core.nim` | Core runtime functions (AOT compiled) |
|
|
| `src/types.nim` | AST node types (used by reader/emitter) |
|
|
| `src/macros.nim` | Macro expansion engine |
|
|
| `src/runtime.nim` | Additional runtime helpers |
|
|
| `lib/cljnim_runtime.nim` | Core runtime library |
|
|
| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT implementation) |
|
|
| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT implementation) |
|
|
| `lib/cljnim_async.nim` | core.async channels runtime |
|
|
|
|
## Memory Model
|
|
|
|
- Uses Nim's ORC garbage collector
|
|
- `CljVal` is a `ref object` (heap-allocated)
|
|
- Persistent data structures (Vector, Map, Set) use structural sharing via HAMT
|