ratasm
A terminal IDE and debugger for x86-64 assembly.
Assembly is hard mostly because the machine state is invisible. You write
add rax, rbx and to know what happened you need two registers, six flags and
the stack, at that instruction rather than before or after it.
ratasm puts them next to your source. The register panel marks what the last
instruction changed. The flag panel lists the conditional jumps that would be
taken as the flags stand right now. The explainer reads your actual operands,
so add rax, rbx becomes RAX ← RAX + RBX with what it reads, writes and
sets. The syscall finder answers which register the fourth argument goes in
(R10, not RCX).
Registers and memory come from GDB, the disassembly from a real x86-64 decoder, the syscall numbers from your kernel's headers. Where ratasm does not know something it says so.
Install
|
Downloads the release binary for your machine, checks its checksum and installs
it into ~/.local/bin (RATASM_INSTALL_DIR overrides that). To read the script
first, download it, then run sh install.sh.
Or cargo install ratasm, or clone and cargo install --path ..
ratasm drives the standard Linux toolchain rather than bundling one: nasm to
assemble, ld to link, and gdb to debug. Everything except debugging works
without gdb.
Run ratasm doctor to check what is installed. Linux on x86-64 only for now.
Start
ratasm new writes a working, commented write/exit program rather than a
stub. F6 assembles it, F5 runs it, F9 sets a
breakpoint on the line you name, and F7 steps one instruction while
you watch the registers move.
Running opens a real terminal in the Output panel. Programs can prompt, read input, move the cursor and use ANSI colour; the same terminal is attached when the program runs under GDB. Ctrl+F5 stops it.
ratasm file.asm opens single files, several at once if you name several.
Pages
The interface is four pages, each holding the panels for one activity. Alt plus the number along the top opens one; Tab moves between the panels of the page you are on.
| Page | For |
|---|---|
| Code | Writing and building: source view, project files, build output |
| Debug | Watching the machine: registers, flags, stack, disassembly |
| Learn | Lessons and questions, with a scratchpad to try them in |
| Reference | Looking up a system call or what an instruction does |
Panels adapt to the terminal. Anything taller than its panel scrolls, with a scrollbar to say so; the mouse wheel moves whatever it is pointing at. Below roughly 100 columns a page keeps its main panel and puts the rest behind a tab strip rather than squeezing a register view into a width where it shows nothing.
Keys
| Key | Action |
|---|---|
| F5 / F6 | Run or continue / build |
| F7 / F8 / F10 | Step instruction / over / source line |
| Shift+F7 | Step one instruction backwards |
| F9 | Toggle a breakpoint on a line |
| F1 / F2 | Learning panel / scratchpad |
| F3 | Show the complete status message in Output |
| Ctrl+P | Command palette |
| Ctrl+E / Ctrl+O | Edit in $EDITOR / open |
| Ctrl+G | Show an address in the memory panel |
| Ctrl+K | Syscall finder |
| Alt+1..4 | Open a page |
Every binding is configurable, and conflicts are reported at start-up instead of silently shadowing one another. Full list: docs/keybindings.md.
Configuration
Per-project settings live in .ratasm.toml beside your source. Every field has
a default, so you write down only what differs.
[]
= "hello"
= "src/main.asm"
= ["src/util.asm"]
[]
= ["-f", "elf64"]
[]
= 5000 # 0 disables the limit
A misspelled key is an error at load time rather than a setting that quietly does nothing, and paths may not escape the project directory. Reference: docs/configuration.md.
A single .asm file with no project file works too: ratasm uses the defaults
and treats the file's directory as the root.
Security
Programs you write in ratasm run natively, with your privileges. The scratchpad is a convenience for trying one instruction, not a sandbox. There is no isolation, no seccomp filter, no container. Do not paste assembly you do not understand into it and run it.
The run timeout stops a program that loops forever; it is not a security
boundary. External tools are launched through execve with separate arguments
and never through a shell.
Limitations
- Linux x86-64 and NASM syntax only. A project file naming
aarch64orgasgets a clear "not supported yet" rather than a confusing failure. - Vector instructions are named and described but not modelled per lane, and the explainer says so.
- Around sixty syscalls carry full argument documentation. All 385 are
searchable; the rest point at
man 2. - Source-level stepping needs debug information. Without it you get instruction-level stepping.
- One debug session at a time, no multi-threaded targets.
- Stepping backwards needs GDB's recording, which is on by default and costs
time per instruction.
record = falseturns it off. - Copying reaches the system clipboard through OSC 52 where the terminal allows it, but pasting only sees what ratasm copied: reading the clipboard back is not something a terminal reliably permits.
Contributing
All three must pass. Tests needing nasm, ld or gdb skip themselves when
those are missing. Workflow: CONTRIBUTING.md. Architecture
notes: docs/architecture.md.
Roadmap
Watchpoints and conditional breakpoints, AT&T syntax throughout, GAS source support, more lessons, and AArch64 and RISC-V back ends.
Licence
MIT. See LICENSE.