Elk

Complete LC-3 toolchain. Available as both a Zig library and a command-line program.

Official Codeberg repository | GitHub mirror

Usage

# Show all options
elk --help
# Assemble and emulate
elk hello.asm
# Assemble and debug
elk hello.asm --debug
# Assemble to object file
elk hello.asm --assemble [--output hello.obj]
# Emulate object file
elk hello.obj --emulate

Installation

1. Download the latest binary release from GitHub releases.
2. Install the downloaded file to your PATH:

sudo install <filename> /usr/bin/elk

From source

Alternatively, you can build elk from source, only requiring Zig 0.16.0:

git clone https://codeberg.org/dxrcy/elk
cd elk/cli

zig build install -Doptimize=ReleaseSafe
sudo install zig-out/bin/elk /usr/bin/

Features

• Assembler (includes linting)
• Emulator
• Debugger (see below)
• Formatter (see issue)

Debugger Features

• Step through execution
• Inspect/modify registers and memory
• View current line in assembly source
• Set breakpoints
• Evaluate arbitrary instructions
• Recover from HALT and runtime exceptions
• Persistent history across program runs
• Import label declarations from symbol table (see issue)

Optional Extension Features

• Builtin debug traps (compatible with Lace)
• Stack instructions (compatible with Lace)
• Extra-permissive assembly syntax
• Parsing of character literals as integers
• Full support for arbitrary user-defined traps
• Support for arbitrary runtime hooks
• Patch label values after assembling
• Output symbol table and assembly listing
• Multiple file support (compatible with Laser)
• Preprocessor macros (compatible with Leap)

Quality-of-Life Features

• Descriptive warnings and error messages
• Assembly code style hints
• Multiple labels can annotate a single address

Other Toolchain Components

• Tree-sitter parser (syntax highlighting)

Supported Applications

• ELCI inter-op (see minecraft branch)
• Automatic testing framework