1RGBASM(1)                 BSD General Commands Manual                RGBASM(1)
2

NAME

4     rgbasm — Game Boy assembler
5

SYNOPSIS

7     rgbasm [-EhLVvw] [-b chars] [-D name[=value]] [-g chars] [-i path]
8            [-M depend_file] [-MG] [-MP] [-MT target_file] [-MQ target_file]
9            [-o out_file] [-p pad_value] [-r recursion_depth] [-W warning]
10            file ...
11

DESCRIPTION

13     The rgbasm program creates an RGB object file from an assembly source
14     file.  The input file can be a file path, or - denoting stdin.
15
16     Note that options can be abbreviated as long as the abbreviation is unam‐
17     biguous: --verb is --verbose, but --ver is invalid because it could also
18     be --version.  The arguments are as follows:
19
20     -b chars, --binary-digits chars
21             Change the two characters used for binary constants.  The de‐
22             faults are 01.
23
24     -D name[=value], --define name[=value]
25             Add a string symbol to the compiled source code.  This is equiva‐
26             lent to ‘name EQUS "value"’ in code, or ‘name EQUS "1"’ if value
27             is not specified.
28
29     -E, --export-all
30             Export all labels, including unreferenced and local labels.
31
32     -g chars, --gfx-chars chars
33             Change the four characters used for gfx constants.  The defaults
34             are 0123.
35
36     -h, --halt-without-nop
37             By default, rgbasm inserts a nop instruction immediately after
38             any halt instruction.  The -h option disables this behavior.
39
40     -i path, --include path
41             Add an include path.
42
43     -L, --preserve-ld
44             Disable the optimization that turns loads of the form LD
45             [$FF00+n8],A into the opcode LDH [$FF00+n8],A in order to have
46             full control of the result in the final ROM.
47
48     -M depend_file, --dependfile depend_file
49             Print make(1) dependencies to depend_file.
50
51     -MG     To be used in conjunction with -M.  This makes rgbasm assume that
52             missing files are auto-generated: when INCLUDE or INCBIN is at‐
53             tempted on a non-existent file, it is added as a dependency, then
54             rgbasm exits normally instead of erroring out.  This feature is
55             used in automatic updating of makefiles.
56
57     -MP     When enabled, this causes a phony target to be added for each de‐
58             pendency other than the main file.  This prevents make(1) from
59             erroring out when dependency files are deleted.
60
61     -MT target_file
62             Add a target to the rules emitted by -M.  The exact string pro‐
63             vided will be written, including spaces and special characters.
64                   -MT fileA -MT fileB
65             is equivalent to
66                   -MT 'fileA fileB'.
67             If neither this nor -MQ is specified, the output file name is
68             used.
69
70     -MQ target_file
71             Same as -MT, but additionally escapes any special make(1) charac‐
72             ters, essentially ‘$’.
73
74     -o out_file, --output out_file
75             Write an object file to the given filename.
76
77     -p pad_value, --pad-value pad_value
78             When padding an image, pad with this value.  The default is 0x00.
79
80     -r recursion_depth, --recursion-depth recursion_depth
81             Specifies the recursion depth at which RGBASM will assume being
82             in an infinite loop.
83
84     -V, --version
85             Print the version of the program and exit.
86
87     -v, --verbose
88             Be verbose.
89
90     -W warning, --warning warning
91             Set warning flag warning.  A warning message will be printed if
92             warning is an unknown warning flag.  See the DIAGNOSTICS section
93             for a list of warnings.
94
95     -w      Disable all warning output, even when turned into errors.
96

DIAGNOSTICS

