Another bugfix update for the fall equinox 🍂, but the number of bugs fixed is anything but small (unfurl the collapsed lists below if you're curious)! No new features whatsoever, but we expect this should be the most stable version of RGBDS ever. (Hope that didn't jinx it?)

RGBASM

• add sp, <offset> and ld hl, sp + <offset> will now also warn about offsets between 128 and 255 (caveat: offsets computed by RGBLINK cannot currently be warned about, but this should be implemented in v1.1.0)
• NUL characters (\0) are no longer allowed in section names and assertion messages

RGBLINK

• Symbol and map files now get emitted as soon as a valid section layout is found, even if any assertions fail, which we hope will make some failing bank- or address-related assertions easier to debug (caveat: if any assertions do fail, any previous .sym and .map files will have been overwritten but the previous ROM file will not!)
• Overhauled the section placement algorithm, fixing several bugs (hangs, invalid placements, etc), and possibly improving performance; notably:
  • -S/--scramble now enforces that sections fit within the specified number of banks, rather than silently falling back to the default packing
  • Correctly check sufficiently large alignment with non-zero offsets
  • Honor zero-sized sections' alignment offsets, memory regions, etc.
• -t/--tiny now accepts fixed-bank ROMX, BANK[1] sections, and -w/--wramx now accepts fixed-bank WRAMX, BANK[1] sections
• -S/--scramble sram=256 is now accepted

RGBGFX

• Fixed several crashes related to -B/--background-color and -x/--trim-end
  💡 Note: we would like to deprecate -x/--trim-end in v1.1.0! Please let us know if this would be an issue for you. We believe -B/--background covers its use cases more cleanly: unlike trimmed tiles, background tiles are applied in the tilemap and attrmap too; they can be placed anywhere in the image, not just the end; and they do not require updating a hard-coded number if you edit the image.
• -C/--color-curve is now supported in -r/--reverse mode
• Tile or palette IDs that can't fit in the tile/attribute maps now raise a warning
• Fixed omitting a transparent color from explicitly-specified palettes if the image has transparency

All

• Many documentation mistakes have been corrected
• Several error and warning messages have been fixed and/or cleaned up
• Some performance optimizations have been made, though we have not measured any significant improvements on recent hardware (contact us if RGBDS is slow on your machine!)
• Fixed a dozen or so integer overflows throughout, which would cause silent invalid behavior (but no crashes)

Misc

• contrib/view_palettes.sh can now output to standard output
• Many internal fixes to the development setup; we hope that contributing to RGBDS is now easier than ever!
• General system stability improvements to enhance the user's experience 😜

Also, pour one out for the one program who's been absent from changelogs since v0.9.4, handling our thorough reviews like a champ... RGBFIX! 🫡

