RGBASM(1)

📦
version 1.0.4 · 4 versions
, in arch rolling, nixpkgs unstable

🎀 rgbasm — Game Boy assembler 🎀

✨ from the General Commands Manual ✨

okay so this is the whole vibe of rgbasm(1), and if you're here you're probably trying to turn your assembly source into a Game Boy object file. Which, honestly? Iconic. Let's get into it, bestie. 💅

✨ NAME ✨

rgbasm — Game Boy assembler. Short, sweet, main character energy. 👑

🌸 SYNOPSIS 🌸

rgbasm [-EhVw] [-v [-v ...]] [-B param] [-b chars] [--color when]
       [-D name[=value]] [-g chars] [-I path] [-M depend_file] [-MG]
       [-MC] [-MP] [-MT target_file] [-MQ target_file] [-o out_file]
       [-P include_file] [-p pad_value] [-Q fix_precision]
       [-r recursion_depth] [-s features:state_file] [-W warning]
       [-X max_errors] asmfile

🦋 DESCRIPTION 🦋

The rgbasm program creates an RGB object file from an assembly source file. The object file format is documented in rgbds(5). That's the whole description, but like... it's doing a lot. 💖

💜 ARGUMENTS 💜

okay so rgbasm accepts the usual short and long options, such as -V and --version. Options later in the command line override those set earlier, except for when duplicate options are considered an error. Options can be abbreviated as long as the abbreviation is unambiguous: --verb is --verbose, but --ver is invalid because it could also be --version. iykyk.

Unless otherwise noted, passing - (a single dash) as a file name makes rgbasm use standard input (for input files) or standard output (for output files). To suppress this behavior, and open a file in the current directory actually called -, pass ./- instead. Using standard input or output for more than one file in a single command may produce unexpected results. so maybe don't do that unless you're feeling chaotic.

rgbasm accepts decimal, hexadecimal, octal, and binary for numeric option arguments. Decimal numbers are written as usual; hexadecimal numbers must be prefixed with either $ or 0x; octal numbers must be prefixed with either & or 0o; and binary numbers must be prefixed with either % or 0b. (The prefixes $ and & will likely need escaping or quoting to avoid being interpreted by the shell.) Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive. For example, all of these are equivalent: 42, 042, 0x2A, 0X2A, 0x2a, &52, 0o52, 0O052, 0b00101010, 0B101010. slay.

The following options are accepted:

  • -B param, --backtrace param — Configures how location backtraces are printed if warnings or errors occur. This flag may be specified multiple times with different parameters that combine meaningfully. If param is a positive number, it specifies the maximum backtrace depth, abbreviating deeper ones. Other valid parameter values are the following:
    • 0 — Do not limit the maximum backtrace depth; this is the default.
    • all — Force all locations to be printed, even "quiet" ones (see “Excluding locations from backtraces” in rgbasm(5) for details).
    • no-all — Do not print "quieted" locations in backtraces; this is the default.
    • collapse — Print all locations on one line.
    • no-collapse — Print one location per line; this is the default.
  • -b chars, --binary-digits chars — Allow two characters to be used for binary constants in addition to the default 0 and 1. Valid characters are numbers other than 0 and 1, letters, ., #, or @.
  • --color when — Specify when to highlight warning and error messages with color: always, never, or auto. auto determines whether to use colors based on the NO_COLOR: https://no-color.org/ or FORCE_COLOR: https://force-color.org/ environment variables, or whether the output is to a TTY.
  • -D name[=value], --define name[=value] — Add a string symbol to the compiled source code. This is equivalent to name EQUS "value" in code, or name EQUS "1" if value is not specified.
  • -E, --export-all — Export all labels, including unreferenced and local labels.
  • -g chars, --gfx-chars chars — Allow four characters to be used for graphics constants in addition to the default 0, 1, 2, and 3. Valid characters are numbers other than 0 to 3, letters, ., #, or @. The defaults are 0123.
  • -h, --help — Print help text for the program and exit. (Help text wraps to the value of the COLUMNS environment variable if that is defined as nonzero; or else to the console window width if output is to a TTY.)
  • -I path, --include path — Add a new “include path”; path must point to a directory. When any INCLUDE (including the implicit one from -P), INCBIN, or READFILE is attempted, rgbasm first looks up the provided path from its working directory; if this fails, it tries again from each of the “include path” directories, in the order they were provided.
  • -M depend_file, --dependfile depend_file — Write make(1) dependencies to depend_file.
  • -MG — To be used in conjunction with -M. This makes rgbasm assume that missing files are auto-generated: when any INCLUDE (including the implicit one from -P), INCBIN, or READFILE is attempted on a non-existent file, it is added as a dependency, then rgbasm exits normally or continues processing (depending on whether -MC was enabled) instead of erroring out. This feature is used in automatic updating of Makefiles.
  • -MC — Implies -MG. This makes rgbasm continue processing after a non-existent dependency file, instead of exiting. Note that this is not recommended if any non-existent dependencies would have influenced subsequent processing, e.g. by causing an IF condition to take a different branch.
  • -MP — When enabled, this adds a phony target to the rules emitted by -M for each dependency other than the main file. This prevents make(1) from erroring out when dependency files are deleted.
  • -MT target_file — Add a target to the rules emitted by -M. The exact string provided will be written, including spaces and special characters.
