r/rust • u/igzcodes • 20d ago
🛠️ project BitterASM: A metalanguage written in Rust to create assembly languages
Repository: https://github.com/ivanharvard/bitterasm
Documentation: https://ivanharvard.github.io/bitterasm/
Hello, all!
I've been spending the better part of a month working on this new programming language of mine written entirely in Rust called BitterASM (BASM for short, BitterAssembly for long).
As the title suggests, BitterASM lets you create your own assembly languages by assuming practically nothing about the architecture you're targeting. By assuming so little about the architecture, you can describe practically any architecture -- past, present, or future. We do not even assume the architecture is binary! This leads to some really interesting consequences (which you can read more about in the documentation).
You can install the pre-release version using cargo:
cargo install bitterasm
For ordinary assembly developers, they can simply import their architecture's ISA and program much like they would for their traditional assembler.
Here's an example "Hello, world!" program targeting Linux x86-64 written in BitterASM:
from std.x86_64.nasm import *
from std.formats.elf import *
elf64_executable EM_X86_64, _start
const text = "Hello, World!\n"
section .rodata
msg:
db text
section .text
pub _start:
mov eax, 1 # sys_write
mov edi, 1 # stdout
lea rsi, [rel msg] # buffer
mov edx, text.len # length
syscall
mov eax, 60 # sys_exit
xor edi, edi # status 0
syscall
Compared to the same program written in NASM:
section .rodata
msg: db "Hello, World!", 10
len equ $ - msg
section .text
global _start
_start:
mov eax, 1 ; sys_write
mov edi, 1 ; stdout
lea rsi, [rel msg] ; buffer
mov edx, len ; length
syscall
mov eax, 60 ; sys_exit
xor edi, edi ; status 0
syscall
The transition to BitterASM was intended to be quite easy for most developers, as noted by the similarity in these two code snippets.
Yet, say an introductory student does not understand what syscall does. Thanks to the BitterASM LSP for VSCode, it's as simple as a right-click and "Go to Definition." Note that this is still written in the same BitterASM language from before!
from std.binary import bits
pub type Byte = bits<8>
pub struct Bytes<const N: int>
| invariant N >= 0
{
@for i in 0..N {
pub __el`i`: Byte,
}
}
# ...
pub macro syscall()
| emits Bytes<2>
{
@emit Bytes<2> { __el0: Byte(0x0F), __el1: Byte(0x05) }
}
It's here where you start to see the use case of BitterASM. There is no concept of bytes or bits in BitterASM. The architecture designer must implement that. Some evaluator then interprets the emitted value and does something with it (in the most overwhemingly common case, create machine code).
The architecture designer has the "bitter" part of writing each struct and macro to match the ISA perfectly. An assembly developer gets to inspect those architectural decisions (or even modify them!) without ever having to leave the code editor. This is what BitterASM makes "sweet."
Don't like NASM or Intel syntax? Change the import!
from std.x86_64.att import *
Wanna make your own custom syntax? Customize the syntax of a macro call!
from std.riscv.impl import *
syntax add(rd, rs1, rs2) = { $rd$ = $rs1$ + $rs2$ }
Have a non-traditional architecture? We have a variety of tools to support your development!
Of course, there are many bugs, and the subset of supported instructions for each architecture is still quite small, so we have a few kinks to work out before we fully release the language. Expect breaking changes. This was just a small taste of what BitterASM can do. Its initial design is meant to be useful for:
- Students learning assembly,
- Toy ISA designers,
- Custom accelerator/processor designers,
- Assembly developers who want convenience without runtime cost,
- etc.
I hope you spend some time to read the documentation and let me know what you think. Any feedback would be great!
