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
22             defaults 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
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
57     -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
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
117             undesired 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, -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
132     -Wno-assert
133             Warns when WARN-type assertions fail. (See “Aborting the assembly
134             process” in rgbasm(5) for ASSERT).
135
136     -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
141     -Wcharmap-redef
142             Warn when re-defining a charmap mapping.  This warning is enabled
143             by -Wall.
144
145     -Wdiv   Warn when dividing the smallest negative integer by -1, which
146             yields itself due to integer overflow.
147
148     -Wempty-entry
149             Warn when an empty entry is encountered in a db, dw, dl list.
150             This warning is enabled by -Wextra.
151
152     -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
156     -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
160     -Wno-obsolete
161             Warn when obsolete constructs such as the jp [hl] instruction or
162             HOME section type are encountered.
163
164     -Wshift
165             Warn when shifting right a negative value.  Use a division by 2^N
166             instead.
167
168     -Wshift-amount
169             Warn when a shift's operand is negative or greater than 32.
170
171     -Wno-truncation
172             Warn when an implicit truncation (for example, db) loses some
173             bits.
174
175     -Wno-user
176             Warn when the WARN built-in is executed. (See “Aborting the
177             assembly process” in rgbasm(5) for WARN).
178

EXAMPLES

180     You can assemble a source file in two ways.
181
182     Straightforward way:
183           $ rgbasm -o bar.o foo.asm
184
185     Pipes way:
186           $ cat foo.asm | rgbasm -o bar.o -
187           $ rgbasm -o bar.o - < foo.asm
188
189     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

BUGS

193     Please report bugs on GitHub:
194           https://github.com/gbdev/rgbds/issues.
195

SEE ALSO

197     rgbasm(5), rgbfix(1), rgblink(1), rgbds(5), rgbds(7), gbz80(7)
198

HISTORY

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
204
205BSD                              July 8, 2019                              BSD
Impressum