mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 10:12:06 +00:00
193 lines
9.6 KiB
HTML
193 lines
9.6 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- This is an automatically generated file. Do not edit.
|
|
This file is part of RGBDS.
|
|
|
|
Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
|
|
|
|
SPDX-License-Identifier: MIT
|
|
-->
|
|
<head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta charset="utf-8"/>
|
|
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
|
|
<link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
|
|
<title>RGBLINK(1)</title>
|
|
</head>
|
|
<body>
|
|
<table class="head">
|
|
<tr>
|
|
<td class="head-ltitle">RGBLINK(1)</td>
|
|
<td class="head-vol">General Commands Manual</td>
|
|
<td class="head-rtitle">RGBLINK(1)</td>
|
|
</tr>
|
|
</table>
|
|
<div class="manual-text">
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
|
<code class="Nm">rgblink</code> —
|
|
<span class="Nd">Game Boy linker</span>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
|
<table class="Nm">
|
|
<tr>
|
|
<td><code class="Nm">rgblink</code></td>
|
|
<td>[<code class="Fl"><a href="#d">-d</a><a href="#t">t</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a><a href="#x">x</a></code>] [<code class="Fl"><a href="#l">-l</a></code>
|
|
<var class="Ar">linker_script</var>] [<code class="Fl"><a href="#m">-m</a></code>
|
|
<var class="Ar">map_file</var>] [<code class="Fl"><a href="#n">-n</a></code>
|
|
<var class="Ar">sym_file</var>] [<code class="Fl"><a href="#O">-O</a></code>
|
|
<var class="Ar">overlay_file</var>] [<code class="Fl"><a href="#o">-o</a></code>
|
|
<var class="Ar">out_file</var>] [<code class="Fl"><a href="#p">-p</a></code>
|
|
<var class="Ar">pad_value</var>] [<code class="Fl"><a href="#s">-s</a></code>
|
|
<var class="Ar">symbol</var>] <var class="Ar">file ...</var></td>
|
|
</tr>
|
|
</table>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
|
The <code class="Nm">rgblink</code> program links RGB object files, typically
|
|
created by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, into a single Game Boy ROM file. The
|
|
format is documented in <a class="Xr" href="rgbds.5.html">rgbds(5)</a>.
|
|
<p class="Pp">ROM0 sections are placed in the first 16 KiB of the output ROM,
|
|
and ROMX sections are placed in any 16 KiB “bank” except the
|
|
first. If your ROM will only be 32 KiB, you can use the
|
|
<code class="Fl">-t</code> option to change this.</p>
|
|
<p class="Pp">Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
|
|
(“bank 0”), and WRAMX sections are placed in any bank of the
|
|
last 4 KiB. If your ROM doesn't use banked WRAM, you can use the
|
|
<code class="Fl">-w</code> option to change this.</p>
|
|
<p class="Pp">Also, if your ROM is designed for a monochrome Game Boy, you can
|
|
make sure that you don't use any incompatible section by using the
|
|
<code class="Fl">-d</code> option, which implies <code class="Fl">-w</code>
|
|
but also prohibits the use of banked VRAM.</p>
|
|
<p class="Pp">Note that options can be abbreviated as long as the abbreviation
|
|
is unambiguous: <code class="Fl">--verb</code> is
|
|
<code class="Fl">--verbose</code>, but
|
|
<code class="Fl">--ver</code> is invalid because it
|
|
could also be <code class="Fl">--version</code>. The
|
|
arguments are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a>,
|
|
<code class="Fl">--dmg</code></dt>
|
|
<dd>Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG,
|
|
such as VRAM bank 1. This option automatically enables
|
|
<code class="Fl">-w</code>.</dd>
|
|
<dt><a class="permalink" href="#l"><code class="Fl" id="l">-l</code></a>
|
|
<var class="Ar">linker_script,</var>
|
|
<code class="Fl">--linkerscript</code>
|
|
<var class="Ar">linker_script</var></dt>
|
|
<dd>Specify a linker script file that tells the linker how sections must be
|
|
placed in the ROM. The attributes assigned in the linker script must be
|
|
consistent with any assigned in the code. See <a class="Xr" href="rgblink.5.html">rgblink(5)</a>
|
|
for more information about the linker script format.</dd>
|
|
<dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
|
|
<var class="Ar">map_file</var>,
|
|
<code class="Fl">--map</code>
|
|
<var class="Ar">map_file</var></dt>
|
|
<dd>Write a map file to the given filename, listing how sections and symbols
|
|
were assigned.</dd>
|
|
<dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
|
|
<var class="Ar">sym_file</var>,
|
|
<code class="Fl">--sym</code>
|
|
<var class="Ar">sym_file</var></dt>
|
|
<dd>Write a symbol file to the given filename, listing the address of all
|
|
exported symbols. Several external programs can use this information, for
|
|
example to help debugging ROMs.</dd>
|
|
<dt><a class="permalink" href="#O"><code class="Fl" id="O">-O</code></a>
|
|
<var class="Ar">overlay_file</var>,
|
|
<code class="Fl">--overlay</code>
|
|
<var class="Ar">overlay_file</var></dt>
|
|
<dd>If specified, sections will be overlaid "on top" of the provided
|
|
ROM image. In that case, all sections must be fixed. This may be used to
|
|
patch an existing binary.</dd>
|
|
<dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
|
|
<var class="Ar">out_file</var>,
|
|
<code class="Fl">--output</code>
|
|
<var class="Ar">out_file</var></dt>
|
|
<dd>Write the ROM image to the given file.</dd>
|
|
<dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
|
|
<var class="Ar">pad_value</var>,
|
|
<code class="Fl">--pad</code>
|
|
<var class="Ar">pad_value</var></dt>
|
|
<dd>When inserting padding between sections, pad with this value. Has no
|
|
effect if <code class="Fl">-O</code> is specified. The default is 0.</dd>
|
|
<dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>
|
|
<var class="Ar">symbol</var>,
|
|
<code class="Fl">--smart</code>
|
|
<var class="Ar">symbol</var></dt>
|
|
<dd>This option is ignored. It was supposed to perform smart linking but fell
|
|
into disrepair, and so has been removed. It will be reimplemented at some
|
|
point.</dd>
|
|
<dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>,
|
|
<code class="Fl">--tiny</code></dt>
|
|
<dd>Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to
|
|
ROM. ROMX sections that are fixed to a bank other than 1 become errors,
|
|
other ROMX sections are treated as ROM0. Useful for ROMs that fit in 32
|
|
KiB.</dd>
|
|
<dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
|
|
<code class="Fl">--version</code></dt>
|
|
<dd>Print the version of the program and exit.</dd>
|
|
<dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
|
|
<code class="Fl">--verbose</code></dt>
|
|
<dd>Verbose: enable printing more information to standard error.</dd>
|
|
<dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a>,
|
|
<code class="Fl">--wramx</code></dt>
|
|
<dd>Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to
|
|
WRAM. WRAMX sections that are fixed to a bank other than 1 become errors,
|
|
other WRAMX sections are treated as WRAM0.</dd>
|
|
<dt><a class="permalink" href="#x"><code class="Fl" id="x">-x</code></a>,
|
|
<code class="Fl">--nopad</code></dt>
|
|
<dd>Disables padding the end of the final file. This option automatically
|
|
enables <code class="Fl">-t</code>. You can use this when not not making a
|
|
ROM. When making a ROM, be careful that not using this is not a
|
|
replacement for <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>'s <code class="Fl">-p</code>
|
|
option!</dd>
|
|
</dl>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
|
|
All you need for a basic ROM is an object file, which can be made into a ROM
|
|
image like so:
|
|
<p class="Pp"></p>
|
|
<div class="Bd Bd-indent">$ rgblink -o bar.gb foo.o</div>
|
|
<p class="Pp">The resulting <var class="Ar">bar.gb</var> will not have correct
|
|
checksums (unless you put them in the assembly source). You should use
|
|
<a class="Xr" href="rgbfix.1.html">rgbfix(1)</a> to fix these so that the program will actually
|
|
run in a Game Boy:</p>
|
|
<p class="Pp"></p>
|
|
<div class="Bd Bd-indent"><code class="Li">$ rgbfix -v bar.gb</code></div>
|
|
<p class="Pp">Here is a more complete example:</p>
|
|
<p class="Pp"></p>
|
|
<div class="Bd Bd-indent"><code class="Li">$ rgblink -o bin/game.gb -n
|
|
bin/game.sym -p 0xFF obj/title.o obj/engine.o</code></div>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
|
|
Please report bugs on
|
|
<a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
|
|
ALSO</a></h1>
|
|
<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.5.html">rgblink(5)</a>,
|
|
<a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
|
|
<a class="Xr" href="rgbds.7.html">rgbds(7)</a>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
|
|
<code class="Nm">rgblink</code> was originally written by Carsten
|
|
Sørensen 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
|
|
<a class="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.
|
|
</section>
|
|
</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">November 26, 2019</td>
|
|
<td class="foot-os">General</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|