What Is RASM?

RASM (Red Assembler) is an x86_64 assembler that uses Intel syntax. It is designed to generate object files, executable files, and raw binary images. Currently, RASM supports the following output formats:

ELF;
PE;
BIN;
Mach-O.

License

RASM is distributed under the Apache License 2.0.

The full license text is available in the LICENSE file located in the repository root.

Installation

Note

Before installing RASM, make sure your computer uses an x86_64 processor architecture (also known as AMD64, x64, or x86-64). At the moment, RASM supports only this architecture.

1. Download

Download the latest version of RASM using one of the following methods:

from the official website;
from GitHub Releases.

Choose the archive corresponding to your operating system.

2. Extract the archive

Extract the downloaded archive to a convenient location.

For example:

Windows: C:\Tools\RASM\
Linux: /opt/rasm/ or $HOME/.local/rasm/
macOS: /usr/local/rasm/ or $HOME/.local/rasm/

3. Add RASM to the PATH

To run the rasm command from any directory, add the directory containing the executable to your PATH environment variable.

Windows

Press Win + R.
Type sysdm.cpl and press Enter.
Open the Advanced tab.
Click Environment Variables…
Under User variables, select Path, then click Edit…
Click New.
Add the directory containing rasm.exe, for example:
```
C:\Tools\RASM
```
Click OK in all open dialogs.
Close and reopen your terminal.

Linux

Open your shell configuration file.

For Bash:

echo 'export PATH="$PATH:/path/to/rasm"' >> ~/.bashrc
source ~/.bashrc

For Zsh:

echo 'export PATH="$PATH:/path/to/rasm"' >> ~/.zshrc
source ~/.zshrc

Replace /path/to/rasm with the directory containing the rasm executable.

macOS

If you are using Bash:

echo 'export PATH="$PATH:/path/to/rasm"' >> ~/.bash_profile
source ~/.bash_profile

If you are using Zsh (the default shell on modern macOS versions):

echo 'export PATH="$PATH:/path/to/rasm"' >> ~/.zshrc
source ~/.zshrc

4. Verify the installation

Open a new terminal and run:

rasm -v

If the installation was successful, the installed RASM version information will be displayed.

Your First Program

The following examples demonstrate how to write a simple “Hello, world!” program.

Windows:

Source code:

.import kernel32.dll GetStdHandle
.import kernel32.dll WriteFile

.data
msg:
    .ascii "Hello, world!\r\n"
written:
    dd 0

.text
_start:
    sub rsp, 40

    mov rcx, -11
    call GetStdHandle

    mov rcx, rax
    lea rdx, [rip + msg]
    mov r8, 15
    lea r9, [rip + written]
    mov qword [rsp + 32], 0
    call WriteFile

    add rsp, 40
    mov rax, 0
    ret

Running the program:

# Using the JIT compiler:
rasm run main.s

# Using AOT compilation:
rasm build main.s

./main

Linux: Source code:

_start:
    jmp print

msg:
    .ascii "Hello, world!\n"

print:
    mov rax, 1
    mov rdi, 1
    lea rsi, [rip + msg]
    mov rdx, 14
    syscall

    mov rax, 60
    xor rdi, rdi
    syscall

The program is built and executed in the same way as on Windows.

macOS:

Examples for macOS will be added after the Mach-O backend has been fully tested.

Why is the code different?

On Windows, output is performed using the WinAPI because direct system calls are not considered a stable user-space programming interface.

On Linux, output is performed using the write system call.

The RASM Assembly Language

This chapter will cover the details of the RASM language.

Program Structure

Every program must define an entry point—the location where program execution begins.

In RASM, the entry point is a label named _start or main.

The simplest possible program looks like this:

main:
    mov rax, 60
    xor rdi, rdi
    syscall

A program typically consists of one or more sections. The most commonly used sections are:

.text — executable code;
.data — initialized data;
.bss — uninitialized data.

Each section contains a specific type of code or data.

Comments

Comments are used to document source code. They are ignored by the assembler and do not affect the generated output.

RASM supports single-line comments beginning with the ; character.

Example:

; Program entry point
_start:
    mov rax, 60      ; exit system call
    xor rdi, rdi     ; return code
    syscall

Identifiers

Identifiers are used to name labels, constants, variables, and other program objects.

An identifier may contain only the following characters:

Latin letters (A-Z, a-z);
digits (0-9);
the underscore character (_).

The first character of an identifier must be either a Latin letter or an underscore (_). An identifier cannot begin with a digit.

Examples of valid identifiers:

_start
main
message
loop1
_tmp

Examples of invalid identifiers:

1loop
my-variable
hello world

Case Sensitivity

Identifiers in RASM are case-sensitive.

For example, the following identifiers are considered different:

main:
Main:
MAIN:

In contrast, instruction mnemonics and register names are case-insensitive.

The following statements are equivalent:

mov rax, 0
MOV RAX, 0
Mov RaX, 0

Allowed Characters

In the current version of RASM, identifiers support only ASCII characters:

Latin letters (A-Z, a-z);
digits (0-9);
the underscore character (_).

Unicode characters (such as Cyrillic letters, CJK characters, or emoji) are not supported in identifiers.

2.4: Numeric Literals

RASM supports integer literals in multiple numeral systems.

Decimal

By default, numbers are interpreted as decimal.

10
255
4096

Hexadecimal

Hexadecimal numbers begin with the 0x prefix.

0x10
0xFF
0x1234ABCD

The letters A-F may be written in either uppercase or lowercase.

0xDEADBEEF
0xdeadbeef

Binary

Binary numbers begin with the 0b prefix.

0b1010
0b11111111

RASM Documentation - RASM