ClojureElisp

A Clojure dialect that compiles to Emacs Lisp — like ClojureScript targets JavaScript, ClojureElisp targets Emacs.

Write .cljel files using Clojure syntax, compile them to .el files that run natively in Emacs 28.1+.

Quick Start

(require '[clojure-elisp.core :as clel])

;; Compile a single form
(clel/emit '(defn greet [name] (str "Hello, " name "!")))
;; => "(defun greet (name)\n  (clel-str \"Hello, \" name \"!\"))"

;; Compile a string of code
(clel/compile-string "(defn inc2 [x] (+ x 2))")
;; => "(defun inc2 (x)\n  (+ x 2))"

;; Compile a .cljel file to .el
(clel/compile-file "src/my_package.cljel" "out/my-package.el")

;; Compile an entire project in dependency order
(clel/compile-project ["src"] "out")

Example

;; my-package.cljel
(ns my.package
  (:require [clojure.string :as str]))

(defn greet [name]
  (let [msg (str "Hello, " name "!")]
    (message msg)))

(defn process-buffer []
  (-> (buffer-string)
      str/upper-case
      insert))

Compiles to:

;;; my-package.el --- -*- lexical-binding: t; -*-
;; Generated by ClojureElisp

(require 'clojure-elisp-runtime)

;;; Code:

(defun my-package-greet (name)
  (let* ((msg (clel-str "Hello, " name "!")))
    (message msg)))

(defun my-package-process-buffer ()
  (insert (upcase (buffer-string))))

(provide 'my-package)
;;; my-package.el ends here

Features

Language

• Functions: defn, fn (lambda), multi-arity, variadic (& rest), destructuring in params
• Bindings: let with sequential bindings, vector/map destructuring, :keys, :as, :or
• Control flow: if, when, cond, case, do, and, or
• Looping: loop/recur, letfn with mutual recursion
• Macros: defmacro (compile-time only), syntax-quote/unquote, macroexpand-1, macroexpand
• Error handling: try/catch/finally, throw, ex-info
• Namespaces: ns with :require, :as, :refer; namespace-prefixed definitions
• Protocols & types: defprotocol, defrecord, deftype with ^:mutable fields, set!
• Multimethods: defmulti/defmethod via cl-defgeneric/cl-defmethod
• Lazy sequences: lazy-seq, realized?, doall, dorun
• Atoms: atom, deref/@, reset!, swap!, add-watch, remove-watch
• Elisp interop: .method dot-notation, elisp/fn namespace, .-property access

Core Functions (100+)

Clojure core functions mapped to Elisp equivalents:

Compiler

• 3-stage pipeline: Reader (Clojure's) → Analyzer (AST + env) → Emitter (codegen)
• Source location tracking with optional ;;; L<line>:C<col> comments
• Incremental compilation with mtime tracking (.clel-cache/manifest.edn)
• Cross-file symbol table with compile-time warnings for missing symbols
• Dependency-aware project compilation with topological sort
• Name mangling: valid? → valid-p, reset! → reset-bang, my.ns/foo → my-ns-foo

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐
│   Reader    │───▶│   Analyzer   │───▶│   Emitter   │───▶│  Elisp Code  │
│ (Clojure's) │    │ (AST + env)  │    │ (codegen)   │    │   (.el)      │
└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘

Installation

Via bbin (recommended)

Install the clel CLI with bbin:

bbin install io.github.BuddhiLW/clojure-elisp

This gives you the clel command globally. Requires Babashka and the uberjar (see below).

Uberjar

The CLI delegates compilation to a JVM uberjar. Download from GitHub Releases or build from source:

# Build and install
make build install
# => ~/.local/lib/clel.jar

The CLI auto-detects the jar at ~/.local/lib/clel.jar or via $CLEL_JAR. If no jar is found, it falls back to clojure -M -e.

CLI Usage

clel compile                            # Compile project from clel.edn
clel compile src/my_app.cljel -o out/   # Compile a single file
clel compile src/ -o out/               # Compile a directory
clel watch src/ -o out/                 # Watch and recompile on changes
clel mcp                                # Start MCP stdio server
clel version                            # Print version

Runtime (Emacs Package)

Compiled .el files require the ClojureElisp runtime. Install via MELPA (once available):

(package-install 'clojure-elisp)

Or manually copy from the repo:

cp resources/clojure-elisp/clojure-elisp-runtime.el ~/.emacs.d/site-lisp/

Building from Source

# Build uberjar
clojure -T:build uber
# => target/clel-<version>.jar

Development

# Start REPL with dev dependencies (nREPL, CIDER)
clojure -M:dev

# Run tests (Kaocha — 500 tests, 2588 assertions)
clojure -M:test

# Build uberjar
clojure -T:build uber

Requirements

• Clojure 1.12+
• Java 21+ (for building/running the uberjar)
• Emacs 28.1+ (for compiled output)

License

MIT