This is an assembler that takes custom, user-defined instruction sets
and uses them to assemble source files.
This can be useful if you'd like to test out a new virtual machine's bytecode,
or even if you're eager to write programs for that new processor architecture
you just implemented in FPGA!
📱 Try it right now on your browser!
📖 Check out the User Guide for instructions!
🕹 Check out an example project which targets the NES!
💻 Install the VSCode syntax highlight extension!
📖 Check out instructions for migration from older versions to v0.11!
You can install directly from crates.io by running cargo install customasm.
Then the customasm application should automatically become available in your
command-line environment.
You can also download pre-built executables from the Releases section.
You can compile from source yourself by first cloning the repository and
then simply running cargo build.
There's also a battery of tests available at cargo test.
Given the following file:
```asm
{
load r1, {value} => 0x11 @ value8
load r2, {value} => 0x12 @ value8
load r3, {value} => 0x13 @ value8
add r1, r2 => 0x21
sub r3, {value} => 0x33 @ value8
jnz {address} => 0x40 @ address`16
ret => 0x50
}
multiply3x4: load r1, 0 load r2, 3 load r3, 4
.loop:
add r1, r2
sub r3, 1
jnz .loop
ret
```
...the assembler will use the #ruledef directive to convert the
instructions into binary code:
```asm outp | addr | data
0:0 | 0 | ; multiply3x4: 0:0 | 0 | 11 00 ; load r1, 0 2:0 | 2 | 12 03 ; load r2, 3 4:0 | 4 | 13 04 ; load r3, 4 6:0 | 6 | ; .loop: 6:0 | 6 | 21 ; add r1, r2 7:0 | 7 | 33 01 ; sub r3, 1 9:0 | 9 | 40 00 06 ; jnz .loop c:0 | c | 50 ; ret ```
```
Usage: customasm [options]
Options: -f, --format FORMAT The format of the output file. Possible formats: binary, annotated, annotatedbin, binstr, hexstr, bindump, hexdump, mif, intelhex, deccomma, hexcomma, decc, hexc, logisim8, logisim16 -o, --output [FILE] The name of the output file. -s, --symbol [FILE] The name of the output symbol file. -t, --iter [NUM] The max number of passes the assembler will attempt (default: 10). -p, --print Print output to stdout instead of writing to a file. -q, --quiet Suppress progress reports. -v, --version Display version information. -h, --help Display this information. ```