// SPDX-License-Identifier: PMPL-1.0-or-later
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
= Nimiser
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:toc: left
:icons: font
== What Is This?
Nimiser generates **high-performance C libraries** from high-level interface
descriptions using https://nim-lang.org[Nim]'s extraordinary metaprogramming
system.
Nim (by Andreas Rumpf) compiles to C, C++, Objective-C, and JavaScript with
Python-like syntax and a compile-time metaprogramming system more powerful than
most languages' runtime reflection. Nimiser exploits this power to produce
optimised, standalone C libraries with zero overhead — the user never writes a
single line of Nim.
== How It Works
Describe your library interface in `nimiser.toml`. Nimiser:
1. **Parses** the manifest to extract types, functions, and strategies
2. **Generates Nim code** using compile-time metaprogramming:
- **Templates** for zero-cost generic abstractions
- **Macros** for AST-level code transformation
- **Generics** for type-safe specialisation
3. **Compiles Nim to optimised C** via `nim c --app:staticLib` / `--app:lib`
4. **Produces a standalone C library** with clean headers (`.h` + `.a`/`.so`)
5. **Creates a Zig FFI bridge** for verified integration
== Nim Metaprogramming Pipeline
[source]
----
nimiser.toml Nim Templates Nim Macros
(manifest) --> (zero-cost --> (AST-level
generics) transforms)
| | |
v v v
Rust CLI Nim Source Code Compile-Time AST
(parses, (generated) (rewritten)
validates) | |
v v
nim c --app:lib Optimised C Output
|
v
C Library (.a/.so)
C Headers (.h)
Zig FFI Bridge
----
=== Nim Template System
Nim templates are **hygienic, zero-cost code substitutions** evaluated at
compile time. Nimiser generates template-based wrappers for:
- Type-safe buffer management
- Platform-specific memory layouts
- Calling convention adapters (cdecl, stdcall)
=== Nim Macro System
Nim macros operate on the **compile-time AST** (Abstract Syntax Tree),
rewriting code before compilation. Nimiser uses macros for:
- Automatic C FFI export generation (`{.exportc.}` pragmas)
- Loop unrolling and specialisation for known sizes
- Dead code elimination for unused code paths
- Pragma injection for alignment and packing
=== Nim Generics
Nim generics produce **monomorphised, specialised code** at compile time.
Nimiser generates generic wrappers that are instantiated for each concrete
type in the manifest, yielding optimal code without runtime dispatch.
== Key Value
* **High-level descriptions -> optimised C libraries** with zero manual Nim
* **Nim's metaprogramming** (templates + macros + generics) generates specialised code paths
* **Multi-backend** -- C, C++, JavaScript from one source via Nim backends
* **Formally verified ABI** -- Idris2 dependent types prove interface correctness
* **Zero overhead** -- Nim compiles to C; generated code is as fast as hand-written C
== Architecture
Follows the hyperpolymath -iser pattern (same as https://github.com/hyperpolymath/chapeliser[Chapeliser]):
* **Manifest** (`nimiser.toml`) -- describe WHAT you want
* **Idris2 ABI** (`src/interface/abi/`) -- formal proofs of interface correctness
* **Zig FFI** (`src/interface/ffi/`) -- C-ABI bridge to target language runtime
* **Codegen** (`src/codegen/`) -- generates Nim code with templates, macros, and generics
* **Rust CLI** -- parses manifest, validates, generates, builds, runs
User writes zero Nim code. Nimiser generates everything.
Part of the https://github.com/hyperpolymath/iseriser[-iser family] of acceleration frameworks.
== Nim-Specific Features
=== Compile-Time Evaluation
Nim's `static` and `const` blocks evaluate arbitrary code at compile time.
Nimiser generates compile-time lookup tables, pre-computed hashes, and
constant-folded expressions that become literal values in the C output.
=== Pragma-Driven C Export
Nim pragmas (`{.exportc.}`, `{.cdecl.}`, `{.packed.}`, `{.align.}`) give
fine-grained control over the C ABI. Nimiser generates the correct pragmas
based on the Idris2 ABI specification, ensuring layout and calling convention
correctness.
=== Destructors and Move Semantics
Nim's `=destroy`, `=copy`, `=sink` hooks provide deterministic resource
management. Nimiser generates these hooks for library types that own
resources (allocations, file handles, etc.).
== Quick Start
[source,bash]
----
# Initialise a manifest
nimiser init
# Edit nimiser.toml to describe your library interface
# Generate Nim code, compile to C, produce library
nimiser generate
nimiser build --release
# The output/ directory contains:
# libmylib.a / libmylib.so -- compiled C library
# mylib.h -- C headers
# mylib_ffi.zig -- Zig FFI bridge
----
== Status
**Pre-alpha.** Architecture defined, CLI scaffolded, codegen stubs in place.
Nim template/macro generation is the primary implementation target.
== License
SPDX-License-Identifier: PMPL-1.0-or-later