RGBLINK(5)

👑 RGBLINK(5) — the linker script file format, bestie ✨

okay so this page lives in the File Formats Manual and it's literally all about rgblink's linker script. come sit with me 🫶

✨ NAME ✨

rgblink — the linker script file format. that's it, that's the vibe 💅

🦋 DESCRIPTION 🦋

The linker script is a file that lets you specify attributes for sections at link time, and in a centralized manner. iconic, honestly. There can only be one linker script per invocation of rgblink, but it can be split into several files (using the INCLUDE directive). so organized 🎀

🌸 Basic syntax 🌸

The linker script syntax is line-based. Each line may have a directive or section name, a comment, both, or neither. Whitespace (space and tab characters) is used to separate syntax elements, but is otherwise ignored. lowkey chill like that.

Comments begin with a semicolon ; character, until the end of the line. They are simply ignored. no cap, they just vanish 💀

Keywords are composed of letters and digits (but they can't start with a digit); they are all case-insensitive. slay, no shouting required.

Numbers can be written in a number of formats:

• Decimal — no prefix, accepted characters 0123456789
• Hexadecimal — prefixes $, 0x, 0X, accepted characters 0123456789ABCDEF
• Octal — prefixes &, 0o, 0O, accepted characters 01234567
• Binary — prefixes %, 0b, 0B, accepted characters 01

Underscores are also accepted in numbers, except at the beginning of one. This can be useful for grouping digits, like 1_234 or $ff_80. we love a readability moment ✨

Strings begin with a double quote, and end at the next (non-escaped) double quote. Strings must not contain literal newline characters. Most of the same character escapes as rgbasm(5) are supported, specifically \\, \", \n, \r, \t, and \0. Other backslash escape sequences in rgbasm(5) are only relevant to assembly code and do not apply in linker scripts. ok so don't get cute with the other ones 🙈

🧚 Directives 🧚

💜 Including other files

• INCLUDE path — acts as if the contents of the file at path were copy-pasted in place of the INCLUDE directive. path must be a string. literally ctrl-c ctrl-v energy, but make it linker 🫶

🔥 Specifying the active bank

The active bank can be set by specifying its type (memory region) and number. The possible types are: ROM0, ROMX, VRAM, SRAM, WRAM0, WRAMX, OAM, and HRAM. The bank number can be omitted from the types that only contain a single bank, which are: ROM0, VRAM if -d is passed to rgblink(1), WRAM0, OAM, and HRAM. one-bank girlies don't need a number 💅

After a bank specification, the "current address" is set to the last value it had for that bank. If the bank has never been active thus far, the "current address" defaults to the beginning of the bank (e.g. $4000 for ROMX sections). memory lane, but for addresses 🌈

Instead of giving a bank number, the keyword FLOATING can be used instead; this sets the type of the subsequent sections without binding them to a particular bank. (If the type only allows a single bank, e.g. ROM0, then FLOATING is valid but redundant and has no effect.) Since no particular section is active, the "current address" is made floating (as if by a FLOATING directive), and ORG is not allowed. main character energy: unbound, unbothered ✨

⭐ Changing the current address

A bank must be active for any of these directives to be used. no bank, no moves, periodt.

• ORG addr — sets the "current address" to addr. This directive cannot be used to move the address backwards: addr must be greater than or equal to the "current address". no time travel bestie 😭
• FLOATING — causes all sections between it and the next ORG or bank specification to be placed at addresses automatically determined by rgblink. (It is, however, compatible with ALIGN below.) let rgblink cook 🍓
• ALIGN addr, offset — increases the "current address" until it is aligned to the specified boundary (i.e. the align lowest bits of the address are equal to offset). If offset is omitted, it is implied to be 0. For example, if the "current address" is $0007, ALIGN 8 would set it to $0100, and ALIGN 8, 10 would set it to $000A. math ate, fr fr 🔥
• DS size — increases the "current address" by size. The gap is not allocated, so smaller floating sections can later be placed there. it's giving reserved-but-not-really 💀

🎀 Section placement 🎀

A section can be placed simply by naming it (with a string). Its bank is set to the active bank, and its address to the "current address". Any constraints the section already possesses (whether from earlier in the linker script, or from the object files being linked) must be consistent with what the linker script specifies: the section's type must match, the section's bank number (if set) must match the active bank, etc. In particular, if the section has an alignment constraint, the address at which it is placed by the linker script must obey that constraint; otherwise, an error will occur. consistency is the whole aesthetic, ngl 💅

After a section is placed, the "current address" is increased by the section's size. This must not increase it past the end of the active memory region. do not overflow, we are not doing that today 🙈

The section must have been defined in the object files being linked, unless the section name is followed by the keyword OPTIONAL. so either it exists or you said OPTIONAL, pick a lane ✨

---

🌈 EXAMPLES 🌈

      ; This line contains only a comment
      ROMX $F            ; start a bank
        "Some functions" ; a section name
        ALIGN 8          ; a directive
        "Some \"array\""

      WRAMX 2            ; start another bank
        org $d123        ; another directive
        "Some variables"

look at that lowercase org — case-insensitive queen 👑

🔍 SEE ALSO 🔍

rgbasm(1), rgbasm(5), rgblink(1), rgbfix(1), rgbgfx(1), gbz80(7), rgbds(5), rgbds(7) — the whole friend group 🫶

📜 HISTORY 📜

rgblink(1) was originally written by Carsten Sørensen as part of the ASMotor package, and was later repackaged in RGBDS by Justin Lloyd. It is now maintained by a number of contributors at https://github.com/gbdev/rgbds. a legacy icon 👑

---

💖 and that's the whole page bestie, no notes. this one's from Debian, dated September 22, 2026 — go link something iconic ✨🎀