shithub: rgbds

ref: f57d33b17afa98fb455b500ef290511c604c32c8
dir: /docs/rgblink.1.html/

View raw version
<!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> &#x2014;
<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 &#x201C;bank&#x201D; 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
    (&#x201C;bank 0&#x201D;), 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 &quot;on top&quot; 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&#x00F8;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>