WARNING

This is an old unmaintained fork of customasm. It is the result of me needing a very specific asm{} behauviour for the one-instruction-cpu I was designing at the time.

It is here AT IS for MY OWN personal use. Feel free to also USE IT AT YOUR OWN RISK.

customasm

This is an assembler that takes custom, user-defined instruction sets and uses them to assemble source files.
It can be useful, for example, if you're trying to test the bytecode of a new virtual machine, or if you're eager to write programs for that new microprocessor architecture you just implemented in an FPGA chip!

🖥️ Try it right now on your browser!

🕹️ Check out an example project which targets the NES!

📜 Check out the changelog for new features!

⌨️ Install the VSCode syntax highlight extension!

❤️ Support me!

Documentation

📚 Check out the Documentation for advanced features and a how-to guide!

Installation

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.

Upgrade to v0.11

📖 Check out instructions for migration from older versions to v0.11!

Example

Given the following file:

#ruledef
{
    load r1, {value} => 0x11 @ value`8
    load r2, {value} => 0x12 @ value`8
    load r3, {value} => 0x13 @ value`8
    add  r1, r2      => 0x21
    sub  r3, {value} => 0x33 @ value`8
    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:

 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

Command-Line Usage

Usage: customasm [options] <asm-file-1> ... <asm-file-N>

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.