From 4739e2c151ed3dbfadebf5614d123930474fa40c Mon Sep 17 00:00:00 2001 From: dimgigov Date: Fri, 8 May 2026 23:59:24 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20highlight=20unique=20advantages=20?= =?UTF-8?q?=E2=80=94=20standalone,=20HAMT,=20multi-target?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 70 ++++++++++++++++++++++++++++++++++++-- docs/bg/02-architecture.md | 34 ++++++++++++++++++ docs/bg/index.md | 54 +++++++++++++++-------------- docs/en/02-architecture.md | 34 ++++++++++++++++++ docs/en/index.md | 58 ++++++++++++++++--------------- 5 files changed, 194 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 1f2fa5d..cde866c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Clojure/Nim > 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)]() @@ -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. +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? -- **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 - **Nim Ecosystem** — Direct access to Nim and C libraries via FFI - **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`, `>!`, ``, `->>`) | ✅ | -| Persistent data structures (HAMT vector/map) | ✅ | +| Persistent data structures (HAMT vector/map/set) | ✅ | +| Transients for batch mutations | ✅ | | Atoms, Agents, Channels | ✅ | | `loop`/`recur` | ✅ | | `try`/`catch`/`finally` | ✅ | +| Namespace system (`ns`, `:require`) | ✅ | +| Dependency resolution (deps.edn, Git deps) | ✅ | +| Nim/C FFI interop | ✅ | | AI integration (DeepSeek, OpenAI, MiMo) | ✅ | | Cross-compilation targets (JS, WASM, shared libs) | ✅ | +| Self-hosted REPL with tree-walking interpreter | ✅ | | 276+ tests | ✅ | ## Example diff --git a/docs/bg/02-architecture.md b/docs/bg/02-architecture.md index 9a45364..b0317b2 100644 --- a/docs/bg/02-architecture.md +++ b/docs/bg/02-architecture.md @@ -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 Компилатор diff --git a/docs/bg/index.md b/docs/bg/index.md index cc57eb4..03c8904 100644 --- a/docs/bg/index.md +++ b/docs/bg/index.md @@ -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 -| # | Документ | Описание | -|---|----------|----------| -| 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/Nim? -## Бърз старт +За разлика от всеки друг Clojure диалект, Clojure/Nim има **нула зависимост от Java екосистемата** — нито JVM, нито GraalVM, нито Google Closure Compiler, нито Java стандартна библиотека. -```bash -git clone https://gitlab.com/balvatar/lisp-nim.git -cd lisp-nim -make build -make check # компилация + тестове + примери -./cljnim repl # човешки REPL -``` +| Диалект | Зависимост от Java екосистемата | +|---------|--------------------------------| +| Clojure (JVM) | Пълна — работи върху JVM | +| ClojureScript | Голяма — Google Closure Compiler | +| Babashka | Средна — GraalVM native-image | +| **Clojure/Nim** | **Никаква — напълно самостоятелен** | -## Статистика +### Уникални предимства -- **Тестове:** 276+ в 8 suite-а -- **Компилатор:** Nim → C → нативен код -- **Target-и:** Linux, macOS, Windows, JS, WASM, C shared libraries -- **AI Поддръжка:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo +1. **Native HAMT Persistent структури от данни** — Изградени от нулата в Nim (Persistent Vector, Map, Set със структурно споделяне) +2. **Множество таргети** — Native бинарен файл, shared library (.so/.dll), WASM и JavaScript от един codebase +3. **AOT Компилатор** — Clojure → Nim → C → native, работи със скоростта на C +4. **Nim/C Interop** — Директен FFI без overhead от JVM bridging +5. **AI-Native Tooling** — Вградена AI интеграция за генериране на код, оптимизация и дебъгване +6. **Конкурентност без JVM** — Atoms, Agents и core.async channels без Java нишки +7. **Миниатюрни бинарни файлове** — Единични изпълними файлове под 1MB без runtime зависимости diff --git a/docs/en/02-architecture.md b/docs/en/02-architecture.md index 0763f16..9647c5f 100644 --- a/docs/en/02-architecture.md +++ b/docs/en/02-architecture.md @@ -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 ### 1. AOT Compiler diff --git a/docs/en/index.md b/docs/en/index.md index 39fd4dc..7193c35 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -1,36 +1,38 @@ - -[← Back to Index](index.md) - ---- - -# Clojure/Nim Documentation (English) +# Clojure/Nim Documentation > 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 | -|---|----------|-------------| -| 01 | [Getting Started](01-getting-started.md) | Installation, build, CLI commands, quick examples | -| 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 | +| 🇬🇧 English | 🇧🇬 Български | +|------------|-------------| +| [English Documentation](en/index.md) | [Българска Документация](bg/index.md) | -## Quick Start +## Quick Links -```bash -git clone https://gitlab.com/balvatar/lisp-nim.git -cd lisp-nim -make build -make check # build + tests + examples -./cljnim repl # human REPL -``` +- **GitHub/GitLab:** [lisp-nim](https://gitlab.com/balvatar/lisp-nim) +- **Build:** `make build && make check` +- **Tests:** 276+ tests across 8 test suites +- **AI Integration:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo -## Stats +## Why Clojure/Nim? -- **Tests:** 276+ across 8 suites -- **Compiler:** Nim → C → native -- **Targets:** Linux, macOS, Windows, JS, WASM, C shared libraries -- **AI Support:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo +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. + +| Dialect | Java Ecosystem Dependency | +|---------|---------------------------| +| 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