v0.1.8 · MIT License · Intel 8086

Learn x86 assembly
the hard way.

A sandboxed feedback loop powered by a Rust-based 16-bit x86 emulator. Write code, save the file, see the result instantly. Inspired by Rustlings.

→ Get started ★ Star on GitHub crates.io ↗
8086 Intel target
Rust Emulator core
0 Dependencies to learn
MIT License
asmlings — exercises/ex01_mov.asm
$ asmlings start
🔍 Watching exercises/
 
── Exercise 01: MOV basics ──
File: exercises/ex01_mov.asm
 
✓ Compiled successfully
✓ ASSERT_REG: AX == 0x1337 ... OK
✓ ASSERT_MEM: [0x0200] == 0x42 ... OK
 
⚠ Remove "; I AM NOT DONE" to advance
 
$
// 01 — audience

Who is this for?

ASMLings is built for people who want to understand computers at the instruction level, not just the framework level.

🎓
CS Students
Taking a computer architecture or systems course and need hands-on practice with registers, memory, and the instruction set beyond slides.
🦀
Rust & Systems Devs
You write low-level Rust and want to understand what the compiler emits, or need to read disassembled output without guessing.
🔍
Reverse Engineers
Learning to read or write x86 assembly for binary analysis, CTF challenges, or security research in a safe, instant-feedback environment.
💡
Curious Hackers
Anyone who has wondered "what actually happens when this runs" and wants to find out by doing — not by reading a textbook.
// 02 — installation

Get it running in 2 minutes

Pick your installation method. All paths end at the same place.

cargo-binstall FAST
$ cargo install cargo-binstall
$ cargo binstall asmlings

Skips compilation. Fastest install if you already have cargo-binstall.

cargo install STANDARD
$ cargo install asmlings

Compiles from source. Requires a Rust toolchain. Run rustup to get one.

Manual binary MANUAL

Download a pre-built binary for your platform directly from GitHub Releases.

↗ GitHub Releases
⚠ System Dependency: NASM required

ASMLings uses the NASM assembler under the hood. Install it for your OS:

macOS brew install nasm
Ubuntu/Debian apt install nasm
Arch Linux pacman -S nasm
Windows winget install NASM
// 03 — workflow

How it works

Three commands to go from zero to writing assembly with live feedback.

01
$ asmlings init
Extracts exercise files into an exercises/ folder and sets up your progress tracker. Run once per workspace.
02
$ asmlings start
Launches a persistent watch loop. Leave this running — it re-assembles and verifies your code every time you save a file.
03
Edit → Save → Repeat
Open the current exercise in any editor. Follow the comment instructions. Make the assertions pass, then delete ; I AM NOT DONE to advance.
+
$ asmlings run
Runs the current exercise once without entering watch mode. Useful for CI or quick single-shot checks.
+
$ asmlings debug
Dumps the assembled binary of the current exercise for debugger inspection.
+
$ asmlings hint
Provides a helpful hint or explanation for the current exercise if you get stuck.
// 04 — contributing

Help build it

ASMLings is open source and contributions are genuinely welcome — exercises, bug fixes, docs, or the emulator core.

🐛
Report a bug
Found unexpected behavior? Open an issue with steps to reproduce and the exercise file.
📝
Add an exercise
Use the template_exercises/ folder as a starting point. New topics — flags, loops, stack operations — are always useful.
⚙️
Improve the emulator
The Rust core in src/ handles 16-bit x86 emulation. More instructions, better error messages, CI improvements.
🔀
Fork & experiment
MIT licensed. Fork it, extend it for your own courses, adapt it for other architectures, or just poke around.
$ git clone https://github.com/giacomo-folli/asmlings.git
$ cd asmlings
$ cargo build
// share

Know someone learning assembly?

Send them here. Star the repo. The more people using it, the more exercises and emulator improvements land.

giacomo-folli.github.io/asmlings