-MT fileA -MT fileB

is equivalent to

-MT 'fileA fileB'

If neither this nor -MQ is specified, the output file name is used.

  • -MQ target_file — Same as -MT, but additionally escapes any special make(1) characters, essentially $.
  • -o out_file, --output out_file — Write an object file to the given filename.
  • -P include_file, --preinclude include_file — Pre-include a file. This acts as if a INCLUDE "include_file" was read before the input asmfile. Multiple files can be pre-included in the order they were provided.
  • -p pad_value, --pad-value pad_value — Use this as the value for DS directives in ROM sections, unless overridden. The default is 0x00.
  • -Q fix_precision, --q-precision fix_precision — Use this as the precision of fixed-point numbers after the decimal point, unless they specify their own precision. The default is 16, so fixed-point numbers are Q16.16 (since they are 32-bit integers). The argument may start with a . to match the Q notation, for example, -Q .16.
  • -r recursion_depth, --recursion-depth recursion_depth — Specifies the recursion depth past which rgbasm will assume being in an infinite loop. The default is 64.
  • -s features:state_file, --state features:state_file — Write the specified features to state_file, based on the final state of rgbasm at the end of its input. The expected features are a comma-separated subset of the following:
    • equ — Write all numeric constants as def name equ value.
    • var — Write all variables as def name = value.
    • equs — Write all string constants as def name equs "value".
    • char — Write all characters as charmap name, value.
    • macro — Write all macros as macro name ... endm.
    • all — Acts like equ,var,equs,char,macro.

This flag may be specified multiple times with different feature subsets to write them to different files (see “EXAMPLES” below).

  • -V, --version — Print the version of the program and exit.
  • -v, --verbose — Be verbose. The verbosity level is increased by one each time the flag is specified, with each level including the previous:
    1. Print the rgbasm configuration before taking actions.
    2. Print a notice before significant actions.
    3. Print some of the actions' intermediate results.
    4. Print some internal debug information.
    5. Print detailed internal information.

The verbosity level does not go past 6.

