ref: b53c945f0544af06f47b78a1ba30607c8f3e569b
parent: 7293da9084274df88db06f7c321e02333c6ca9fa
author: bentley <[email protected]>
date: Sat Feb 27 14:19:50 EST 2010
Man pages!
--- a/Makefile
+++ b/Makefile
@@ -2,8 +2,6 @@
CFLAGS+=-Wall -Iinclude -Iinclude/asm/gameboy -DLOCALVERSION=\"$(localversion)\" -g -std=c99 -D_POSIX_C_SOURCE=200112L
-all:
-
yacc_pre := \
src/asm/yaccprt1.y\
src/asm/gameboy/yaccprt2.y\
@@ -48,6 +46,7 @@
rm -rf rgblink $(rgblink_obj)
rm -rf rgbfix $(rgbfix_obj)
rm -rf src/asm/asmy.c
+ rm -rf rgbasm.0 rgbfix.0 rgblib.0 rgblink.0
rgbasm: $(rgbasm_obj)
${CC} $(CFLAGS) -o $@ $(rgbasm_obj) -lm@@ -69,3 +68,17 @@
src/asm/asmy.y: $(yacc_pre)
cat $(yacc_pre) > $@
+
+man: rgbasm.0 rgbfix.0 rgblib.0 rgblink.0
+
+rgbasm.0: man/rgbasm.1
+ nroff -mdoc man/rgbasm.1 > rgbasm.0
+
+rgbfix.0: man/rgbfix.1
+ nroff -mdoc man/rgbfix.1 > rgbfix.0
+
+rgblib.0: man/rgblib.1
+ nroff -mdoc man/rgblib.1 > rgblib.0
+
+rgblink.0: man/rgblink.1
+ nroff -mdoc man/rgblink.1 > rgblink.0
--- /dev/null
+++ b/man/rgbasm.1
@@ -1,0 +1,61 @@
+.Dd $\&Mdocdate$
+.Dt RGBASM 1
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgbasm
+.Nd Game Boy assembler
+.\" SECTION
+.Sh SYNOPSIS
+.Nm rgbasm
+.Op Fl b Ar chars
+.Op Fl g Ar chars
+.Op Fl i Ar path
+.Op Fl o Ar outfile
+.Op Fl p Ar pad_value
+.Ar file
+.\" SECTION
+.Sh DESCRIPTION
+The
+.Nm
+program creates an object file from an assembly source file. Its arguments
+are as follows:
+.Bl -tag -width Ds
+.\" ITEM
+.It Fl b Ar chars
+Change the two characters used for binary constants. The defaults are 01.
+.\" ITEM
+.It Fl g Ar chars
+Change the four characters used for binary constants. The defaults are 0123.
+.\" ITEM
+.It Fl i Ar path
+Add an include path.
+.\" ITEM
+.It Fl o Ar outfile
+Write an object file to the given filename.
+.\" ITEM
+.It Fl p Ar pad_value
+When padding an image, pad with this value. The default is 0x00.
+.El
+.\" SECTION
+.Sh EXAMPLES
+Assembling a basic source file is simple:
+.Pp
+.D1 $ rgbasm \-o bar.o foo.asm
+.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 .
+.\" SECTION
+.Sh SEE ALSO
+.Xr rgbds 7 ,
+.Xr rgbfix 1 ,
+.Xr rgblib 1 ,
+.Xr rgblink 1 ,
+.Xr gbz80 7
+.\" SECTION
+.Sh HISTORY
+.Nm
+was originally written by Carsten Sørensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
--- /dev/null
+++ b/man/rgbfix.1
@@ -1,0 +1,111 @@
+.Dd $\&Mdocdate$
+.Dt RGBFIX 1
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgbfix
+.Nd Game Boy checksum fixer
+.\" SECTION
+.Sh SYNOPSIS
+.Nm rgbfix
+.Op Fl Ccdjqrsv
+.Op Fl k Ar licensee_str
+.Op Fl m Ar mbc_type
+.Op Fl p Ar pad_value
+.Op Fl r Ar ram_size
+.Op Fl t Ar title_str
+.Ar file Ns Op .gb
+.\" SECTION
+.Sh DESCRIPTION
+The
+.Nm
+program changes headers of Game Boy ROM images. It also performs other
+filetype operations, such as truncation. The arguments are as follows:
+.Bl -tag -width Ds
+.\" ITEM
+.It Fl C
+Set the Game Boy Color compatible flag: [0x143] = 0x80. This flag and the
+.Fl c
+flag are mutually exclusive.
+.\" ITEM
+.It Fl c
+Set the Game Boy Color only flag: [0x143] = 0xC0. This flag and the
+.Fl C
+flag are mutually exclusive.
+.\" ITEM
+.It Fl d
+Don't perform any changes, just pretend to for debugging.
+.\" ITEM
+.It Fl j
+Set the non-Japanese region flag: [0x14A] = 1.
+.\" ITEM
+.It Fl k Ar licensee_str
+Set the new licensee string ([0x144\(en0x145]) to a given string, truncated
+to at most two characters.
+.\" ITEM
+.It Fl m Ar mbc_type
+Set the MBC type, [0x147], to a given value from 0 to 0xFF.
+.\" ITEM
+.It Fl p Ar pad_value
+Pad the image to a valid size with a given pad value from 0 to 0xFF.
+.Nm
+will automatically pick a size from 32KiB, 64KiB, 128KiB, ..., 8192KiB and
+give a warning thereafter. The cartridge size byte ([0x148]) will be changed
+to reflect this new size.
+.\" ITEM
+.It Fl q
+Enable quiet mode, suppressing all text except errors.
+.\" ITEM
+.It Fl r Ar ram_size
+Set the RAM size, [0x149], to a given value from 0 to 0xFF.
+.\" ITEM
+.It Fl s
+Set the SGB flag: [0x146] = 3, and set the old licensee code: [0x14B] = 0x33.
+.\" ITEM
+.It Fl t Ar title
+Set the title string ([0x134\(en0x143]) to a given string, truncated to at
+most 16 characters. It is recommended to use 15 characters instead, to avoid
+clashing with the CGB flag (
+.Fl c
+or
+.Fl C Ns
+).
+.\" ITEM
+.It Fl v
+Validate the header and fix checksums: the Nintendo character area
+([0x104\(en0x133]), the header checksum ([0x14D]), and the global checksum
+([0x14E\(en0x14F]).
+.El
+.\" SECTION
+.Sh EXAMPLES
+Most values in the ROM header are only cosmetic. The bare minimum requirements
+for a workable image are checksums, the Nintendo logo, and (if needed) the
+CGB/SGB flags. It is a good idea to pad the image to a valid size as well
+("valid" meaning a multiple of 32KiB).+.Pp
+The following will make a plain, no-color Game Boy game without checking for
+a valid size:
+.Pp
+.D1 $ rgbfix \-v foo.gb
+.Pp
+The following will make a SGB-enabled, color-enabled game with a title of
+"foobar", and pad it to a multiple of 32KiB. (The Game Boy itself does not
+use the title, but some emulators or ROM managers might.)
+.Pp
+.D1 $ rgbfix \-vCs \-p 0 \-t foobar baz.gb
+.Pp
+The following will duplicate the header (sans global checksum) of the game
+"Survival Kids":
+.Pp
+.D1 $ rgbfix \-Cjsv \-k A4 \-m 0x1B \-p 0xFF \-r 3 \-t SURVIVALKIDAVKE SurvivalKids.gbc
+.\" SECTION
+.Sh SEE ALSO
+.Xr rgbds 7 ,
+.Xr rgbasm 1 ,
+.Xr rgblib 1 ,
+.Xr rgblink 1 ,
+.Xr gbz80 7
+.\" SECTION
+.Sh HISTORY
+.Nm
+was originally released by Carsten Sørensen as a standalone program called
+gbfix. It was later integrated with the ASMotor package, which became RGBDS.
--- /dev/null
+++ b/man/rgblib.1
@@ -1,0 +1,44 @@
+.Dd $\&Mdocdate$
+.Dt RGBLIB 1
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgblib
+.Nd Game Boy library manager
+.\" SECTION
+.Sh SYNOPSIS
+.Nm rgblib
+.Ar library
+.Op add | delete | extract | list
+.Ar module ...
+.\" SECTION
+.Sh DESCRIPTION
+The
+.Nm
+program manages libraries for use with
+.Xr rgblink 1 .
+.Bl -tag -width Ds
+.\" ITEM
+.It add
+Add the given modules to the library.
+.\" ITEM
+.It delete
+Delete the given modules from the library.
+.\" ITEM
+.It extract
+Extract the given modules from the library.
+.\" ITEM
+.It list
+List all the modules in the library.
+.El
+.\" SECTION
+.Sh SEE ALSO
+.Xr rgbds 7 ,
+.Xr rgbasm 1 ,
+.Xr rgbfix 1 ,
+.Xr rgblink 1 ,
+.Xr gbz80 7
+.\" SECTION
+.Sh HISTORY
+.Nm
+was originally released by Carsten Sørensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
--- /dev/null
+++ b/man/rgblink.1
@@ -1,0 +1,85 @@
+.Dd $\&Mdocdate$
+.Dt RGBLINK 1
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgblink
+.Nd Game Boy linker
+.\" SECTION
+.Sh SYNOPSIS
+.Nm rgblink
+.Op Fl t
+.Op Fl l Ar library
+.Op Fl m Ar mapfile
+.Op Fl n Ar symfile
+.Op Fl o Ar outfile
+.Op Fl p Ar pad_value
+.Op Fl s Ar symbol
+.Ar
+.\" SECTION
+.Sh DESCRIPTION
+The
+.Nm
+program links objects created by
+.Xr rgbasm 1
+into a single Game Boy ROM file.
+.Pp
+By default, HOME sections created by the assembler are placed in the 16KiB
+bank 0, and CODE/DATA sections are placed in any bank except bank 0. If your
+ROM will only be 32KiB, you can use the
+.Fl t
+option to override this.
+.Pp
+The arguments are as follows:
+.Bl -tag -width Ds
+.\" ITEM
+.It Fl l Ar library
+Include a referenced library module created with
+.Xr rgblib 1 .
+Note that specified libraries will be included only if needed\(emthat is, if
+a SECTION from a library is referenced by an object file. Only the relevant
+SECTION will be included, rather than the entire module.
+.\" ITEM
+.It Fl m Ar mapfile
+Write a mapfile to the given filename.
+.\" ITEM
+.It Fl n Ar symfile
+Write a symbol file to the given filename.
+.\" ITEM
+.It Fl o Ar outfile
+Write ROM image to the given filename.
+.\" ITEM
+.It Fl p Ar pad_value
+When padding an image, pad with this value. The default is 0x00.
+.\" ITEM
+.It Fl s Ar symbol
+???
+.\" ITEM
+.It Fl t
+Write a tiny (32KiB) ROM file. This forces all DATA/CODE sections to be of
+type HOME, and increases the HOME section size from 16KiB to 32KiB.
+.El
+.\" SECTION
+.Sh EXAMPLES
+All you need for a basic ROM is an object file, which can be made into a ROM
+image like so:
+.Pp
+.D1 $ rgblink \-o bar.gb foo.o
+.Pp
+The resulting bar.gb will not have correct checksums (unless you put them in
+the assembly source). You should use
+.Xr rgbfix 1
+to fix these so that the program will actually run in a Game Boy:
+.Pp
+.D1 $ rgbfix \-v bar.gb
+.\" SECTION
+.Sh SEE ALSO
+.Xr rgbds 7 ,
+.Xr rgbasm 1 ,
+.Xr rgbfix 1 ,
+.Xr rgblib 1 ,
+.Xr gbz80 7
+.\" SECTION
+.Sh HISTORY
+.Nm
+was originally written by Carsten Sørensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.