1RGBLINK(1)                BSD General Commands Manual               RGBLINK(1)
2

NAME

4     rgblink — Game Boy linker
5

SYNOPSIS

7     rgblink [-dtVvwx] [-l linker_script] [-m map_file] [-n sym_file]
8             [-O overlay_file] [-o out_file] [-p pad_value] [-s symbol]
9             file ...
10

DESCRIPTION

12     The rgblink program links RGB object files, typically created by
13     rgbasm(1), into a single Game Boy ROM file.  The format is documented in
14     rgbds(5).
15
16     ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX
17     sections are placed in any 16 KiB “bank” except the first.  If your ROM
18     will only be 32 KiB, you can use the -t option to change this.
19
20     Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM (“bank
21     0”), and WRAMX sections are placed in any bank of the last 4 KiB.  If
22     your ROM doesn't use banked WRAM, you can use the -w option to change
23     this.
24
25     Also, if your ROM is designed for a monochrome Game Boy, you can make
26     sure that you don't use any incompatible section by using the -d option,
27     which implies -w but also prohibits the use of banked VRAM.
28
29     Note that options can be abbreviated as long as the abbreviation is unam‐
30     biguous: --verb is --verbose, but --ver is invalid because it could also
31     be --version.  The arguments are as follows:
32
33     -d, --dmg
34             Enable DMG mode.  Prohibit the use of sections that doesn't exist
35             on a DMG, such as VRAM bank 1.  This option automatically enables
36             -w.
37
38     -l linker_script, --linkerscript linker_script
39             Specify a linker script file that tells the linker how sections
40             must be placed in the ROM.  The attributes assigned in the linker
41             script must be consistent with any assigned in the code.  See
42             rgblink(5) for more information about the linker script format.
43
44     -m map_file, --map map_file
45             Write a map file to the given filename, listing how sections and
46             symbols were assigned.
47
48     -n sym_file, --sym sym_file
49             Write a symbol file to the given filename, listing the address of
50             all exported symbols.  Several external programs can use this in‐
51             formation, for example to help debugging ROMs.
52
53     -O overlay_file, --overlay overlay_file
54             If specified, sections will be overlaid "on top" of the provided
55             ROM image.  In that case, all sections must be fixed.  This may
56             be used to patch an existing binary.
57
58     -o out_file, --output out_file
59             Write the ROM image to the given file.
60
61     -p pad_value, --pad pad_value
62             When inserting padding between sections, pad with this value.
63             Has no effect if -O is specified.  The default is 0.
64
65     -s symbol, --smart symbol
66             This option is ignored.  It was supposed to perform smart linking
67             but fell into disrepair, and so has been removed.  It will be re‐
68             implemented at some point.
69
70     -t, --tiny
71             Expand the ROM0 section size from 16 KiB to the full 32 KiB as‐
72             signed to ROM.  ROMX sections that are fixed to a bank other than
73             1 become errors, other ROMX sections are treated as ROM0.  Useful
74             for ROMs that fit in 32 KiB.
75
76     -V, --version
77             Print the version of the program and exit.
78
79     -v, --verbose
80             Verbose: enable printing more information to standard error.
81
82     -w, --wramx
83             Expand the WRAM0 section size from 4 KiB to the full 8 KiB as‐
84             signed to WRAM.  WRAMX sections that are fixed to a bank other
85             than 1 become errors, other WRAMX sections are treated as WRAM0.
86
87     -x, --nopad
88             Disables padding the end of the final file.  This option automat‐
89             ically enables -t.  You can use this when not not making a ROM.
90             When making a ROM, be careful that not using this is not a re‐
91             placement for rgbfix(1)'s -p option!
92

EXAMPLES

94     All you need for a basic ROM is an object file, which can be made into a
95     ROM image like so:
96
97           $ rgblink -o bar.gb foo.o
98
99     The resulting bar.gb will not have correct checksums (unless you put them
100     in the assembly source).  You should use rgbfix(1) to fix these so that
101     the program will actually run in a Game Boy:
102
103           $ rgbfix -v bar.gb
104
105     Here is a more complete example:
106
107           $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o
108           obj/engine.o
109

BUGS

111     Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
112

SEE ALSO

114     rgbasm(1), rgblink(5), rgbfix(1), rgbds(5), rgbds(7)
115

HISTORY

117     rgblink was originally written by Carsten Sørensen as part of the ASMotor
118     package, and was later packaged in RGBDS by Justin Lloyd.  It is now
119     maintained by a number of contributors at https://github.com/gbdev/rgbds
120
121BSD                             March 28, 2021                             BSD