1RGBLINK(1) BSD General Commands Manual RGBLINK(1)
2
4 rgblink — Game Boy linker
5
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
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
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
111 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
112
114 rgbasm(1), rgblink(5), rgbfix(1), rgbds(5), rgbds(7)
115
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