cl-cc

A self-hosting Common Lisp compiler and runtime implemented in pure Common Lisp. cl-cc compiles ANSI Common Lisp to a register-based bytecode VM, and from there to native x86-64, AArch64, and WebAssembly; PHP and JavaScript frontends lower to the same AST and reuse the whole backend. There is no project C source — the VM interpreter includes a minimal SBCL host-backed CFFI-compatible FFI shim. The compiler's core design (CLOS dispatch, Prolog-based optimization, CPS transformation, Hindley–Milner type inference) is implemented using the same language features it compiles.

Full documentation is published at https://nerima-lisp.github.io/cl-cc/. The source for that site lives in docs/src/.

Quick Start

nix develop

cl-cc eval "(+ 1 2)"
cl-cc repl                             # definitions persist across forms
cl-cc run file.lisp
cl-cc run file.php                     # frontend chosen by extension
cl-cc run file.js
cl-cc compile file.lisp -o out --arch x86-64

Install

# flake.nix
inputs.cl-cc = {
  url = "github:nerima-lisp/cl-cc/v0.1.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

Note the pinned tag. Consumers inside this org must pin a release tag rather than follow the default branch.

Documentation

• Getting started — install, first program, building from source
• Core concepts — the ANSI Common Lisp surface cl-cc implements
• CLI reference — every command and flag
• Architecture — the pipeline, the packages, and how self-hosting works
• Compatibility — ANSI conformance status, known limitations, security scope

Development

nix develop          # SBCL with every ASDF dependency and the cl-cc CLI
nix run .#test       # the canonical fast unit test plan
nix build            # standalone binary at ./result/bin/cl-cc
nix fmt              # format Nix sources (treefmt)
nix flake check      # tests + formatting + docs, the same gate CI uses

Tests live in t/ and run under cl-weave, the org's test framework; the entry point is ./run-tests.lisp. nix run .#test executes the fast unit plan only — integration, E2E, conformance, and documentation/evidence suites are selected by suite taxonomy and run explicitly.

Set CLCC_TEST_TIMEOUT (default 10) or CLCC_SUITE_TIMEOUT (default 600) to override the test timeouts, in seconds. If stale FASLs cause trouble after switching project paths, clear the cache with rm -rf ~/.cache/common-lisp/ && mkdir -p ~/.cache/common-lisp/.

docs/notes/ holds the unpublished specification trail for the compiler subsystems. It is outside the documentation site and is not built.

Contributing

See the org-wide CONTRIBUTING guide and the package standard.

Support

See SUPPORT. Report security issues privately through GitHub Security Advisories.

License

MIT. See LICENSE.