1RGBASM(1) BSD General Commands Manual RGBASM(1)
2
4 rgbasm — Game Boy assembler
5
7 rgbasm [-EHhLlVvw] [-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 include_file] [-p pad_value] [-Q fix_precision]
10 [-r recursion_depth] [-W warning] asmfile
11
13 The rgbasm program creates an RGB object file from an assembly source
14 file. The input asmfile can be a path to a file, or - to read from stan‐
15 dard input.
16 Note that options can be abbreviated as long as the abbreviation is unam‐
18 biguous: --verb is --verbose, but --ver is invalid because it could also
19 be --version. The arguments are as follows:
20 -b chars, --binary-digits chars
22 Change the two characters used for binary constants. The de‐
23 faults are 01.
24 -D name[=value], --define name[=value]
26 Add a string symbol to the compiled source code. This is equiva‐
27 lent to ‘name EQUS "value"’ in code, or ‘name EQUS "1"’ if value
28 is not specified.
29 -E, --export-all
31 Export all labels, including unreferenced and local labels.
32 -g chars, --gfx-chars chars
34 Change the four characters used for gfx constants. The defaults
35 are 0123.
36 -H, --nop-after-halt
38 By default, rgbasm inserts a nop instruction immediately after
39 any halt instruction, but this has been deprecated and prints a
40 warning message the first time it occurs. The -H option opts
41 into this insertion, so no warning will be printed.
42 -h, --halt-without-nop
44 Disables inserting a nop instruction immediately after any halt
45 instruction.
46 -I path, --include path
48 Add a new “include path; path” must point to a directory. When a
49 INCLUDE (including the implicit one from -P) or INCBIN is at‐
50 tempted, rgbasm first looks up the provided path from its working
51 directory; if this fails, it tries again from each of the
52 “include path” directories, in the order they were provided.
53 -L, --preserve-ld
55 By default, rgbasm optimizes loads of the form LD [$FF00+n8],A
56 into the opcode LDH [$FF00+n8],A, but this has been deprecated
57 and prints a warning message the first time it occurs. The -L
58 option disables this optimization.
59 -l, --auto-ldh
61 Optimize loads of the form LD [$FF00+n8],A into the opcode LDH
62 [$FF00+n8],A.
63 -M depend_file, --dependfile depend_file
65 Print make(1) dependencies to depend_file.
66 -MG To be used in conjunction with -M. This makes rgbasm assume that
68 missing files are auto-generated: when INCLUDE (including the
69 implicit one from -P) or INCBIN is attempted on a non-existent
70 file, it is added as a dependency, then rgbasm exits normally in‐
71 stead of erroring out. This feature is used in automatic updat‐
72 ing of makefiles.
73 -MP When enabled, this causes a phony target to be added for each de‐
75 pendency other than the main file. This prevents make(1) from
76 erroring out when dependency files are deleted.
77 -MT target_file
79 Add a target to the rules emitted by -M. The exact string pro‐
80 vided will be written, including spaces and special characters.
81 -MT fileA -MT fileB
82 is equivalent to
83 -MT 'fileA fileB'.
84 If neither this nor -MQ is specified, the output file name is
85 used.
86 -MQ target_file
88 Same as -MT, but additionally escapes any special make(1) charac‐
89 ters, essentially ‘$’.
90 -o out_file, --output out_file
92 Write an object file to the given filename.
93 -P include_file, --preinclude include_file
95 Pre-include a file. This acts as if a ‘INCLUDE "include_file"’
96 was read before the input asmfile.
97 -p pad_value, --pad-value pad_value
99 When padding an image, pad with this value. The default is 0x00.
100 -Q fix_precision, --q-precision fix_precision
102 Use this as the precision of fixed-point numbers after the deci‐
103 mal point, unless they specify their own precision. The default
104 is 16, so fixed-point numbers are Q16.16 (since they are 32-bit
105 integers). The argument may start with a ‘.’ to match the Q no‐
106 tation, for example, ‘-Q .16’.
107 -r recursion_depth, --recursion-depth recursion_depth
109 Specifies the recursion depth past which RGBASM will assume being
110 in an infinite loop. The default is 64.
111 -V, --version
113 Print the version of the program and exit.
114 -v, --verbose
116 Be verbose.
117 -W warning, --warning warning
119 Set warning flag warning. A warning message will be printed if
120 warning is an unknown warning flag. See the DIAGNOSTICS section
121 for a list of warnings.
122 -w Disable all warning output, even when turned into errors.
124
126 Warnings are diagnostic messages that indicate possibly erroneous behav‐
127 ior that does not necessarily compromise the assembling process. The
128 following options alter the way warnings are processed.
129 -Werror
131 Make all warnings into errors.
132 -Werror=
134 Make the specified warning into an error. A warning's name is
135 appended (example: -Werror=obsolete), and this warning is implic‐
136 itly enabled and turned into an error. This is an error if used
137 with a meta warning, such as -Werror=all.
138 The following warnings are “meta” warnings, that enable a collection of
140 other warnings. If a specific warning is toggled via a meta flag and a
141 specific one, the more specific one takes priority. The position on the
142 command-line acts as a tie breaker, the last one taking effect.
143 -Wall This enables warnings that are likely to indicate an error or un‐
145 desired behavior, and that can easily be fixed.
146 -Wextra
148 This enables extra warnings that are less likely to pose a prob‐
149 lem, but that may still be wanted.
150 -Weverything
152 Enables literally every warning.
153 The following warnings are actual warning flags; with each description,
155 the corresponding warning flag is included. Note that each of these flag
156 also has a negation (for example, -Wcharmap-redef enables the warning
157 that -Wno-charmap-redef disables). Only the non-default flag is listed
158 here. Ignoring the “no-” prefix, entries are listed alphabetically.
159 -Wno-assert
161 Warn when WARN-type assertions fail. (See “Aborting the assembly
162 process” in rgbasm(5) for ASSERT).
163 -Wbackwards-for
165 Warn when FOR loops have their start and stop values switched ac‐
166 cording to the step value. This warning is enabled by -Wall.
167 -Wbuiltin-args
169 Warn about incorrect arguments to built-in functions, such as
170 STRSUB() with indexes outside of the string's bounds. This warn‐
171 ing is enabled by -Wall.
172 -Wcharmap-redef
174 Warn when re-defining a charmap mapping. This warning is enabled
175 by -Wall.
176 -Wdiv Warn when dividing the smallest negative integer (-2**31) by -1,
178 which yields itself due to integer overflow.
179 -Wempty-macro-arg
181 Warn when a macro argument is empty. This warning is enabled by
182 -Wextra.
183 -Wempty-strrpl
185 Warn when STRRPL() is called with an empty string as its second
186 argument (the substring to replace). This warning is enabled by
187 -Wall.
188 -Wlarge-constant
190 Warn when a constant too large to fit in a signed 32-bit integer
191 is encountered. This warning is enabled by -Wall.
192 -Wlong-string
194 Warn when a string too long to fit in internal buffers is encoun‐
195 tered. This warning is enabled by -Wall.
196 -Wmacro-shift
198 Warn when shifting macro arguments past their limits. This warn‐
199 ing is enabled by -Wextra.
200 -Wno-obsolete
202 Warn when obsolete constructs such as the _PI constant or PRINTT
203 directive are encountered.
204 -Wnumeric-string=
206 Warn when a multi-character string is treated as a number.
207 -Wnumeric-string=0 or -Wno-numeric-string disables this warning.
208 -Wnumeric-string=1 or just -Wnumeric-string warns about strings
209 longer than four characters, since four or fewer characters fit
210 within a 32-bit integer. -Wnumeric-string=2 warns about any
211 multi-character string.
212 -Wshift
214 Warn when shifting right a negative value. Use a division by
215 2**N instead.
216 -Wshift-amount
218 Warn when a shift's operand is negative or greater than 32.
219 -Wtruncation=
221 Warn when an implicit truncation (for example, db to an 8-bit
222 value) loses some bits. -Wtruncation=0 or -Wno-truncation dis‐
223 ables this warning. -Wtruncation=1 warns when an N-bit value's
224 absolute value is 2**N or greater. -Wtruncation=2 or just
225 -Wtruncation also warns when an N-bit value is less than
226 -2**(N-1), which will not fit in two's complement encoding.
227 -Wunmapped-char=
229 Warn when a character goes through charmap conversion but has no
230 defined mapping. -Wunmapped-char=0 or -Wunmapped-char disables
231 this warning. -Wunmapped-char=1 or just -Wunmapped-char only
232 warns if the active charmap is not empty. -Wunmapped-char=2
233 warns if the active charmap is empty, and/or is not the default
234 charmap ‘main’.
235 -Wno-user
237 Warn when the WARN built-in is executed. (See “Aborting the
238 assembly process” in rgbasm(5) for WARN).
239
241 You can assemble a source file in two ways.
242 Straightforward way:
244 $ rgbasm -o bar.o foo.asm
245 Pipes way:
247 $ cat foo.asm | rgbasm -o bar.o -
248 $ rgbasm -o bar.o - < foo.asm
249 The resulting object file is not yet a usable ROM image—it must first be
251 run through rgblink(1) and then rgbfix(1).
252
254 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
255
257 rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
258
260 rgbasm was originally written by Carsten Sørensen as part of the ASMotor
261 package, and was later packaged in RGBDS by Justin Lloyd. It is now
262 maintained by a number of contributors at https://github.com/gbdev/rgbds
263BSD March 28, 2021 BSD