yodl

Yet anOther (hardware) Description Language

Quick links

• Documentation
• Playground

Installation

npm

The JS build of Yodl can be installed from npm:

$ npm install --global yodl

wasm

A WASI Preview 1 build of yodl is included in this repository:

wasmtime --dir examples res/yodl-wasi.wasm examples/RISCV.yodl "write_firrtl"

To compile FIRRTL outputs to SystemVerilog, install firtool

Usage

$ yodl examples/Hello.yodl "write_firrtl Hello.fir"
$ firtool --format=fir --verilog Hello.fir -o Hello.sv

Development

Install Moonbit:

$ curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s '0.10.11+8f8e8db1e'

Documentation, playground, and tour

The playground includes a 12-lesson tour, separate from the larger designs under examples/. Start with a logic gate, then explore types, combinational logic, reusable modules, registers, and memory. Each lesson offers an explanation, a suggested compiler output to inspect, and a small experiment. Drafts are saved locally, and circuits can be shared by link or downloaded.

With MoonBit, Bun 1.4.0, and Python 3 installed, start the documentation and playground:

bash scripts/serve-playground.sh

Open http://localhost:8080/book/ for documentation or http://localhost:8080/playground.html for the playground. After editing Markdown, browser code, or tour content, restart the script to rebuild, then reload the page. The editor loads Monaco from a CDN, so its initial load requires internet access.

The book is built from Markdown using Bun's built-in parser and shares the playground's themes, Monaco editor, and browser compiler. Examples support local drafts, compiler stages, expected errors, output comparison, and share links. See documentation authoring for example metadata and validation.

Build the complete static site into dist/ with bun run build:site. GitHub Pages deployment uses this same build; no application server is required.

Validate the browser components and documentation with bun run test:docs. Validate the tour and backend output with:

moon test src/lib/tests
bash scripts/test.sh

Checklist

• FIRRTL export
• Generic multi-port memories
• Imports (TODO: unqualified imports)
• Verilator + SDL graphics simulation example
• Multi-dimensional vectors ([4][8]u16)
• Optional module parameters (and register initial value)
• Arbitrary port types
• Type parameters
• External modules
• Source Maps
• Test Benches
• FIRRTL to RTLIL backend to bypass SystemVerilog generation
• Language Server Protocol (LSP) support
• KiCad schematics export
• Web tour/playground