baraba/bara-lang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: highlight unique advantages — standalone, HAMT, multi-target

Browse Source 
Update README and architecture docs to emphasize:
- Complete independence from Java ecosystem (JVM, GraalVM, Closure)
- Native HAMT persistent data structures built from scratch in Nim
- Multi-target compilation (native, shared lib, WASM, JS)
- AI-native tooling and concurrency without JVM threads

Updates both English and Bulgarian documentation.
This commit is contained in:
dimgigov
2026-05-08 23:59:24 +03:00
parent 23252826a0
commit 4739e2c151
5 changed files with 194 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+68 -2
View File
@@ -1,6 +1,7 @@
# Clojure/Nim # Clojure/Nim
> A Clojure dialect that compiles to Nim → C → native binaries. > A Clojure dialect that compiles to Nim → C → native binaries.
> **The only standalone Clojure implementation completely free from the Java ecosystem.**
[![Tests](https://img.shields.io/badge/tests-276%2B-green)]() [![Nim](https://img.shields.io/badge/nim-%3E%3D2.0-blue)]() [![License](https://img.shields.io/badge/license-MIT-yellow)]() [![Tests](https://img.shields.io/badge/tests-276%2B-green)]() [![Nim](https://img.shields.io/badge/nim-%3E%3D2.0-blue)]() [![License](https://img.shields.io/badge/license-MIT-yellow)]()
@@ -23,12 +24,72 @@ make check
Clojure/Nim is an **AI-first** Clojure implementation targeting the Nim ecosystem. It compiles Clojure source directly to Nim, then to C, and finally to a native binary. Clojure/Nim is an **AI-first** Clojure implementation targeting the Nim ecosystem. It compiles Clojure source directly to Nim, then to C, and finally to a native binary.
Unlike every other Clojure dialect, this project has **zero dependency on the Java ecosystem**:
| Dialect | JVM? | Java Ecosystem Dependency |
|---------|------|---------------------------|
| Clojure (JVM) | ✅ Required | Full — runs on JVM, uses Java stdlib |
| ClojureScript | ❌ | Heavy — Google Closure Compiler, JS ecosystem |
| Babashka | ❌ | Medium — GraalVM native-image, still JVM-based |
| **Clojure/Nim** | ❌ | **None — completely standalone** |
### Why? ### Why?
- **Native Performance** — No JVM warmup, no GC pauses - **Native Performance** — No JVM warmup, no GC pauses, C-speed execution
- **Tiny Binaries** — Single-file executables, often under 1MB - **Tiny Binaries** — Single-file executables, often under 1MB
- **Nim Ecosystem** — Direct access to Nim and C libraries via FFI - **Nim Ecosystem** — Direct access to Nim and C libraries via FFI
- **AI-Native** — JSON REPL, batch evaluation, AI-assisted error messages and code generation - **AI-Native** — JSON REPL, batch evaluation, AI-assisted error messages and code generation
- **True Independence** — No JVM, no GraalVM, no Java stdlib, no Google Closure
## What Makes This Unique?
### 1. Completely Independent from Java
This is the **only** Clojure dialect that does not depend on any part of the Java ecosystem — not the JVM, not GraalVM, not the Java standard library, and not Google Closure Compiler. The entire toolchain is self-contained: Clojure source → Nim source → C source → native binary.
### 2. Native HAMT Persistent Data Structures
Built from scratch in Nim:
- **Persistent Vector** — Hash Array Mapped Trie with 32-way branching and structural sharing
- **Persistent Map** — HAMT-based immutable hash map, O(log₃₂ n) operations
- **Persistent Set** — Backed by HAMT map
- **Transients** — Batch mutations with `conj!`, `assoc!`, `persistent!`
No Java `PersistentVector.java` or `IPersistentMap` interfaces — our own implementation optimized for Nim's memory model and ORC garbage collector.
### 3. Multiple Compilation Targets from One Codebase
The same Clojure code compiles to:
| Target | Status | Use Case |
|--------|--------|----------|
| **Native binary** | ✅ Ready | CLI tools, system programming, servers |
| **Native shared library** (.so/.dll/.dylib) | ✅ Ready | Embed Clojure in Python/Rust/Go/C via FFI |
| **WASM** | ✅ Ready | Browser, serverless, edge computing |
| **JavaScript** | ✅ Ready | Frontend, Node.js without 50MB JVM |
### 4. AOT Compiler — Not an Interpreter
Full ahead-of-time compilation like ClojureScript, but without the JavaScript/Google Closure dependency:
- Fast runtime execution at C speed
- Small binary sizes with no interpreter overhead
- REPL uses a hybrid model: tree-walking interpreter for fast feedback (<1ms eval), AOT compilation for production builds
### 5. Nim/C Interop Instead of Java Interop
Direct FFI to the Nim and C ecosystem:
```clojure
(nim/math/sin x)
(nim/strutils/toUpper s)
```
Nim modules are auto-imported. No JNI, no JVM bridging, no Java interop overhead.
### 6. AI-Native Tooling Built-In
- **AI-assisted errors** — DeepSeek/MiMo explain compiler errors
- **AI code generation** — `(ai/generate "quicksort")` in REPL
- **AI optimization hints** — `(ai/optimize code)` suggests algorithm improvements
- **AI debugging** — `(ai/debug expr)` analyzes runtime behavior
- **JSON REPL protocol** — Structured I/O designed for AI agents and IDE integration
### 7. Concurrency Without the JVM
- **Atoms** — Compare-and-swap semantics
- **Agents** — Async state updates with `send`/`await`
- **core.async channels** — `chan`, `>!`, `<!`, `go` macros — CSP-style concurrency without JVM threads
## Key Features ## Key Features
@@ -37,12 +98,17 @@ Clojure/Nim is an **AI-first** Clojure implementation targeting the Nim ecosyste
| Compiler (Clojure → Nim → C → native) | ✅ | | Compiler (Clojure → Nim → C → native) | ✅ |
| REPL with JSON protocol | ✅ | | REPL with JSON protocol | ✅ |
| Macro system (`defmacro`, `syntax-quote`, `->`, `->>`) | ✅ | | Macro system (`defmacro`, `syntax-quote`, `->`, `->>`) | ✅ |
| Persistent data structures (HAMT vector/map) | ✅ | | Persistent data structures (HAMT vector/map/set) | ✅ |
| Transients for batch mutations | ✅ |
| Atoms, Agents, Channels | ✅ | | Atoms, Agents, Channels | ✅ |
| `loop`/`recur` | ✅ | | `loop`/`recur` | ✅ |
| `try`/`catch`/`finally` | ✅ | | `try`/`catch`/`finally` | ✅ |
| Namespace system (`ns`, `:require`) | ✅ |
| Dependency resolution (deps.edn, Git deps) | ✅ |
| Nim/C FFI interop | ✅ |
| AI integration (DeepSeek, OpenAI, MiMo) | ✅ | | AI integration (DeepSeek, OpenAI, MiMo) | ✅ |
| Cross-compilation targets (JS, WASM, shared libs) | ✅ | | Cross-compilation targets (JS, WASM, shared libs) | ✅ |
| Self-hosted REPL with tree-walking interpreter | ✅ |
| 276+ tests | ✅ | | 276+ tests | ✅ |
## Example ## Example
docs/bg/02-architecture.md
+34
View File
@@ -45,6 +45,40 @@ Clojure/Nim е **компилатор**, не интерпретатор. Сле
└─────────┘ └─────────┘
``` ```
## Уникални Предимства
### Независимост от Java Екосистемата
Clojure/Nim е **единственият** Clojure диалект с абсолютно никаква зависимост от Java екосистемата:
| Диалект | JVM | GraalVM | Google Closure | Java stdlib |
|---------|-----|---------|----------------|-------------|
| Clojure (JVM) | ✅ | ❌ | ❌ | ✅ |
| ClojureScript | ❌ | ❌ | ✅ | ❌ |
| Babashka | ❌ | ✅ | ❌ | Частично |
| **Clojure/Nim** | ❌ | ❌ | ❌ | ❌ |
Това означава:
- **Без JVM warmup** — бинарните файлове стартират мигновенно
- **Без GraalVM сложност** — без native-image конфигурация
- **Без нужда от Java инсталация** — самият компилатор е единичен бинарен файл
- **Истинско standalone разгръщане** — един файл, нула runtime зависимости
### Native HAMT Имплементация
Нашите persistent структури от данни са изградени от нулата в Nim, оптимизирани за Nim's ORC garbage collector:
- **32-way branching** като Clojure's `PersistentVector`, но без Java object overhead
- **Структурно споделяне** през copy-on-write HAMT възли
- **O(log₃₂ n)** за `assoc`/`dissoc`/`nth` — същата асимптотична сложност като JVM Clojure
- **Nim ref обекти** вместо Java интерфейси — по-просто разположение в паметта, по-добра кеш локалност
### Мулти-таргет Компилация
Един и същ Clojure изходен код се компилира до четири различни таргета от един codebase:
1. **Native бинарен файл** — `nim c` → C → машинен код
2. **Shared library** — `nim c --app:lib` → `.so` / `.dll` / `.dylib`
3. **WASM** — `nim c -d:emscripten` → browser-native WebAssembly
4. **JavaScript** — `nim js` → браузър/Node.js
Никоя друга Clojure имплементация не предлага толкова широк спектър от таргети без външни инструменти.
## Ключови Дизайн Решения ## Ключови Дизайн Решения
### 1. AOT Компилатор ### 1. AOT Компилатор
docs/bg/index.md
+28 -26
View File
@@ -1,36 +1,38 @@
# Clojure/Nim Документация
[← Към индекса](index.md) > Clojure диалект, който се компилира до Nim → C → native бинарни файлове.
> **Единствената самостоятелна Clojure имплементация, напълно независима от Java екосистемата.**
--- ## Избор на език / Choose Language
# Clojure/Nim Документация (Български) | 🇧🇬 Български | 🇬🇧 English |
|-------------|------------|
| [Българска Документация](bg/index.md) | [English Documentation](en/index.md) |
> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл. ## Бързи връзки
## Съдържание - **GitHub/GitLab:** [lisp-nim](https://gitlab.com/balvatar/lisp-nim)
- **Build:** `make build && make check`
- **Тестове:** 276+ теста в 8 тестови пакета
- **AI Интеграция:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
| # | Документ | Описание | ## Защо Clojure/Nim?
|---|----------|----------|
| 01 | [Първи стъпки](01-getting-started.md) | Инсталация, компилация, CLI команди, бързи примери |
| 02 | [Архитектура](02-architecture.md) | Компилационен pipeline, дизайн решения, вътрешна структура |
| 03 | [AI Интеграция](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — помощ при грешки, генериране на код, оптимизация, дебъг |
| 04 | [API Справочник](04-api-reference.md) | JSON REPL протокол, операции, tool-call формат |
| 05 | [Ръководство](05-user-guide.md) | Макроси, threading, interop, напреднали шаблони |
| 06 | [Пътна карта](06-roadmap.md) | Завършени фази, бъдещи планове, цели за перформанс |
## Бърз старт За разлика от всеки друг Clojure диалект, Clojure/Nim има **нула зависимост от Java екосистемата** — нито JVM, нито GraalVM, нито Google Closure Compiler, нито Java стандартна библиотека.
```bash | Диалект | Зависимост от Java екосистемата |
git clone https://gitlab.com/balvatar/lisp-nim.git |---------|--------------------------------|
cd lisp-nim | Clojure (JVM) | Пълна — работи върху JVM |
make build | ClojureScript | Голяма — Google Closure Compiler |
make check # компилация + тестове + примери | Babashka | Средна — GraalVM native-image |
./cljnim repl # човешки REPL | **Clojure/Nim** | **Никаква — напълно самостоятелен** |
```
## Статистика ### Уникални предимства
- **Тестове:** 276+ в 8 suite-а 1. **Native HAMT Persistent структури от данни** — Изградени от нулата в Nim (Persistent Vector, Map, Set със структурно споделяне)
- **Компилатор:** Nim → C → нативен код 2. **Множество таргети** — Native бинарен файл, shared library (.so/.dll), WASM и JavaScript от един codebase
- **Target-и:** Linux, macOS, Windows, JS, WASM, C shared libraries 3. **AOT Компилатор** — Clojure → Nim → C → native, работи със скоростта на C
- **AI Поддръжка:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo 4. **Nim/C Interop** — Директен FFI без overhead от JVM bridging
5. **AI-Native Tooling** — Вградена AI интеграция за генериране на код, оптимизация и дебъгване
6. **Конкурентност без JVM** — Atoms, Agents и core.async channels без Java нишки
7. **Миниатюрни бинарни файлове** — Единични изпълними файлове под 1MB без runtime зависимости
docs/en/02-architecture.md
+34
View File
@@ -45,6 +45,40 @@ Clojure/Nim is a **compiler**, not an interpreter. It follows the model of Cloju
└─────────┘ └─────────┘
``` ```
## Unique Advantages
### Independence from the Java Ecosystem
Clojure/Nim is the **only** Clojure dialect with absolutely no dependency on the Java ecosystem:
| Dialect | JVM Required | GraalVM | Google Closure | Java stdlib |
|---------|-------------|---------|----------------|-------------|
| Clojure (JVM) | ✅ | ❌ | ❌ | ✅ |
| ClojureScript | ❌ | ❌ | ✅ | ❌ |
| Babashka | ❌ | ✅ | ❌ | Partial |
| **Clojure/Nim** | ❌ | ❌ | ❌ | ❌ |
This means:
- **No JVM warmup** — binaries start instantly
- **No GraalVM complexity** — no native-image configuration
- **No Java installation required** — the compiler itself is a single binary
- **True standalone deployment** — one file, zero runtime dependencies
### Native HAMT Implementation
Our persistent data structures are built from scratch in Nim, optimized for Nim's ORC garbage collector:
- **32-way branching** like Clojure's `PersistentVector`, but without Java object overhead
- **Structural sharing** via copy-on-write HAMT nodes
- **O(log₃₂ n)** for `assoc`/`dissoc`/`nth` — same asymptotic complexity as JVM Clojure
- **Nim ref objects** instead of Java interfaces — simpler memory layout, better cache locality
### Multi-Target Compilation
The same Clojure source compiles to four different targets from one codebase:
1. **Native binary** — `nim c` → C → machine code
2. **Shared library** — `nim c --app:lib` → `.so` / `.dll` / `.dylib`
3. **WASM** — `nim c -d:emscripten` → browser-native WebAssembly
4. **JavaScript** — `nim js` → browser/Node.js
No other Clojure implementation offers this breadth of targets without external tools.
## Key Design Decisions ## Key Design Decisions
### 1. AOT Compiler ### 1. AOT Compiler
docs/en/index.md
+30 -28
View File
@@ -1,36 +1,38 @@
# Clojure/Nim Documentation
[← Back to Index](index.md)
---
# Clojure/Nim Documentation (English)
> A Clojure dialect that compiles to Nim → C → native binaries. > A Clojure dialect that compiles to Nim → C → native binaries.
> **The only standalone Clojure implementation completely free from the Java ecosystem.**
## Table of Contents ## Choose Language / Избор на език
| # | Document | Description | | 🇬🇧 English | 🇧🇬 Български |
|---|----------|-------------| |------------|-------------|
| 01 | [Getting Started](01-getting-started.md) | Installation, build, CLI commands, quick examples | | [English Documentation](en/index.md) | [Българска Документация](bg/index.md) |
| 02 | [Architecture](02-architecture.md) | Compiler pipeline, design decisions, internal structure |
| 03 | [AI Integration](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — error assistance, code generation, optimization, debugging |
| 04 | [API Reference](04-api-reference.md) | JSON REPL protocol, operations, tool-call format |
| 05 | [User Guide](05-user-guide.md) | Macros, threading, interop, advanced patterns |
| 06 | [Roadmap](06-roadmap.md) | Completed phases, future plans, performance targets |
## Quick Start ## Quick Links
```bash - **GitHub/GitLab:** [lisp-nim](https://gitlab.com/balvatar/lisp-nim)
git clone https://gitlab.com/balvatar/lisp-nim.git - **Build:** `make build && make check`
cd lisp-nim - **Tests:** 276+ tests across 8 test suites
make build - **AI Integration:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
make check # build + tests + examples
./cljnim repl # human REPL
```
## Stats ## Why Clojure/Nim?
- **Tests:** 276+ across 8 suites Unlike every other Clojure dialect, Clojure/Nim has **zero dependency on the Java ecosystem** — no JVM, no GraalVM, no Google Closure Compiler, no Java standard library.
- **Compiler:** Nim → C → native
- **Targets:** Linux, macOS, Windows, JS, WASM, C shared libraries | Dialect | Java Ecosystem Dependency |
- **AI Support:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo |---------|---------------------------|
| Clojure (JVM) | Full — runs on JVM |
| ClojureScript | Heavy — Google Closure Compiler |
| Babashka | Medium — GraalVM native-image |
| **Clojure/Nim** | **None — completely standalone** |
### Unique Advantages
1. **Native HAMT Persistent Data Structures** — Built from scratch in Nim (Persistent Vector, Map, Set with structural sharing)
2. **Multiple Targets** — Native binary, shared library (.so/.dll), WASM, and JavaScript from one codebase
3. **AOT Compiler** — Clojure → Nim → C → native, running at C speed
4. **Nim/C Interop** — Direct FFI without JVM bridging overhead
5. **AI-Native Tooling** — Built-in AI integration for code generation, optimization, and debugging
6. **Concurrency Without JVM** — Atoms, Agents, and core.async channels without Java threads
7. **Tiny Binaries** — Single executables under 1MB with no runtime dependencies