rgbasm(1) — Game Boy assembler
rgbasm program creates an RGB object
file from an assembly source file. The input file can
be a file path, or
Note that options can be abbreviated as long as the abbreviation
invalid because it could also be
arguments are as follows:
- Change the two characters used for binary constants. The defaults are 01.
- Add a string symbol to the compiled source code. This is equivalent to
name’ in code, or ‘
name’ if value is not specified.
- Export all labels, including unreferenced and local labels.
- Change the four characters used for gfx constants. The defaults are 0123.
- By default,
nopinstruction immediately after any
-hoption disables this behavior.
- Add an include path.
- Disable the optimization that turns loads of the form
LD [$FF00+n8],Ainto the opcode
LD [H $FF00+n8],Ain order to have full control of the result in the final ROM.
- Print make(1) dependencies to depend_file.
- To be used in conjunction with
-M. This makes
rgbasmassume that missing files are auto-generated: when
INCBINis attempted on a non-existent file, it is added as a dependency, then
rgbasmexits normally instead of erroring out. This feature is used in automatic updating of makefiles.
- When enabled, this causes a phony target to be added for each dependency other than the main file. This prevents make(1) from erroring out when dependency files are deleted.
- Add a target to the rules emitted by
-M. The exact string provided will be written, including spaces and special characters.is equivalent to
-MTfileB. If neither this nor
-MQis specified, the output file name is used.
- Same as
-MT, but additionally escapes any special make(1) characters, essentially ‘$’.
- Write an object file to the given filename.
- When padding an image, pad with this value. The default is 0x00.
- Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
- Print the version of the program and exit.
- Be verbose.
- 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.
- Disable all warning output, even when turned into errors.
Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process. The following options alter the way warnings are processed.
- Make all warnings into errors.
- Make the specified warning into an error. A warning's name is appended
-Werror=obsolete), and this warning is implicitly enabled and turned into an error. This is an error if used with a meta warning, such as
The following warnings are “meta” warnings, that enable a collection of other warnings. If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority. The position on the command-line acts as a tie breaker, the last one taking effect.
- This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
- This enables extra warnings that are less likely to pose a problem, but that may still be wanted.
- Enables literally every warning.
The following warnings are actual warning flags; with each
description, the corresponding warning flag is included. Note that each of
these flag also has a negation (for example,
-Wcharmap-redef enables the warning that
-Wno-charmap-redef disables). Only the non-default
flag is listed here. Ignoring the “no-” prefix, entries are
- Warns when
WARN-type assertions fail. (See “Aborting the assembly process” in rgbasm(5) for
- Warn about incorrect arguments to built-in functions, such as
STRSUB() with indexes outside of the string's bounds. This warning is enabled by
- Warn when re-defining a charmap mapping. This warning is enabled by
- Warn when dividing the smallest negative integer by -1, which yields itself due to integer overflow.
- Warn when a macro argument is empty. This warning is enabled by
- Warn when
STRRPL() is called with an empty string as its second argument (the substring to replace). This warning is enabled by
- Warn when a constant too large to fit in a signed 32-bit integer is
encountered. This warning is enabled by
- Warn when a string too long to fit in internal buffers is encountered.
This warning is enabled by
- Warn when shifting macro arguments past their limits. This warning is
- Warn when obsolete constructs such as the
PRINTTdirective are encountered.
- Warn when shifting right a negative value. Use a division by 2^N instead.
- Warn when a shift's operand is negative or greater than 32.
- Warn when an implicit truncation (for example,
LD [B @]) loses some bits.
- Warn when the
WARNbuilt-in is executed. (See “Aborting the assembly process” in rgbasm(5) for
You can assemble a source file in two ways.
$ rgbasm -o bar.o foo.asm
$ cat foo.asm | rgbasm -o bar.o -
$ rgbasm -o bar.o - < foo.asm
The resulting object file is not yet a usable ROM image—it must first be run through rgblink(1) and then rgbfix(1).
Please report bugs on GitHub.
rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
rgbasm was originally written by Carsten
Sørensen as part of the ASMotor package, and was later packaged in
RGBDS by Justin Lloyd. It is now maintained by a number of contributors at