-
-
Notifications
You must be signed in to change notification settings - Fork 175
/
Copy pathrgbasm.1
442 lines (442 loc) · 11.6 KB
/
rgbasm.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
.\" SPDX-License-Identifier: MIT
.\"
.Dd February 2, 2025
.Dt RGBASM 1
.Os
.Sh NAME
.Nm rgbasm
.Nd Game Boy assembler
.Sh SYNOPSIS
.Nm
.Op Fl EhVvw
.Op Fl b Ar chars
.Op Fl D Ar name Ns Op = Ns Ar value
.Op Fl g Ar chars
.Op Fl I Ar path
.Op Fl M Ar depend_file
.Op Fl MG
.Op Fl MP
.Op Fl MT Ar target_file
.Op Fl MQ Ar target_file
.Op Fl o Ar out_file
.Op Fl P Ar include_file
.Op Fl p Ar pad_value
.Op Fl Q Ar fix_precision
.Op Fl r Ar recursion_depth
.Op Fl s Ar features Ns : Ns Ar state_file
.Op Fl W Ar warning
.Op Fl X Ar max_errors
.Ar asmfile
.Sh DESCRIPTION
The
.Nm
program creates an RGB object file from an assembly source file.
The object file format is documented in
.Xr rgbds 5 .
.Pp
The input
.Ar asmfile
can be a path to a file, or
.Cm \-
to read from standard input.
.Pp
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl \-verb
is
.Fl \-verbose ,
but
.Fl \-ver
is invalid because it could also be
.Fl \-version .
The arguments are as follows:
.Bl -tag -width Ds
.It Fl b Ar chars , Fl \-binary-digits Ar chars
Change the two characters used for binary constants.
The defaults are 01.
.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl \-define Ar name Ns Oo = Ns Ar value Oc
Add a string symbol to the compiled source code.
This is equivalent to
.Ql Ar name Ic EQUS No \(dq Ns Ar value Ns \(dq
in code, or
.Ql Ar name Ic EQUS No \(dq1\(dq
if
.Ar value
is not specified.
.It Fl E , Fl \-export-all
Export all labels, including unreferenced and local labels.
.It Fl g Ar chars , Fl \-gfx-chars Ar chars
Change the four characters used for gfx constants.
The defaults are 0123.
.It Fl h , Fl \-help
Print help text for the program and exit.
.It Fl I Ar path , Fl \-include Ar path
Add a new
.Dq include path ;
.Ar path
must point to a directory.
When a
.Ic INCLUDE
.Pq including the implicit one from Fl P
or
.Ic INCBIN
is attempted,
.Nm
first looks up the provided path from its working directory; if this fails, it tries again from each of the
.Dq include path
directories, in the order they were provided.
.It Fl M Ar depend_file , Fl \-dependfile Ar depend_file
Write
.Xr make 1
dependencies to
.Ar depend_file .
.It Fl MG
To be used in conjunction with
.Fl M .
This makes
.Nm
assume that missing files are auto-generated: when
.Ic INCLUDE
.Pq including the implicit one from Fl P
or
.Ic INCBIN
is attempted on a non-existent file, it is added as a dependency, then
.Nm
exits normally instead of erroring out.
This feature is used in automatic updating of makefiles.
.It Fl MP
When enabled, this causes a phony target to be added for each dependency other than the main file.
This prevents
.Xr make 1
from erroring out when dependency files are deleted.
.It Fl MT Ar target_file
Add a target to the rules emitted by
.Fl M .
The exact string provided will be written, including spaces and special characters.
.Dl Fl MT No fileA Fl MT No fileB
is equivalent to
.Dl Fl MT No 'fileA fileB' .
If neither this nor
.Fl MQ
is specified, the output file name is used.
.It Fl MQ Ar target_file
Same as
.Fl MT ,
but additionally escapes any special
.Xr make 1
characters, essentially
.Sq $ .
.It Fl o Ar out_file , Fl \-output Ar out_file
Write an object file to the given filename.
.It Fl P Ar include_file , Fl \-preinclude Ar include_file
Pre-include a file.
This acts as if a
.Ql Ic INCLUDE Qq Ar include_file
was read before the input
.Ar asmfile .
.It Fl p Ar pad_value , Fl \-pad-value Ar pad_value
Use this as the value for
.Ic DS
directives in ROM sections, unless overridden.
The default is 0x00.
.It Fl Q Ar fix_precision , Fl \-q-precision Ar fix_precision
Use this as the precision of fixed-point numbers after the decimal point, unless they specify their own precision.
The default is 16, so fixed-point numbers are Q16.16 (since they are 32-bit integers).
The argument may start with a
.Ql \&.
to match the Q notation, for example,
.Ql Fl Q Ar .16 .
.It Fl r Ar recursion_depth , Fl \-recursion-depth Ar recursion_depth
Specifies the recursion depth past which
.Nm
will assume being in an infinite loop.
The default is 64.
.It Fl s Ar features Ns : Ns Ar state_file , Fl \-state Ar features Ns : Ns Ar state_file
Write the specified
.Ar features
to
.Ar state_file ,
based on the final state of
.Nm
at the end of its input.
The expected
.Ar features
are a comma-separated subset of the following:
.Bl -tag -width Ds
.It Cm equ
Write all numeric constants as
.Ql Ic def Ar name Ic equ Ar value .
.It Cm var
Write all variables as
.Ql Ic def Ar name Ic = Ar value .
.It Cm equs
Write all string constants as
.Ql Ic def Ar name Ic equs Qq Ar value .
.It Cm char
Write all characters as
.Ql Ic charmap Ar name , Ar value .
.It Cm macro
Write all macros as
.Ql Ic macro Ar name No ... Ic endm .
.It Cm all
Acts like
.Cm equ,var,equs,char,macro .
.El
.Pp
This flag may be specified multiple times with different feature subsets to write them to different files (see
.Sx EXAMPLES
below).
.It Fl V , Fl \-version
Print the version of the program and exit.
.It Fl v , Fl \-verbose
Be verbose.
.It Fl W Ar warning , Fl \-warning Ar warning
Set warning flag
.Ar warning .
A warning message will be printed if
.Ar warning
is an unknown warning flag.
See the
.Sx DIAGNOSTICS
section for a list of warnings.
.It Fl w
Disable all warning output, even when turned into errors.
.It Fl X Ar max_errors , Fl \-max-errors Ar max_errors
If more than this number of errors (not warnings) occur, then abort the assembly process;
.Fl X Ar 0
disables this behavior.
The default is 100 if
.Nm
is printing errors to a terminal, and 0 otherwise.
.El
.Sh DIAGNOSTICS
Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process.
The following options alter the way warnings are processed.
.Bl -tag -width Ds
.It Fl Werror
Make all warnings into errors.
This can be negated as
.Fl Wno-error
to prevent turning all warnings into errors.
.It Fl Werror=
Make the specified warning or meta warning into an error.
A warning's name is appended
.Pq example: Fl Werror=obsolete ,
and this warning is implicitly enabled and turned into an error.
This can be negated as
.Fl Wno-error=
to prevent turning a specified warning into an error, even if
.Fl Werror
is in effect.
.El
.Pp
The following warnings are
.Dq meta
warnings, that enable a collection of other warnings.
If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority.
The position on the command-line acts as a tie breaker, the last one taking effect.
.Bl -tag -width Ds
.It Fl Wall
This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
.It Fl Wextra
This enables extra warnings that are less likely to pose a problem, but that may still be wanted.
.It Fl Weverything
Enables literally every warning.
.El
.Pp
The following warnings are actual warning flags; with each description, the corresponding warning flag is included.
Note that each of these flag also has a negation (for example,
.Fl Wcharmap-redef
enables the warning that
.Fl Wno-charmap-redef
disables; and
.Fl Wall
enables every warning that
.Fl Wno-all
disables).
Only the non-default flag is listed here.
Ignoring the
.Dq no-
prefix, entries are listed alphabetically.
.Bl -tag -width Ds
.It Fl Wno-assert
Warn when
.Ic WARN Ns No -type
assertions fail. (See
.Dq Aborting the assembly process
in
.Xr rgbasm 5
for
.Ic ASSERT ) .
.It Fl Wbackwards-for
Warn when
.Ic FOR
loops have their start and stop values switched according to the step value.
This warning is enabled by
.Fl Wall .
.It Fl Wbuiltin-args
Warn about incorrect arguments to built-in functions, such as
.Fn STRSUB
with indexes outside of the string's bounds.
This warning is enabled by
.Fl Wall .
.It Fl Wcharmap-redef
Warn when re-defining a charmap mapping.
This warning is enabled by
.Fl Wall .
.It Fl Wdiv
Warn when dividing the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow.
.It Fl Wempty-macro-arg
Warn when a macro argument is empty.
This warning is enabled by
.Fl Wextra .
.It Fl Wempty-strrpl
Warn when
.Fn STRRPL
is called with an empty string as its second argument (the substring to replace).
This warning is enabled by
.Fl Wall .
.It Fl Wlarge-constant
Warn when a constant too large to fit in a signed 32-bit integer is encountered.
This warning is enabled by
.Fl Wall .
.It Fl Wmacro-shift
Warn when shifting macro arguments past their limits.
This warning is enabled by
.Fl Wextra .
.It Fl Wno-nested-comment
Warn when the block comment start sequence
.Ql /*
is found inside of a block comment.
Block comments cannot be nested, so the first
.Ql */
will end the whole comment.
.It Fl Wno-obsolete
Warn when obsolete constructs such as the
.Ic _PI
constant or
.Ic PRINTT
directive are encountered.
.It Fl Wnumeric-string=
Warn when a multi-character string is treated as a number.
.Fl Wnumeric-string=0
or
.Fl Wno-numeric-string
disables this warning.
.Fl Wnumeric-string=1
or just
.Fl Wnumeric-string
warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer.
.Fl Wnumeric-string=2
warns about any multi-character string.
.It Fl Wpurge=
Warn when purging symbols which are likely to have been necessary.
.Fl Wpurge=0
or
.Fl Wno-purge
disables this warning.
.Fl Wpurge=1
or just
.Fl Wpurge
warns when purging any exported symbol (regardless of type).
.Fl Wpurge=2
also warns when purging any label (even if not exported).
.It Fl Wshift
Warn when shifting right a negative value.
Use a division by 2**N instead.
.It Fl Wshift-amount
Warn when a shift's operand is negative or greater than 32.
.It Fl Wtruncation=
Warn when an implicit truncation (for example,
.Ic db
to an 8-bit value) loses some bits.
.Fl Wtruncation=0
or
.Fl Wno-truncation
disables this warning.
.Fl Wtruncation=1
warns when an N-bit value is 2**N or greater, or less than -2**N.
.Fl Wtruncation=2
or just
.Fl Wtruncation
also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding.
.It Fl Wunmapped-char=
Warn when a character goes through charmap conversion but has no defined mapping.
.Fl Wunmapped-char=0
or
.Fl Wno-unmapped-char
disables this warning.
.Fl Wunmapped-char=1
or just
.Fl Wunmapped-char
only warns if the active charmap is not empty.
.Fl Wunmapped-char=2
warns if the active charmap is empty, and/or is not the default charmap
.Sq main .
.It Fl Wunmatched-directive
Warn when a
.Ic PUSHC , PUSHO ,
or
.Ic PUSHS
directive does not have a corresponding
.Ic POPC , POPO ,
or
.Ic POPS .
This warning is enabled by
.Fl Wextra .
.It Fl Wunterminated-load
Warn when a
.Ic LOAD
block is not terminated by an
.Ic ENDL .
This warning is enabled by
.Fl Wextra .
.It Fl Wno-user
Warn when the
.Ic WARN
built-in is executed. (See
.Dq Aborting the assembly process
in
.Xr rgbasm 5
for
.Ic WARN ) .
.El
.Sh EXAMPLES
You can assemble a source file in two ways.
.Pp
Straightforward way:
.Dl $ rgbasm -o bar.o foo.asm
.Pp
Pipes way:
.Dl $ cat foo.asm | rgbasm -o bar.o -
.Dl $ rgbasm -o bar.o - < foo.asm
.Pp
The resulting object file is not yet a usable ROM image\(emit must first be run through
.Xr rgblink 1
and then
.Xr rgbfix 1 .
.Pp
Writing the final assembler state to a file:
.Dl $ rgbasm -s all:state.dump.asm foo.asm
.Pp
Or to multiple files:
.Dl $ rgbasm -s equ,var:numbers.dump.asm -s equs:strings.dump.asm foo.asm
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 5 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbgfx 1 ,
.Xr gbz80 7 ,
.Xr rgbasm-old 5 ,
.Xr rgbds 5 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally written by
.An Carsten S\(/orensen
as part of the ASMotor package, and was later repackaged in RGBDS by
.An Justin Lloyd .
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .