1.\" 2.\" This file is part of RGBDS. 3.\" 4.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors. 5.\" 6.\" SPDX-License-Identifier: MIT 7.\" 8.Dd March 28, 2021 9.Dt RGBASM 1 10.Os 11.Sh NAME 12.Nm rgbasm 13.Nd Game Boy assembler 14.Sh SYNOPSIS 15.Nm 16.Op Fl EhLVvw 17.Op Fl b Ar chars 18.Op Fl D Ar name Ns Op = Ns Ar value 19.Op Fl g Ar chars 20.Op Fl i Ar path 21.Op Fl M Ar depend_file 22.Op Fl MG 23.Op Fl MP 24.Op Fl MT Ar target_file 25.Op Fl MQ Ar target_file 26.Op Fl o Ar out_file 27.Op Fl p Ar pad_value 28.Op Fl r Ar recursion_depth 29.Op Fl W Ar warning 30.Ar 31.Sh DESCRIPTION 32The 33.Nm 34program creates an RGB object file from an assembly source file. 35The input 36.Ar file 37can be a file path, or 38.Cm \- 39denoting 40.Cm stdin . 41.Pp 42Note that options can be abbreviated as long as the abbreviation is unambiguous: 43.Fl Fl verb 44is 45.Fl Fl verbose , 46but 47.Fl Fl ver 48is invalid because it could also be 49.Fl Fl version . 50The arguments are as follows: 51.Bl -tag -width Ds 52.It Fl b Ar chars , Fl Fl binary-digits Ar chars 53Change the two characters used for binary constants. 54The defaults are 01. 55.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc 56Add a string symbol to the compiled source code. 57This is equivalent to 58.Ql Ar name Ic EQUS \(dq Ns Ar value Ns \(dq 59in code, or 60.Ql Ar name Ic EQUS \(dq1\(dq 61if 62.Ar value 63is not specified. 64.It Fl E , Fl Fl export-all 65Export all labels, including unreferenced and local labels. 66.It Fl g Ar chars , Fl Fl gfx-chars Ar chars 67Change the four characters used for gfx constants. 68The defaults are 0123. 69.It Fl h , Fl Fl halt-without-nop 70By default, 71.Nm 72inserts a 73.Ic nop 74instruction immediately after any 75.Ic halt 76instruction. 77The 78.Fl h 79option disables this behavior. 80.It Fl i Ar path , Fl Fl include Ar path 81Add an include path. 82.It Fl L , Fl Fl preserve-ld 83Disable the optimization that turns loads of the form 84.Ic LD [$FF00+n8],A 85into the opcode 86.Ic LDH [$FF00+n8],A 87in order to have full control of the result in the final ROM. 88.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file 89Print 90.Xr make 1 91dependencies to 92.Ar depend_file . 93.It Fl MG 94To be used in conjunction with 95.Fl M . 96This makes 97.Nm 98assume that missing files are auto-generated: when 99.Ic INCLUDE 100or 101.Ic INCBIN 102is attempted on a non-existent file, it is added as a dependency, then 103.Nm 104exits normally instead of erroring out. 105This feature is used in automatic updating of makefiles. 106.It Fl MP 107When enabled, this causes a phony target to be added for each dependency other than the main file. 108This prevents 109.Xr make 1 110from erroring out when dependency files are deleted. 111.It Fl MT Ar target_file 112Add a target to the rules emitted by 113.Fl M . 114The exact string provided will be written, including spaces and special characters. 115.Dl Fl MT No fileA Fl MT No fileB 116is equivalent to 117.Dl Fl MT No 'fileA fileB' . 118If neither this nor 119.Fl MQ 120is specified, the output file name is used. 121.It Fl MQ Ar target_file 122Same as 123.Fl MT , 124but additionally escapes any special 125.Xr make 1 126characters, essentially 127.Sq $ . 128.It Fl o Ar out_file , Fl Fl output Ar out_file 129Write an object file to the given filename. 130.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value 131When padding an image, pad with this value. 132The default is 0x00. 133.It Fl r Ar recursion_depth , Fl Fl recursion-depth Ar recursion_depth 134Specifies the recursion depth at which RGBASM will assume being in an infinite loop. 135.It Fl V , Fl Fl version 136Print the version of the program and exit. 137.It Fl v , Fl Fl verbose 138Be verbose. 139.It Fl W Ar warning , Fl Fl warning Ar warning 140Set warning flag 141.Ar warning . 142A warning message will be printed if 143.Ar warning 144is an unknown warning flag. 145See the 146.Sx DIAGNOSTICS 147section for a list of warnings. 148.It Fl w 149Disable all warning output, even when turned into errors. 150.El 151.Sh DIAGNOSTICS 152Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process. 153The following options alter the way warnings are processed. 154.Bl -tag -width Ds 155.It Fl Werror 156Make all warnings into errors. 157.It Fl Werror= 158Make the specified warning into an error. 159A warning's name is appended 160.Pq example: Fl Werror=obsolete , 161and this warning is implicitly enabled and turned into an error. 162This is an error if used with a meta warning, such as 163.Fl Werror=all . 164.El 165.Pp 166The following warnings are 167.Dq meta 168warnings, that enable a collection of other warnings. 169If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority. 170The position on the command-line acts as a tie breaker, the last one taking effect. 171.Bl -tag -width Ds 172.It Fl Wall 173This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed. 174.It Fl Wextra 175This enables extra warnings that are less likely to pose a problem, but that may still be wanted. 176.It Fl Weverything 177Enables literally every warning. 178.El 179.Pp 180The following warnings are actual warning flags; with each description, the corresponding warning flag is included. 181Note that each of these flag also has a negation (for example, 182.Fl Wcharmap-redef 183enables the warning that 184.Fl Wno-charmap-redef 185disables). 186Only the non-default flag is listed here. 187Ignoring the 188.Dq no- 189prefix, entries are listed alphabetically. 190.Bl -tag -width Ds 191.It Fl Wno-assert 192Warn when 193.Ic WARN Ns No -type 194assertions fail. (See 195.Dq Aborting the assembly process 196in 197.Xr rgbasm 5 198for 199.Ic ASSERT ) . 200.It Fl Wbackwards-for 201Warn when 202.Ic FOR 203loops have their start and stop values switched according to the step value. 204This warning is enabled by 205.Fl Wall . 206.It Fl Wbuiltin-args 207Warn about incorrect arguments to built-in functions, such as 208.Fn STRSUB 209with indexes outside of the string's bounds. 210This warning is enabled by 211.Fl Wall . 212.It Fl Wcharmap-redef 213Warn when re-defining a charmap mapping. 214This warning is enabled by 215.Fl Wall . 216.It Fl Wdiv 217Warn when dividing the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow. 218.It Fl Wempty-macro-arg 219Warn when a macro argument is empty. 220This warning is enabled by 221.Fl Wextra . 222.It Fl Wempty-strrpl 223Warn when 224.Fn STRRPL 225is called with an empty string as its second argument (the substring to replace). 226This warning is enabled by 227.Fl Wall . 228.It Fl Wlarge-constant 229Warn when a constant too large to fit in a signed 32-bit integer is encountered. 230This warning is enabled by 231.Fl Wall . 232.It Fl Wlong-string 233Warn when a string too long to fit in internal buffers is encountered. 234This warning is enabled by 235.Fl Wall . 236.It Fl Wmacro-shift 237Warn when shifting macro arguments past their limits. 238This warning is enabled by 239.Fl Wextra . 240.It Fl Wno-obsolete 241Warn when obsolete constructs such as the 242.Ic _PI 243constant or 244.Ic PRINTT 245directive are encountered. 246.It Fl Wnumeric-string= 247Warn when a multi-character string is treated as a number. 248.Fl Wnumeric-string=0 249or 250.Fl Wno-numeric-string 251disables this warning. 252.Fl Wnumeric-string=1 253or just 254.Fl Wnumeric-string 255warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer. 256.Fl Wnumeric-string=2 257warns about any multi-character string. 258.It Fl Wshift 259Warn when shifting right a negative value. 260Use a division by 2**N instead. 261.It Fl Wshift-amount 262Warn when a shift's operand is negative or greater than 32. 263.It Fl Wtruncation= 264Warn when an implicit truncation (for example, 265.Ic db 266to an 8-bit value) loses some bits. 267.Fl Wtruncation=0 268or 269.Fl Wno-truncation 270disables this warning. 271.Fl Wtruncation=1 272warns when an N-bit value's absolute value is 2**N or greater. 273.Fl Wtruncation=2 274or just 275.Fl Wtruncation 276also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding. 277.It Fl Wno-user 278Warn when the 279.Ic WARN 280built-in is executed. (See 281.Dq Aborting the assembly process 282in 283.Xr rgbasm 5 284for 285.Ic WARN ) . 286.El 287.Sh EXAMPLES 288You can assemble a source file in two ways. 289.Pp 290Straightforward way: 291.Dl $ rgbasm -o bar.o foo.asm 292.Pp 293Pipes way: 294.Dl $ cat foo.asm | rgbasm -o bar.o - 295.Dl $ rgbasm -o bar.o - < foo.asm 296.Pp 297The resulting object file is not yet a usable ROM image\(emit must first be run through 298.Xr rgblink 1 299and then 300.Xr rgbfix 1 . 301.Sh BUGS 302Please report bugs on 303.Lk https://github.com/gbdev/rgbds/issues GitHub . 304.Sh SEE ALSO 305.Xr rgbasm 5 , 306.Xr rgbfix 1 , 307.Xr rgblink 1 , 308.Xr rgbds 5 , 309.Xr rgbds 7 , 310.Xr gbz80 7 311.Sh HISTORY 312.Nm 313was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd. 314It is now maintained by a number of contributors at 315.Lk https://github.com/gbdev/rgbds . 316