Note that verbose output is only intended to be consumed by humans, and may change without notice between RGBDS releases; relying on those for scripts is not advised.

  • -W warning, --warning warning — Set warning flag warning. A warning message will be printed if warning is an unknown warning flag. See the “DIAGNOSTICS” section for a list of warnings.
  • -w — Disable all warning output, even when turned into errors.
  • -X max_errors, --max-errors max_errors — If more than this number of errors (not warnings) occur, then abort the assembly process; -X 0 disables this behavior. The default is 100 if rgbasm is printing errors to a terminal, and 0 otherwise.
  • @at_file — Read more options and arguments from a file, as if its contents were given on the command line. Arguments are separated by whitespace or newlines. Lines starting with a hash sign (#) are considered comments and ignored.

No shell processing is performed, such as wildcard or variable expansion. There is no support for escaping or quoting whitespace to be included in arguments. The standard -- to stop option processing also disables at-file processing. Note that while -- can be used inside an at-file, it only disables option processing within that at-file, and processing continues in the parent scope.

💅 DIAGNOSTICS 💅

Okay so listen — warnings are these lil diagnostic messages that are like "hey bestie, this might be a little wrong" but they don't necessarily ruin the whole assembling thing. Think of them as a friend going "girl…" instead of a full intervention. 😭 The options below change how warnings get handled.

  • -Werror — turns every warning into a full-on error. Dramatic, but valid. You can negate it with -Wno-error so nothing gets turned into an error.
  • -Werror= — turns one specific warning or meta warning into an error. You just slap the warning's name on the end (like -Werror=obsolete) and boom, that warning is implicitly enabled and promoted to error status. Negate it with -Wno-error= and you stop a specific warning from becoming an error, even if -Werror is already doing its thing. 🫶

✨ the meta warnings ✨

These are the "meta" warnings — they're not one warning, they're a whole collection of other warnings. If a specific warning gets toggled by both a meta flag and a specific one, the more specific one takes priority. And if it's still a tie? Position on the command-line decides, and the last one takes effect. Periodt. 👑

  • -Wall — enables warnings that are likely to indicate an error or just undesired behavior, and that can easily be fixed. The "please just be normal" pack.
  • -Wextra — enables extra warnings that are less likely to pose a problem, but that you may still want. The "hmm, maybe?" pack.
  • -Weverything — enables literally every warning. No cap. Literally all of them.

🎀 the actual warning flags 🎀

So these are the real warning flags; with each description, the corresponding flag is included right there. Note that every one of these also has a negation — for example, -Wobsolete enables the warning that -Wno-obsolete disables, and -Wall enables every warning that -Wno-all disables. Only the non-default flag is listed here. Ignoring the "no-" prefix, entries are listed alphabetically. Yes, alphabetically. We're cute and organised. 💖

  • -Wno-assert — warns when WARN-type assertions fail. (See "Aborting the assembly process" in rgbasm(5) for ASSERT.)
  • -Wbackwards-for — warns when FOR loops have their start and stop values switched according to the step value. This one's enabled by -Wall.
  • -Wbuiltin-args — warns about incorrect arguments to built-in functions, like STRSLICE() with indexes outside of the string's bounds. Enabled by -Wall.
  • -Wcharmap-redef — warns when you re-define a charmap mapping. Rude. This is enabled by -Wall.
  • -Wdiv — warns when you divide the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow. Math said no. 💀
  • -Wempty-data-directive — warns when DB, DW, or DL is used without an argument in a ROM section. Enabled by -Wall.
  • -Wempty-macro-arg — warns when a macro argument is empty. Enabled by -Wextra.
  • -Wempty-strrpl — warns when STRRPL() is called with an empty string as its second argument (the substring to replace). Enabled by -Wall.
  • -Wexport-undefined — warns when exporting an undefined symbol. Enabled by -Wall.
  • -Wno-large-constant — warns when a constant too large to fit in a signed 32-bit integer shows up.
  • -Wmacro-shift — warns when shifting macro arguments past their limits. Enabled by -Wextra.
  • -Wno-nested-comment — warns when the block comment start sequence /* is found inside of a block comment. Block comments cannot be nested, bestie — the first */ will end the whole comment. 😭
  • -Wno-obsolete — warns when obsolete features are encountered, which have been deprecated and may later be removed. Use the new thing, it's giving main character energy.
  • -Wnumeric-string= — warns when a multi-character string is treated as a number. -Wnumeric-string=0 or -Wno-numeric-string disables this warning. -Wnumeric-string=1 or just -Wnumeric-string warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer. -Wnumeric-string=2 warns about any multi-character string. Pick your level of pickiness. 💅
  • -Wpurge= — warns when purging symbols which are likely to have been necessary. -Wpurge=0 or -Wno-purge disables this warning. -Wpurge=1 warns when purging any exported symbol (regardless of type). -Wpurge=2 or just -Wpurge also warns when purging any label (even if not exported). Choices, choices.
  • -Wshift — warns when shifting right a negative value. Use a division by 2**N instead. Trust.
  • -Wshift-amount — warns when a shift's operand is negative or greater than 32.
  • -Wtruncation= — warns when an implicit truncation (for example, db to an 8-bit value) loses some bits. -Wtruncation=0 or -Wno-truncation disables this warning. -Wtruncation=1 or just -Wtruncation warns when an N-bit value is 2**N or greater, or less than -2**N. -Wtruncation=2 also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding. Bits are getting lost bestie, we must report it. 🫶
  • -Wunmapped-char= — warns when a character goes through charmap conversion but has no defined mapping. -Wunmapped-char=0 or -Wno-unmapped-char disables this warning. -Wunmapped-char=1 or just -Wunmapped-char only warns if the active charmap is not empty. -Wunmapped-char=2 warns if the active charmap is empty, and/or is not the default charmap main. The ladder of "how much do I care". ✨
  • -Wunmatched-directive — warns when a PUSHC, PUSHO, or PUSHS directive does not have a corresponding POPC, POPO, or POPS. This warning is enabled by -Wextra.
  • -Wunterminated-load — warns when a LOAD block is not terminated by an ENDL. Enabled by -Wextra.
  • -Wno-user — warns when the WARN built-in is executed. (See "Aborting the assembly process" in rgbasm(5) for WARN.)

🌸 EXAMPLES 🌸

You can assemble a source file in two ways, and both are iconic in their own right.

The straightforward way:

$ rgbasm -o bar.o foo.asm

The pipes way:

$ cat foo.asm | rgbasm -o bar.o -
$ rgbasm -o bar.o - < foo.asm

Now, the resulting object file is not yet a usable ROM image — it must first be run through rgblink(1) and then rgbfix(1). It's a whole journey, not a one-step situation. 🦋

Writing the final assembler state to a file:

$ rgbasm -s all:state.dump.asm foo.asm

Or to multiple files:

$ rgbasm -s equ,var:numbers.dump.asm -s equs:strings.dump.asm foo.asm

🐛 BUGS 🐛

Found a bug or a mistake in this documentation? Please report it on GitHub, we're literally right here:

https://github.com/gbdev/rgbds/issues

👑 SEE ALSO 👑

rgbasm(5), rgblink(1), rgbfix(1), rgbgfx(1), gbz80(7), rgbasm-old(5), rgbds(5), rgbds(7)

🌈 HISTORY 🌈

rgbasm was originally written by Carsten Sørensen as part of the ASMotor package, and was later repackaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at https://github.com/gbdev/rgbds. Look at the legacy, we love to see it. 💜

Okay that's the whole page bestie, go assemble something gorgeous. 💅✨

Debian build, dated September 22, 2026 — RGBASM(1), slay.

📦 where this page comes from