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

NAME

4     rgbasm — Game Boy assembler
5

SYNOPSIS

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

DESCRIPTION

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
17     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
21     -b chars, --binary-digits chars
22             Change the two characters used for binary constants.  The de‐
23             faults are 01.
24
25     -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
30     -E, --export-all
31             Export all labels, including unreferenced and local labels.
32
33     -g chars, --gfx-chars chars
34             Change the four characters used for gfx constants.  The defaults
35             are 0123.
36
37     -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
43     -h, --halt-without-nop
44             Disables inserting a nop instruction immediately after any halt
45             instruction.
46
47     -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
54     -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
60     -l, --auto-ldh
61             Optimize loads of the form LD [$FF00+n8],A into the opcode LDH
62             [$FF00+n8],A.
63
64     -M depend_file, --dependfile depend_file
65             Print make(1) dependencies to depend_file.
66
67     -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
74     -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
78     -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
87     -MQ target_file
88             Same as -MT, but additionally escapes any special make(1) charac‐
89             ters, essentially ‘$’.
90
91     -o out_file, --output out_file
92             Write an object file to the given filename.
93
94     -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
98     -p pad_value, --pad-value pad_value
99             When padding an image, pad with this value.  The default is 0x00.
100
101     -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
108     -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
112     -V, --version
113             Print the version of the program and exit.
114
115     -v, --verbose
116             Be verbose.
117
118     -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
123     -w      Disable all warning output, even when turned into errors.
124

DIAGNOSTICS

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
130     -Werror
131             Make all warnings into errors.
132
133     -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
139     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
144     -Wall   This enables warnings that are likely to indicate an error or un‐
145             desired behavior, and that can easily be fixed.
146
147     -Wextra
148             This enables extra warnings that are less likely to pose a prob‐
149             lem, but that may still be wanted.
150
151     -Weverything
152             Enables literally every warning.
153
154     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
160     -Wno-assert
161             Warn when WARN-type assertions fail. (See “Aborting the assembly
162             process” in rgbasm(5) for ASSERT).
163
164     -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
168     -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
173     -Wcharmap-redef
174             Warn when re-defining a charmap mapping.  This warning is enabled
175             by -Wall.
176
177     -Wdiv   Warn when dividing the smallest negative integer (-2**31) by -1,
178             which yields itself due to integer overflow.
179
180     -Wempty-macro-arg
181             Warn when a macro argument is empty.  This warning is enabled by
182             -Wextra.
183
184     -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
189     -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
193     -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
197     -Wmacro-shift
198             Warn when shifting macro arguments past their limits.  This warn‐
199             ing is enabled by -Wextra.
200
201     -Wno-obsolete
202             Warn when obsolete constructs such as the _PI constant or PRINTT
203             directive are encountered.
204
205     -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
213     -Wshift
214             Warn when shifting right a negative value.  Use a division by
215             2**N instead.
216
217     -Wshift-amount
218             Warn when a shift's operand is negative or greater than 32.
219
220     -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
228     -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
236     -Wno-user
237             Warn when the WARN built-in is executed. (See “Aborting the
238             assembly process” in rgbasm(5) for WARN).
239

EXAMPLES

241     You can assemble a source file in two ways.
242
243     Straightforward way:
244           $ rgbasm -o bar.o foo.asm
245
246     Pipes way:
247           $ cat foo.asm | rgbasm -o bar.o -
248           $ rgbasm -o bar.o - < foo.asm
249
250     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

BUGS

254     Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
255

SEE ALSO

257     rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
258

HISTORY

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
263
264BSD                             March 28, 2021                             BSD
Impressum