98     Warnings are diagnostic messages that indicate possibly erroneous behav‐
99     ior that does not necessarily compromise the assembling process.  The
100     following options alter the way warnings are processed.
101
102     -Werror
103             Make all warnings into errors.
104
105     -Werror=
106             Make the specified warning into an error.  A warning's name is
107             appended (example: -Werror=obsolete), and this warning is implic‐
108             itly enabled and turned into an error.  This is an error if used
109             with a meta warning, such as -Werror=all.
110
111     The following warnings are “meta” warnings, that enable a collection of
112     other warnings.  If a specific warning is toggled via a meta flag and a
113     specific one, the more specific one takes priority.  The position on the
114     command-line acts as a tie breaker, the last one taking effect.
115
116     -Wall   This enables warnings that are likely to indicate an error or un‐
117             desired behavior, and that can easily be fixed.
118
119     -Wextra
120             This enables extra warnings that are less likely to pose a prob‐
121             lem, but that may still be wanted.
122
123     -Weverything
124             Enables literally every warning.
125
126     The following warnings are actual warning flags; with each description,
127     the corresponding warning flag is included.  Note that each of these flag
128     also has a negation (for example, -Wcharmap-redef enables the warning
129     that -Wno-charmap-redef disables).  Only the non-default flag is listed
130     here.  Ignoring the “no-” prefix, entries are listed alphabetically.
131
132     -Wno-assert
133             Warn when WARN-type assertions fail. (See “Aborting the assembly
134             process” in rgbasm(5) for ASSERT).
135
136     -Wbackwards-for
137             Warn when FOR loops have their start and stop values switched ac‐
138             cording to the step value.  This warning is enabled by -Wall.
139
140     -Wbuiltin-args
141             Warn about incorrect arguments to built-in functions, such as
142             STRSUB() with indexes outside of the string's bounds.  This warn‐
143             ing is enabled by -Wall.
144
145     -Wcharmap-redef
146             Warn when re-defining a charmap mapping.  This warning is enabled
147             by -Wall.
148
149     -Wdiv   Warn when dividing the smallest negative integer (-2**31) by -1,
150             which yields itself due to integer overflow.
151
152     -Wempty-macro-arg
153             Warn when a macro argument is empty.  This warning is enabled by
154             -Wextra.
155
156     -Wempty-strrpl
157             Warn when STRRPL() is called with an empty string as its second
158             argument (the substring to replace).  This warning is enabled by
159             -Wall.
160
161     -Wlarge-constant
162             Warn when a constant too large to fit in a signed 32-bit integer
163             is encountered.  This warning is enabled by -Wall.
164
165     -Wlong-string
166             Warn when a string too long to fit in internal buffers is encoun‐
167             tered.  This warning is enabled by -Wall.
168
169     -Wmacro-shift
170             Warn when shifting macro arguments past their limits.  This warn‐
171             ing is enabled by -Wextra.
172
173     -Wno-obsolete
174             Warn when obsolete constructs such as the _PI constant or PRINTT
175             directive are encountered.
176
177     -Wnumeric-string=
178             Warn when a multi-character string is treated as a number.
179             -Wnumeric-string=0 or -Wno-numeric-string disables this warning.
180             -Wnumeric-string=1 or just -Wnumeric-string warns about strings
181             longer than four characters, since four or fewer characters fit
182             within a 32-bit integer.  -Wnumeric-string=2 warns about any
183             multi-character string.
184
185     -Wshift
186             Warn when shifting right a negative value.  Use a division by
187             2**N instead.
188
189     -Wshift-amount
190             Warn when a shift's operand is negative or greater than 32.
191
192     -Wtruncation=
193             Warn when an implicit truncation (for example, db to an 8-bit
194             value) loses some bits.  -Wtruncation=0 or -Wno-truncation dis‐
195             ables this warning.  -Wtruncation=1 warns when an N-bit value's
196             absolute value is 2**N or greater.  -Wtruncation=2 or just
197             -Wtruncation also warns when an N-bit value is less than
198             -2**(N-1), which will not fit in two's complement encoding.
199
200     -Wno-user
201             Warn when the WARN built-in is executed. (See “Aborting the
202             assembly process” in rgbasm(5) for WARN).
203

EXAMPLES

205     You can assemble a source file in two ways.
206
207     Straightforward way:
208           $ rgbasm -o bar.o foo.asm
209
210     Pipes way:
211           $ cat foo.asm | rgbasm -o bar.o -
212           $ rgbasm -o bar.o - < foo.asm
213
214     The resulting object file is not yet a usable ROM image—it must first be
215     run through rgblink(1) and then rgbfix(1).
216

BUGS

218     Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
219

SEE ALSO

221     rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
222

HISTORY

224     rgbasm was originally written by Carsten Sørensen as part of the ASMotor
225     package, and was later packaged in RGBDS by Justin Lloyd.  It is now
226     maintained by a number of contributors at https://github.com/gbdev/rgbds
227
228BSD                             March 28, 2021                             BSD
Impressum