shithub: rgbds

ref: cdd82009369ff348ccce7b40267c5079c8439679
dir: /src/asm/rgbasm.1/

View raw version
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd July 8, 2019
.Dt RGBASM 1
.Os RGBDS Manual
.Sh NAME
.Nm rgbasm
.Nd Game Boy assembler
.Sh SYNOPSIS
.Nm rgbasm
.Op Fl EhLVvw
.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 dependfile
.Op Fl o Ar outfile
.Op Fl p Ar pad_value
.Op Fl r Ar recursion_depth
.Ar file
.Sh DESCRIPTION
The
.Nm
program creates an object file from an assembly source file.
The input
.Ar file
can be a file path, or
.Cm \-
denoting
.Cm stdin .
Its arguments are as follows:
.Bl -tag -width Ds
.It Fl b Ar chars
Change the two characters used for binary constants.
The defaults are 01.
.It Fl D Ar name Ns Op = Ns Ar value
Add string symbol to the compiled source code. This is equivalent to
.Ar name
.Cm EQUS
.Qq Ar "value"
in code. If a value is not specified, a value of 1 is given.
.It Fl E
Export all labels, including unreferenced and local labels.
.It Fl g Ar chars
Change the four characters used for binary constants.
The defaults are 0123.
.It Fl h
By default,
.Nm
inserts a
.Sq nop
instruction immediately after any
.Sq halt
instruction.
The
.Fl h
option disables this behavior.
.It Fl i Ar path
Add an include path.
.It Fl L
Disable the optimization that turns loads of the form
.Sy LD [$FF00+n8],A
into the opcode
.Sy LDH [$FF00+n8],A
in order to have full control of the result in the final ROM.
.It Fl M Ar dependfile
Print
.Xr make 1
dependencies to
.Ar dependfile .
.It Fl o Ar outfile
Write an object file to the given filename.
.It Fl p Ar pad_value
When padding an image, pad with this value.
The default is 0x00.
.It Fl r Ar recursion_depth
Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
.It Fl V
Print the version of the program and exit.
.It Fl v
Be verbose.
.It Fl w
Disable warning output.
.El
.Sh EXAMPLES
You can assemble a source file in two ways.
Straight forward way:
.Pp
.Bd -literal -offset indent
$ rgbasm -o bar.o foo.asm
.Ed
.Pp
Pipes way:
.Pp
.Bd -literal -offset indent
$ cat foo.asm | rgbasm -o bar.o -
$ rgbasm -o bar.o - < foo.asm
.Ed
.Pp
The resulting object file is not yet a usable ROM image \(em it must first be
run through
.Xr rgblink 1
and
.Xr rgbfix 1 .
.Sh SEE ALSO
.Xr rgbasm 5 ,
.Xr rgbfix 1 ,
.Xr rgblink 1 ,
.Xr rgbds 5 ,
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package,
and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a
number of contributors at
.Lk https://github.com/rednex/rgbds .