1RGBASM(1) BSD General Commands Manual RGBASM(1)
2
4 rgbasm — Game Boy assembler
5
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
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 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 -b chars, --binary-digits chars
21 Change the two characters used for binary constants. The de‐
22 faults are 01.
23 -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 -E, --export-all
30 Export all labels, including unreferenced and local labels.
31 -g chars, --gfx-chars chars
33 Change the four characters used for gfx constants. The defaults
34 are 0123.
35 -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 -i path, --include path
41 Add an include path.
42 -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 -M depend_file, --dependfile depend_file
49 Print make(1) dependencies to depend_file.
50 -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 -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 -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 -MQ target_file
71 Same as -MT, but additionally escapes any special make(1) charac‐
72 ters, essentially ‘$’.
73 -o out_file, --output out_file
75 Write an object file to the given filename.
76 -p pad_value, --pad-value pad_value
78 When padding an image, pad with this value. The default is 0x00.
79 -r recursion_depth, --recursion-depth recursion_depth
81 Specifies the recursion depth at which RGBASM will assume being
82 in an infinite loop.
83 -V, --version
85 Print the version of the program and exit.
86 -v, --verbose
88 Be verbose.
89 -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 -w Disable all warning output, even when turned into errors.
96
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 -Werror
103 Make all warnings into errors.
104 -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 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 -Wall This enables warnings that are likely to indicate an error or un‐
117 desired behavior, and that can easily be fixed.
118 -Wextra
120 This enables extra warnings that are less likely to pose a prob‐
121 lem, but that may still be wanted.
122 -Weverything
124 Enables literally every warning.
125 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 -Wno-assert
133 Warn when WARN-type assertions fail. (See “Aborting the assembly
134 process” in rgbasm(5) for ASSERT).
135 -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 -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 -Wcharmap-redef
146 Warn when re-defining a charmap mapping. This warning is enabled
147 by -Wall.
148 -Wdiv Warn when dividing the smallest negative integer (-2**31) by -1,
150 which yields itself due to integer overflow.
151 -Wempty-macro-arg
153 Warn when a macro argument is empty. This warning is enabled by
154 -Wextra.
155 -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 -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 -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 -Wmacro-shift
170 Warn when shifting macro arguments past their limits. This warn‐
171 ing is enabled by -Wextra.
172 -Wno-obsolete
174 Warn when obsolete constructs such as the _PI constant or PRINTT
175 directive are encountered.
176 -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 -Wshift
186 Warn when shifting right a negative value. Use a division by
187 2**N instead.
188 -Wshift-amount
190 Warn when a shift's operand is negative or greater than 32.
191 -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 -Wno-user
201 Warn when the WARN built-in is executed. (See “Aborting the
202 assembly process” in rgbasm(5) for WARN).
203
205 You can assemble a source file in two ways.
206 Straightforward way:
208 $ rgbasm -o bar.o foo.asm
209 Pipes way:
211 $ cat foo.asm | rgbasm -o bar.o -
212 $ rgbasm -o bar.o - < foo.asm
213 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
218 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
219
221 rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
222
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
227BSD March 28, 2021 BSD