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
22 defaults 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
53 attempted on a non-existent file, it is added as a dependency,
54 then rgbasm exits normally instead of erroring out. This feature
55 is used in automatic updating of makefiles.
56 -MP When enabled, this causes a phony target to be added for each
58 dependency 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
117 undesired 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, -Wempty-entry enables the warning that
129 -Wno-empty-entry disables). Only the non-default flag is listed here.
130 Ignoring the “no-” prefix, entries are listed alphabetically.
131 -Wno-assert
133 Warns when WARN-type assertions fail. (See “Aborting the assembly
134 process” in rgbasm(5) for ASSERT).
135 -Wbuiltin-args
137 Warn about incorrect arguments to built-in functions, such as
138 STRSUB() with indexes outside of the string's bounds. This warn‐
139 ing is enabled by -Wall.
140 -Wcharmap-redef
142 Warn when re-defining a charmap mapping. This warning is enabled
143 by -Wall.
144 -Wdiv Warn when dividing the smallest negative integer by -1, which
146 yields itself due to integer overflow.
147 -Wempty-entry
149 Warn when an empty entry is encountered in a db, dw, dl list.
150 This warning is enabled by -Wextra.
151 -Wlarge-constant
153 Warn when a constant too large to fit in a signed 32-bit integer
154 is encountered. This warning is enabled by -Wall.
155 -Wlong-string
157 Warn when a string too long to fit in internal buffers is encoun‐
158 tered. This warning is enabled by -Wall.
159 -Wno-obsolete
161 Warn when obsolete constructs such as the jp [hl] instruction or
162 HOME section type are encountered.
163 -Wshift
165 Warn when shifting right a negative value. Use a division by 2^N
166 instead.
167 -Wshift-amount
169 Warn when a shift's operand is negative or greater than 32.
170 -Wno-truncation
172 Warn when an implicit truncation (for example, db) loses some
173 bits.
174 -Wno-user
176 Warn when the WARN built-in is executed. (See “Aborting the
177 assembly process” in rgbasm(5) for WARN).
178
180 You can assemble a source file in two ways.
181 Straightforward way:
183 $ rgbasm -o bar.o foo.asm
184 Pipes way:
186 $ cat foo.asm | rgbasm -o bar.o -
187 $ rgbasm -o bar.o - < foo.asm
188 The resulting object file is not yet a usable ROM image—it must first be
190 run through rgblink(1) and then rgbfix(1).
191
193 Please report bugs on GitHub:
194 https://github.com/gbdev/rgbds/issues.
195
197 rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
198
200 rgbasm was originally written by Carsten Sørensen as part of the ASMotor
201 package, and was later packaged in RGBDS by Justin Lloyd. It is now
202 maintained by a number of contributors at .:
203 https://github.com/gbdev/rgbds
204BSD July 8, 2019 BSD