Edited on 2026-08-06: fixed install.sh inside rgbds-macos.zip (see issue #2045)!

Another small bugfix update. The main thing is fixing backwards jr from ROM0 to HRAM, which had broken in v1.0.2. The v1.0.2+hotfix Git tag was also incompatible with rgbenv, so v1.0.3 fixes that.

RGBASM:

• Fix INCBIN on Windows to work with files larger than 2 GiB (no ROM can be that large but a partial INCBIN can still work)
• FMOD and LOG explicitly handle invalid inputs without any platform-specific behavior

RGBLINK:

• Fix the v1.0.2 regression that prevented backwards jr from low ROM0 to high HRAM
• Show -Wtruncation warnings for invalid jr addresses
• Fix an SDAS object error message to refer to a section by its correct name
• Fix reading the value of "relocations" symbol/section index from SDAS objects

RGBGFX:

• Invalid -B/--background-color specs will print one error message, not two redundant ones
• Fix potential undefined behavior in the palette generation algorithm

All:

• Fix handling of at-files containing -- followed by positional arguments
• Support COLUMNS environment variable to control --help width

Edited on 2026-08-06: fixed install.sh inside rgbds-macos.zip (see issue #2045)!

Happy anniversary of the first lunar landing! 🌙🚀

This is simply a bugfix and optimization release. Most of the fixes, including the severe-sounding "crash"es, are really edge cases that we aren't aware of anyone ever running into; but some have affected real users (like rgbgfx -p/--palette generation, or SECTION UNION alignment, or faster .asm parsing).

(Please note the Git tag name is v1.0.2+hotfix, not v1.0.2. We needed to amend the initial release, but GitHub's immutable releases had made the v1.0.2 tag impossible to edit. The reported --version is still v1.0.2 by all tools.)

RGBASM:

• Modulo $8000_0000 % -1 warns with -Wdiv, like $8000_0000 / -1 already did
• Fix negative macro arguments (e.g. \<-1>) when SHIFTed by some amount
• Improve some error messages, e.g. for invalid command-line options and for section creation errors

RGBLINK:

• Add -Wlarge-constant warning (about numbers in linker scripts) that's enabled by default (the same as RGBASM)
• Modulo $8000_0000 % -1 warns with -Wdiv, like $8000_0000 / -1 already did, and does not potentially crash
• SECTION UNION alignment could be incorrect or fail to build depending on the order of UNIONs from multiple object files (thanks to @vulcandth for the fix!)
• Parse numeric literals in linker scripts the same way as RGBASM (handling hex/octal/binary base prefixes, and _ digit separators)

RGBGFX:

• Fix -p/--palette generation being inconsistent and potentially failing depending on whether -Z/--columns was passed (thanks to @ElectroDeoxys for reporting this and to @vulcandth for help fixing it!)
• Report CGB colors in error/verbose messages formatted as GB:rr,gg,bb, not $xxxx

Build/Test:

• Rename test/fetch-test-deps.sh to test/external/fetch-repos.sh
• Refactor and tidy up the CTest-based testing system to use LABELS instead of ad-hoc -D defines (previously -DUSE_NONFREE_TESTS and -DUSE_EXTERNAL_TESTS)
• Refactor and tidy up the CMake-based build system; note that the minimum required CMake version is now 3.24 from August 2022 (previously 3.9 from July 2017)

Happy New Year! 🎊 🐎

As promised, we use semantic versioning now, so 1.0.1 being a "patch" release means that it's fully backwards compatble with 1.0.0. All that's changed is fixing various bugs (and typos, internal refactorings, etc).

(Many of these bugs were found with the "fuzzing" tool AFL++, so they involve unrealistic inputs which would be unlikely or impossible in normal usage of RGBDS. Still, even specifically-crafted garbage inputs should give sensible error messages and not crash, so we try to find and fix these.)

RGBASM:

• Symbol names of just three or more periods ("...", "....", etc) were mistakenly allowed
• SECTION UNION was mistakenly allowed for ROM sections (when there was no second SECTION UNION of the same name)
• -MG and -MC were not accounting for -P/--preinclude files
• Non-UTF-8 "garbage" characters at the end of a file could hang in an infinite loop

RGBLINK:

• Undefined symbols could cause extra warning messages about meaningless values in expressions
• Various invalid object files (which RGBASM would not output in the first place) could print misleading error messages or outright crash

RGBGFX:

• Input images with ambiguous alpha channel values (neither transparent nor opaque) could crash due to an assertion failure
• Clarify documentation of rgbgfx -C/--color-curve
• Improve some error messages

All programs:

• Some errors with command-line options could be incorrectly reported (due to inaccurate errno values)
• For RGBASM and RGBLINK, very long error location backtraces could crash with a stack overflow (only ever observed during fuzzing)

Happy Halloween! 🎃

We've finally hit a big milestone: the first major version increment, from 0.x to 1.0.0! 🥳

From now on RGBDS will adhere to semantic versioning ("semver"), meaning that you can rely on meaningful version numbers. Breaking changes will be reserved for new major versions; new features will require a minor version update; and bugfixes, internal refactorings, or other small tweaks will be patch-level version updates.

Removed

• Treating multi-value strings as numbers, and the rgbasm -Wnumeric-string warning about doing so
• ldio [c], a/ldio a, [c], and ld [c], a/ld a, [c] (use ldh [c], a/ldh a, [c] instead)
• ldh [$xx], a/ldh a, [$xx] (use ldh [$FFxx], a/ldh a, [$FFxx] instead)

Deprecated

You can pass -Wno-obsolete to silence warnings about these deprecations for now, but they will eventually be removed.

• Treating single-value strings as numbers (use 'c'haracter constants or the CHARVAL function instead)
• 1-indexed string functions STRIN, STRRIN, STRSUB, and CHARSUB (use 0-indexed STRFIND, STRRFIND, STRSLICE, and STRCHAR instead)
• rgbfix -O/--overwrite (use the -Wno-overwrite diagnostic flag instead)

Added

• Error/warning output is $\normalsize{\textsf{\color{#ff0000}c\color{#ff8000}o\color{#cccc00}l\color{#00aa00}o\color{#00aaaa}r\color{#4444ff}f\color{#6600cc}u\color{#ff00aa}l}}$ by default when sent to a terminal; control it with --color always/never/auto, or the NO_COLOR or FORCE_COLOR environment variables
• Add a question mark after macro?, rept?, for?, include? or macro invocations like my_mac?, to "silence" them, excluding them from error/warning location backtraces
• === and !== operators for string comparison, as an alternative to STRCMP
• :: can join db/dw/dl/ds directives as well as instructions onto one line
• __SCOPE__ is an empty string "", ".", or "..", according to the current innermost label scope level
• CHARVAL(str), without an index argument, gets the numeric value of a single-character string
• OPT allows an optional dash before flags to be more like the CLI (e.g. OPT -Wno-obsolete)
• CHARMAP accepts character literals as well as strings (there is no difference in effect)
• -B/--backtrace configures location backtraces for error/warning messages in RGBASM and RGBLINK
• -v/--verbose has multiple levels for RGBASM and RGBLINK too, not just RGBGFX
  _{(RGBFIX's functionality is too simple to need verbose debug output, and it uses the -v flag for something else already)}
• rgbasm -Wexport-undefined warns when you EXPORT an undefined symbol (enabled by -Wall)
• rgblink -Wtruncation supports warning levels =0, =1, or =2, same as rgbasm -Wtruncation
• rgbgfx -c auto explicitly specifies to use the automatic palette generation algorithm
• rgbgfx -c dmg is short for rgbgfx -c dmg=e4
• rgbgfx -O without -o or without any of -A -P -Q -T prints a warning
• Numeric command-line arguments and OPT arguments can use any base prefix: 0x or $ for hex, 0b or % for binary, 0o or & for octal, or nothing for decimal
• rgbasm, rgblink, and rgbfix, as well as rgbgfx already, support @args.flags to read more CLI arguments from an args.flags "at-file"

Changed

• Underscores in integer constants can go after the base prefix, between digits, or before the fixed-point q suffix, but cannot be multiple in a row or trailing
• Too-large integer constants get evaluated as 0
• OPT p argument is decimal by default, and requires 0x prefix for hexadecimal (like OPT Q, OPT r, and CLI -p/--pad-value)
• Leading spaces are stripped from all OPT arguments, not just OPT r
• Spaces are consistently stripped from the beginning and end of macro arguments, even with a block comment in the middle of the spaces
• rgbasm -Wlarge-constant is enabled by default instead of by -Wall
• rgbasm -Wpurge default level is increased from 1 to 2
• rgbasm -Wtruncation and rgblink -Wtruncation default level is reduced from 2 to 1
• RGBLINK .map files will only print ; Next fragment or ; Next union comments when they also have subsequent labels to print
• Reformatted and rephrased some error messages; in particular, location traces are now indented and have one file location per line

Fixed

• bit/res/set with an unknown bit index could segfault
• Division and modulo were off by one for very large negative numbers
• Exporting an undefined symbol is now an error
• A local label after a keyword (e.g. call.local) is now an error
• Labels were allowed before ENDC, which could lead to inconsistent lexing and parsing
• Line numbers after using "nested" macros were incorrect
  _{Macros can be "nested" by defining the inner macro within an EQUS and expanding it}
• Interpolation would fail after an empty string literal (""{example})
• q could be repeated in fixed-point format specs (e.g. STRFMT("%qqq16f", 3.14q16))
• Formatting very long fixed-point numbers could cut off the end (e.g. STRFMT("%#.255q1f", 1073741823.5q1))
• Character literals would be misread after invalid "garbage" characters
• "while expanding symbol" error backtrace was printing the symbol's contents instead of its name
• Too-large integer constants would print a -Wlarge-constant error for every subsequent digit
• Section-related error messages could be inaccurate/misleading after use of [[ fragment literals ]]
• RGBASM's Bash completion script supports -MC
• RGBLINK supports .rel object files generated by SDCC 4.4.0 and later (XL4 instead of XL3)
• RGBGFX could output incorrect attrmap data for bank 1 when bank 0 contained 256 duplicatable tiles (i.e. -N 256,256 without -u)

Thanks to @Rangi42, @ISSOtm, and @ReiquelApplegate for the work done for this release.

RGBDS's major version number is finally going to increment from 0 to 1! As of this release, we'll stick to semantic versioning, so that any future breaking changes will require a major version update, new features will be a minor version, and bug fixes will be a patch version. That should make it easier to manage RGBDS version compatibility for assembly projects. (And if a "version 2.0" does eventually come after this one, it might be rewritten in Rust.)

This is a release candidate to help people test it out early, and make sure we won't need to release a 1.0.1 bugfix immediately afterwards.

What's different from v1.0.0-rc1?

• Added: === and !== operators for string comparison, as an alternative to STRCMP
• Added: CHARMAP accepts character literals as well as strings (there is no difference in effect)
• Changed: rgbgfx -O without -o or without any of -A -P -Q -T prints a warning
• Changed: Numeric command-line arguments and OPT arguments can use any base prefix: 0x or $ for hex, 0b or % for binary, 0o or & for octal, or nothing for decimal
• Changed: OPT p argument is decimal by default, and requires 0x prefix for hexadecimal (like OPT Q, OPT r, and CLI -p/--pad-value)
• Changed: Leading spaces are stripped from all OPT arguments, not just OPT r
• Changed: Spaces are consistently stripped from the beginning and end of macro arguments, even with a block comment in the middle of the spaces
• Changed: RGBLINK .map files will only print ; Next fragment or ; Next union comments when they also have subsequent labels to print
• Changed: RGBGFX accurately rounds 8-bit to 5-bit color conversion (and vice-versa for -r/--reverse)
• Fixed: bit/res/set with an unknown bit index could segfault
• Fixed: Formatting very long fixed-point numbers could cut off the end (e.g. STRFMT("%#.255q1f", 1073741823.5q1))
• Fixed: Section-related error messages could be inaccurate/misleading after use of [[ fragment literals ]]

Thanks to @Rangi42, @ISSOtm, and @ReiquelApplegate for the work done for this release.

RGBDS's major version number is finally going to increment from 0 to 1! As of this release, we'll stick to semantic versioning, so that any future breaking changes will require a major version update, new features will be a minor version, and bug fixes will be a patch version. That should make it easier to manage RGBDS version compatibility for assembly projects. (And if a "version 2.0" does eventually come after this one, it might be rewritten in Rust.)

This is a release candidate to help people test it out early, and make sure we won't need to release a 1.0.1 bugfix immediately afterwards.

Removed

• Treating multi-value strings as numbers, and the rgbasm -Wnumeric-string warning about doing so
• ldio [c], a/ldio a, [c], and ld [c], a/ld a, [c] (use ldh [c], a/ldh a, [c] instead)
• ldh [$xx], a/ldh a, [$xx] (use ldh [$FFxx], a/ldh a, [$FFxx] instead)

Deprecated

• Treating single-value strings as numbers (use 'c'haracter constants or the CHARVAL function instead)
• 1-indexed string functions STRIN, STRRIN, STRSUB, and CHARSUB (use 0-indexed STRFIND, STRRFIND, STRSLICE, and STRCHAR instead)
• rgbfix -O/--overwrite (use the -Wno-overwrite diagnostic flag instead)

Added

• Error/warning output is $\normalsize{\textsf{\color{#ff0000}c\color{#ff8000}o\color{#cccc00}l\color{#00aa00}o\color{#00aaaa}r\color{#4444ff}f\color{#6600cc}u\color{#ff00aa}l}}$ by default when sent to a terminal; control it with --color always/never/auto, or the NO_COLOR or FORCE_COLOR environment variables
• Add a question mark after macro?, rept?, for?, include? or macro invocations like my_mac?, to "silence" them, excluding them from error/warning location backtraces
• :: can join db/dw/dl/ds directives as well as instructions onto one line
• CHARVAL(str), without an index argument, gets the numeric value of a single-character string
• OPT allows an optional dash before flags to be more like the CLI (e.g. OPT -Wno-obsolete)
• -B/--backtrace configures location backtraces for error/warning messages in RGBASM and RGBLINK
• -v/--verbose has multiple levels for RGBASM and RGBLINK too, not just RGBGFX
  _{(RGBFIX's functionality is too simple to need verbose debug output, and it uses the -v flag for something else already)}
• rgbasm -Wexport-undefined warns when you EXPORT an undefined symbol (enabled by -Wall)
• rgblink -Wtruncation supports warning levels =0, =1, or =2, same as rgbasm -Wtruncation
• rgbgfx -c auto explicitly specifies to use the automatic palette generation algorithm
• rgbgfx -c dmg is short for rgbgfx -c dmg=e4

Changed

• Underscores in integer constants can go after the base prefix, between digits, or before the fixed-point q suffix, but cannot be multiple in a row or trailing
• Too-large integer constants get evaluated as 0
• rgbasm -Wlarge-constant is enabled by default instead of by -Wall
• Reformatted and rephrased some error messages; in particular, location traces are now indented and have one file location per line

Fixed

• Division and modulo were off by one for very large negative numbers
• Exporting an undefined symbol is now an error
• Line numbers after using "nested" macros were incorrect
  _{Macros can be "nested" by defining the inner macro within an EQUS and expanding it}
• Interpolation would fail after an empty string literal (""{example})
• q could be repeated in fixed-point format specs (e.g. STRFMT("%qqq16f", 3.14q16))
• Character literals would be misread after invalid "garbage" characters
• "while expanding symbol" error backtrace was printing the symbol's contents instead of its name
• Too-large integer constants would print a -Wlarge-constant error for every subsequent digit
• RGBASM's Bash completion script supports -MC
• RGBLINK supports .rel object files generated by SDCC 4.4.0 and later (XL4 instead of XL3)

Thanks to @Rangi42 and @ISSOtm for the work done for this release.

We're still not following SemVer yet, so this release has a lot in it even though it's "only" a patch-level update -- comparable to v0.3.9, v0.4.2, v0.5.2...

Added

• Inline [[ fragment literals ]] can be used instead of labels for one-off data
• 'character' constants are now preferred to single-character "strings" for getting the numeric value of a character
• READFILE(name[, maxlen]) returns the contents of a file as a string
• BYTELEN(str) returns the number of bytes in a string
• STRBYTE(str, idx) returns the idxth byte in a string
• SIZEOF applies to 8-and 16-bit registers, evaluating to their 1- or 2-byte size
• -W warning diagnostics for RGBLINK, RGBFIX, and RGBGFX
• rgbasm -MC flag which continues assembling even after a missing dependency (unlike -MG, which exits to let the dependency be generated before continuing)
• rgbasm -P can be specified multiple times to pre-include multiple files
• Linkerscripts support 0x/0b/0o/& numeric prefixes, _ numeric separators, and "\0" characters, same as assembly
• rgbgfx -c/--colors supports png: for PNG images as palette spec inputs
• rgbgfx -l/--base-palette sets a base palette ID, like -b/--base-tiles does for tilemap IDs
• rgbfix -m list does the same thing as rgbfix -m help (lists supported MBCs)
• Documented some more historical deprecations/removals which had been left out of rgbasm-old(5)

Changed

• Error message for ALIGN failure tells you what the actual alignment is
• Invalid rgblink -S/--scramble or rgbfix -f/--fix-spec arguments are a fatal error, not a warning

Fixed

• Aligning a section first to one size and then to a greater size could fail even when the new alignment is compatible
• Some string functions treated \0 characters in strings as the end of the string
• Overflowing exponent operator ** could cause undefined behavior
• Invalid warning flag parameters could be silently accepted, e.g. rgbasm -Wtruncation=256 acting like =0
• Unterminated strings in linkerscripts would break subsequent parsing
• Invalid rgblink -S/--scramble spec could crash
• Out-of-bounds rgbgfx -L/--slice coordinates could crash
• RGBGFX was skipping a step of its palette generation algorithm
• rgbfix -m with unlisted numeric values could crash
• The rgbds:latest Docker tag is correctly updated

Thanks to @Rangi42 and @avivace for the work done for this release.

Happy Pride month! 🏳️‍🌈

Added

• CHARVAL function gets individual values from a multi-value charmap entry
• ++ operator for string concatenation, as an alternative to STRCAT
• rgbgfx -c can take a dmg=XX DMG grayscale palette specification (works like rBGP)

Changed

• Restrict custom binary and graphics digits to digits, letters, ., #, or @
• Recover from syntax errors even inside REPT/FOR loops
• Hint to {interpolate} names when EQUS expanding does not occur
• .sym file sorting accounts for local labels' parents' addresses and names
• rgbgfx -r encodes reversed PNG images as grayscale or indexed colors when possible
• Omit the version number from distributed release archive filenames

Fixed

• STRSLICE with two arguments assumed an off-by-one stop index
• rgbasm -MP would generate phony dependencies even for files that don't exist
• Handle missing newline at EOF for linkerscript INCLUDEd files
• The Dockerfile was building but not installing RGBDS in its environment
• Building with Bison versions 3.x below 3.5 could fail over "parse.lac=full"
• A second rgbgfx -c argument might not completely override the previous one

Thanks to @Rangi42 and @ISSOtm for the work done for this release.

May the 4th be with you! ⭐ 👾

Added

• New 0-indexed string functions (we plan to eventually deprecate the old 1-indexed ones):
  • STRFIND and STRRFIND: like STRIN and STRRIN
  • STRCHAR: like CHARSUB
  • STRSLICE: like STRSUB, but taking start and stop indexes, instead of a start position and length
• CHARCMP: compares two strings by their charmap value sequences
• CHARSIZE: counts how many charmap values a single character would map to
• REVCHAR: reverse-maps a value sequence to its charmap string (the values must have one unique corresponding charmap)
• Allow macro \<arg> to take negative values to count arguments from the end (e.g. \<-2> is the penultimate arg)
• Allow the index of bit/res/set instructions to be determined at link time
• rgbgfx -B/--background specifies a "background" color; tiles entirely of that color will be skipped in the graphic output
• rgbfix -o/--output can write its output to a different file than its input (must have one input file); thanks @jmillikin!

Changed

• Raw symbols do not undergo EQUS expansion (so #symbol can be used instead of "{symbol}")
• Some invalid instructions have more specific error messages than just "syntax error"
• Terser RGBASM output for sequences of unknown characters
• contrib/gbdiff.bash does not need a .sym file to be sorted

Fixed

• Macro names could be used as numeric symbols with value 0
• Map files were listing anonymous labels (as Unicode escape syntax)
• RGBGFX could segfault with transparent colors in embedded palettes
• RGBGFX could segfault or give incorrect output for grayscale images with transparent colors
• RGBFIX expects nonzero -r/--ram-size for -m MBC6 (the one game that uses MBC6 has -r 3)
• CMAKE_CXX_FLAGS_DEBUG can be user-specified

Thanks to @Rangi42 and @ISSOtm for the work done for this release.