v0.9.0-rc1

Tip

Starting with this release, we publish universal ("fat") binaries for macOS, so they'll support x86-64 and newer ARM (“Apple Silicon”) CPUs!

⚠️ Deprecated

• Treating multi-character strings as numbers (you can use a single 32-bit character mapping instead)

Added

• RGBASM -s outputs a "state file", listing the values of (non-label) symbols when finished assembling
• RGBASM -Wpurge warns when purging exported symbols or labels
• Symbols can have non-leading $ characters (so an interpolated prefix{numeric} symbol works)
• Symbols can have the same names as reserved keywords by prefixing them with a #
• CHARMAP can map characters to sequences of multiple values, with values not limited to 8 bits
• A string constant . (period) which expands to the current global label scope
• A string constant .. (two periods) which expands to the current fully-qualified local label scope (e.g. Global.local)
• BITWIDTH(n) returns the number of bits necessary to represent n
• TZCOUNT(n) returns the count of trailing zero bits of n
• EXPORT DEF defines and exports a numeric symbol in a single line
• PUSHC name acts like PUSHC followed by SETCHARMAP name
• PUSHS ... acts like PUSHS followed by SECTION ...
• PUSHO ... acts like PUSHO followed by OPT ...
• cpl can also be written as cpl a
• RGBLINK supports e.g. ROMX FLOATING in linker scripts, which allows assigning a section to no particular bank (this is generally only useful with SDCC object files)
• RGBLINK's .sym file now includes exported numeric constants (if this breaks your tools, please check the .sym specification!)
• RGBGFX -i/--input-tileset uses a given tileset instead of generating all the tiles itself
• RGBGFX -r 0 infers a valid width for the reversed image
• RGBGFX -X or -Y only mirror tiles horizontally or vertically (-X -Y acts like -m)
• The contrib/view_palettes.sh script lets you render a GBC .pal file as an image

Changed

• LOW(Label) can be constant if Label is aligned to 8 or more bits
• !expr can be constant 0 if expr has any non-zero bits
• Error messages for undefined symbols mention if the symbol was previously purged
• Sections that grew too big are reported after the whole assembly file has been processed
• When RGBLINK encounters an unknown symbol, it lists the potential un-exported symbols by that name
• RGBLINK reports source locations for conflicts between object files
• RGBGFX -r gives a detailed warning if -c and -p mismatch; improved several other error messages too
• LOW() and HIGH() have their own RPN operators in the object file (this should lead to nicer output from rgbobj)
• Clarified a lot of documentation, including for fixed-point numbers and macros
• Explicitly document that FMOD behaves differently than %
• Increment object file revision number to 11

Fixed

• Label & CONSTANT was not actually doing the & operation!
• Some nonsensical uses of empty local labels (Global.) were ignored
• Many bugs prevented SDCC object files from being processed correctly (special thanks to @RubenZwietering for helping with bugfixing and testing!)
• Crash when assembling a nonexistent file
• Crash when INCLUDEing an unbounded-size file (e.g. /dev/urandom)
• Crash when passing an object file with invalid patch offsets to RGBLINK
• Crash when specifying palette files within RGBGFX at-files
• Crash when reversing an image if the tilemap referred to nonexistent tiles
• Multiple bugs with parsing text palette files (GPL, HEX, and PSP)
• Palette generation was suboptimal, potentially failing to fit within 8 palettes
• Maximum number of palettes wrapped around after 255
• Allow text palette files to have the maximum number of colors
• Building works on systems with bison 3.8.0

v0.8.0

Happy Pride month! 🏳️‍🌈

This release internally refactored a lot of C code into more idiomatic C++ (partly to fix memory leaks), which *hopefully, knock on wood, fingers crossed* won't have broken anything else.

We're optimistic that the next release will be a 1.0.0 rewritten in Rust. 🦀

Added:

• RGBGFX allows #none as a "gap color" in -c palettes (thanks, @eievui5!)
• RGBFIX -L/--logo can specify a custom logo 1bpp instead of the Nintendo logo
• RGBASM allows "\0" as a NUL character in strings
• RGBASM align 16, N acts like org N (so align 16 acts like org 0)
• RGBLINK -p padding applies when output goes past the -O overlay file contents

Removed:

• Defining symbols without using DEF
• RGBASM -H/--nop-after-halt, -l/-auto-ldh, -h/--halt-without-nop, and -L/--preserve-ld options (the auto-ld-to-ldh and auto-nop-after-halt behaviors are now completely removed)
• RGBASM -i for --include (use -I)
• RGBGFX --output-* long options (use --auto-* or the short -A/-P/-Q/-T options)

Changed:

• Strings and symbol names are no longer limited to 255 characters!
• expr && 0 and expr & 0 are constant 0; expr || 1 is constant 1
• All warnings/errors refer to input/output file "-" as "<stdin>/<stdout>"
• Documentation switched from reStructuredText to Markdown for ease of contributing

Fixed:

• Increment object file revision number to 10 (since 0.7.0 updated the object file format but didn't increment this)
• Linker scripts infinitely looped when parsing decimal numbers (thanks, @huderlem!)
• Long RGBASM interpolation format specs could segfault
• RGBGFX --reverse --columns was incorrect for non-square images (thanks, @sfiera!)!!!!
• ACO palette files were not being read correctly
• Specifying an embedded palette to override a previously specified palette crashed (thanks, @ZoomTen!)
• Warning/error file-stack traces for macros inside REPT/FOR loops are complete
• Building RGBDS nested in another Git repo won't pick up that repo's tags for the RGBDS version
• Some fixed-point functions could give inconsistent results if they internally gave infinity or NaN (e.g. FMOD(value, 0.0))
• Formatting $8000_0000 (-2,147,483,648) as a string was omitting the negative sign
• BANK(NotALabel) is 1, not $4B4E4142 (the numeric value of "BANK" 😂)
• \@ could change within a macro or REPT/FOR if it was first used within an INCLUDE
• Some built-in symbols could be misreported as being defined on the command-line

v0.7.0

Starting with this release, we publish statically-linked Linux binaries! We also provide a Dockerfile to build RGBDS.

Deprecated:

• Defining symbols without using DEF (use {interpolation} if you relied on EQUS expansion for defined symbol names)
• RGBASM -H/--nop-after-halt and -l/-auto-ldh options (which are now off by default)

Added:

• Multiple instructions can go on one line, separated by ::
• #"raw strings" don't process any escapes (not even interpolation or macro args!)
• DS ALIGN[size, offset] to insert padding until the next alignment boundary within the same section
• RGBASM allows defining local labels for scopes that aren't active
• INCHARMAP function to check if a string matches a charmap value
• SIZEOF and STARTOF can now take section types like WRAM0 as argument
• ENDSECTION explicitly ends a section
• DS in RGBLINK linker scripts
• OPTIONAL sections in RGBLINK linker scripts
• FLOATING addresses in RGBLINK linker scripts (should improve SDCC interop)
• RGBASM -X/--max-errors stops after too many errors, with a default of 100
• Linker scripts support ALIGN alignment, offset
• RGBFIX warns when SGB compatibility is set with the wrong "old licensee", even if not setting it via RGBFIX itself
• RGBGFX can generate a palette from a spec, without an input image
• RGBGFX forces transparent colors to take slot #0 in all palettes
• RGBGFX -O/--group-outputs bases automatic output filenames on the output path, instead of the input path

Removed:

• name: MACRO syntax (use MACRO name instead)
• Escaped commas "\," inside strings (not necessary in macro arguments)
• __FILE__ and __LINE__
• Exported labels cannot have a space between their two colons (Label: : is invalid)

Changed:

• RGBASM -Wtruncation=1 will not warn about 8-bit ~$FF or 16-bit ~$FFFF values
• The memory usage summary in .map files is now placed at the top of the file
• Alignment offsets in RGBASM can now be negative (ALIGN 8, -1 is equivalent to ALIGN 8, 255)
• RGBGFX's --output-* options have been renamed to --auto-* for clarity
• RGBLINK .sym files sort symbols at the same address by their locality
• RGBLINK -S/--scramble prioritizes higher banks
• RGBGFX's long --output-* flags are renamed to --auto-*
• All programs show usage help when given missing or incorrect command-line arguments
• Add --only-free and --help options to test scripts
• PURGE arguments can go in any order

Fixed:

• RGBASM preserves the value of \@ through INCLUDEd files
• FOR loops, in some edge cases, could loop with unexpected values
• PUSHO and POPO now save and restore the r option
• ENDL now restores the label scope from before LOAD
• Anonymous labels are never exported anymore, as doing so could cause link errors
• -1 >>> 32 now equals 0, not -1
• Document ATAN2 to have argument order (y, x)
• RGBLINK's -w flag properly coerces WRAMX sections to WRAM0
• Fix off-by-one error in RGBLINK -S/--scramble argument validation
• RGBGFX could crash on some images with alpha transparency
• RGBGFX --color-curve now works as it always should have
• RGBGFX properly detects tiles with more than 4 colors
• RGBGFX -r/--reverse gave incorrect output with -d/--depth 1
• RGBGFX ignored -L/--slice if -u/--unique-tiles wasn't also passed
• RGBGFX ignored -c/--colors with -r/--reverse
• RGBGFX outputs a palette map to the right filename
• Fix formatting errors in documentation
• Fix incorrect options in RGBGFX zsh completions
• Made testing scripts a little more robust

v0.6.1

Starting with this release, we now publish macOS binaries!

Added:

• RGBASM prints a specific error message for leftover diff marks (+ and -)
• RGBLINK has improved .map file output:
  • EMPTY blocks have address ranges, and fixed indentation and duplicates
  • ; Next union/fragment comments have fixed indentation and placement
• RGBGFX supports - for stdin and stdout

Fixed:

• RGBGFX terminates if opening a file fails
• Fix some possible build errors on some systems
• RGBLINK could crash when merging SECTION FRAGMENTs that aren't in ROM
• RGBLINK mangles absolute SECTION names to support SDCC "areas"
• RGBGFX could crash on empty palette slots with "Assertion 'this->_M_is_engaged()' failed."; we hardened our test configuration to catch more bugs like this

A big thank you to @eievui5 and @pinobatch for additional testing during the development of this version, as well as @rlewicki for some improvements to the codebase!

v0.6.0

Our website received a big facelift, please check it out at https://rgbds.gbdev.io! Thanks to @ISSOtm and @avivace for the work on this.
While some pages have been moved around, all URLs under /docs have been preserved.

Deprecated:

• m: MACRO syntax; use MACRO m.
• __FILE__ and __LINE__.
• rgbasm -h and -L will soon become the default behavior; please use rgbasm -H and -l respectively to opt into the current behavior.
• rgbgfx -h has been renamed to the less confusing rgbgfx -Z.

Added:

• RGBGFX has been massively overhauled! Please check out the new docs for full details, but notably:
  • The alpha channel is now handled in a sensible and useful way.
  • Palettes can be manually specified without having to muck with PNG embedded palettes using -c!
  • rgbgfx -r can also "reverse" the process and generate a PNG from the binary data.
  • "At-files" allow storing the flags e.g. next to the image, instead of centralized within your Makefile/build script.
  • State-of-the-art packing algorithm ensures optimal palette generation 😎
  • Special thanks to @aaaaaa123456789 for randtilegen, used for testing; @eievui5, @MarkSixtyFour, and @Rangi42 for review and testing!
  • There's an egg somewhere in there?
• Unsigned right shift operator >>>!
• Binary AND & can now be constant if applied to a symbol with the right alignment.
• rgbasm -Q or OPT Q configures the fixed-point precision, which is still 16 by default (e.g. -Q8 uses Q24.8).
• FMOD function for fixed-point modulo.
• Precise fixed-point literals like 12.34q8 override the current Q option value.
• Fixed-point functions take an optional final argument to specify their precision, overriding the current -Q option.
• @ and _NARG are considered undefined (e.g. by DEF) when they have no value.
• rgbasm -P allows automatically pre-including a file before the source file; for example, to define constants used throughout the codebase.
• SECTION(symbol) evaluates to the name of symbol's section.
• rgbasm -r sets the maximum recursion depth, not the minimum failure depth (off by one).
• OPT r.
• -Wunmapped-char=0/1/2 warning for characters not in the charmap. Level 1 ignores unmapped characters in a non-default charmap if it's empty, level 2 does not.
• \@ only increments its expanded value when used, so merely adding or removing MACRO, REPT, or FOR blocks will not affect generated symbols.
• RGBASM will warn if a command-line argument overrides a previous one, for example -o.
• RGBLINK is able to link SDCC object files.
• RGBLINK will now report floating sections' names when using -O.
• RGBLINK will omit symbol names from the .map file when using -M.
• RGBLINK will not output anonymous labels in the .sym file, to comply with the spec.
• RGBLINK will report EMPTY space between sections in the .map file, and total used+empty space at the end.
• A .clang-format, though it it only applied to C++ files; we are gradually transitioning away from checkpatch style.

Removed:

• PRINTT, PRINTI, PRINTV, PRINTF (use PRINT/PRINTLN instead)
• _PI
• SET as an assignment operator (use = instead)
• rgbgfx -D, -f, and -F were not useful anymore

Changed:

• RGBASM trigonometry functions now divide a circle into 1.0 turns, not 65536.0 so-called "binary degrees".
• Please prefer rgbasm -I over rgbasm -i, for consistency with other tools (mainly C compilers); -i will be phased out in a future release.
• man pages are now all in a single directory; this affects the release tarballs!
• .map files now have a more useful free/used space summary at the end
• .map files are now indented using tabs (requested in #1012)

Fixed:

• rgblink -S rejected a lot of valid arguments.
• rgblink -O could "forget" ROM0 if no such sections were defined, offsetting the entire file.
• Whitespace is now trimmed in macro arguments, even after line continuations.
• All *UTC* symbols could contain local time instead on some systems.
• contrib/gbdiff.bash correctly handles spaces in its arguments (oops)
• Version number will always be properly updated when building with CMake.
• RGBASM now warns when specifying options that override eachother.
• rgbasm -b and -g were broken.
• Tests did not pass on the release tarballs.
• Math symbols could render incorrectly in rgbasm(5).
• RGBDS should be portable to more systems now.
• RGBASM has been optimized slightly yet again.
• Rephrased some documentation for clarity.

v0.6.0-rc2

Our website received a big facelift, please check it out at https://rgbds.gbdev.io! Thanks to @ISSOtm and @avivace for the work on this.
While some pages have been moved around, all URLs under /docs have been preserved.

Deprecated:

• m: MACRO syntax; use MACRO m.
• rgbasm -h and -L will soon become the default behavior; please use rgbasm -H and -l respectively to opt into the current behavior.
• rgbgfx -h has been renamed to the less confusing rgbgfx -Z.

Added:

• RGBGFX has been massively overhauled! Please check out the new docs for full details, but notably:
  • The alpha channel is now handled in a sensible and useful way.
  • Palettes can be manually specified without having to muck with PNG embedded palettes using -c!
  • rgbgfx -r can also "reverse" the process and generate a PNG from the binary data.
  • "At-files" allow storing the flags e.g. next to the image, instead of centralized within your Makefile/build script.
  • State-of-the-art packing algorithm ensures optimal palette generation 😎
  • Special thanks to @aaaaaa123456789 for randtilegen, used for testing; @eievui5, @MarkSixtyFour, and @Rangi42 for review and testing!
  • There's an egg somewhere in there?
• Unsigned right shift operator >>>!
• Binary AND & can now be constant if applied to a symbol with the right alignment.
• rgbasm -Q or OPT Q configures the fixed-point precision, which is still 16 by default (e.g. -Q8 uses Q24.8).
• Precise fixed-point literals like 12.34q8 override the current Q option value.
• FMOD function for fixed-point modulo.
• rgbasm -r sets the maximum recursion depth, not the minimum failure depth (off by one).
• OPT r.
• -Wunmapped-char warning for characters not in the charmap.
• \@ only increments its expanded value when used, so merely adding or removing MACRO, REPT, or FOR blocks will not affect generated symbols.
• RGBLINK is able to link SDCC object files.
• RGBLINK will now report floating sections' names when using -O.
• RGBLINK will omit symbol names from the .map file when using -M.
• RGBLINK will report EMPTY space between sections in the .map file.
• A .clang-format, though it it only applied to C++ files; we are gradually transitioning away from checkpatch style.

Removed:

• PRINTT, PRINTI, PRINTV, PRINTF (use PRINT/PRINTLN instead)
• _PI
• SET as an assignment operator (use = instead)
• rgbgfx -D, -f, and -F were not useful anymore

Changed:

• man pages are now all in a single directory; this affects the release tarballs!

Fixed:

• rgblink -S rejected a lot of valid arguments.
• rgblink -O could "forget" ROM0 if no such sections were defined, offsetting the entire file.
• Whitespace is now trimmed in macro arguments, even after line continuations.
• All *UTC* symbols could contain local time instead on some systems.
• contrib/gbdiff.bash correctly handles spaces in its arguments (oops)
• Version number will always be properly updated when building with CMake.
• Math equations could render incorrectly in rgbasm(5).
• RGBDS should be portable to more systems now.
• RGBASM has been optimized slightly yet again.
• Rephrased some documentation for clarity.

v0.6.0-rc1

Our website received a big facelift, please check it out at https://rgbds.gbdev.io! Thanks to @ISSOtm and @avivace for the work on this.
While some pages have been moved around, all URLs under /docs have been preserved.

Deprecated:

• rgbasm -h and -L will soon become the default behavior; please use rgbasm -H and -l respectively to opt into the current behavior.
• rgbgfx -h has been renamed to the less confusing rgbgfx -Z.

Added:

• RGBGFX has been massively overhauled! Please check out the new docs for full details, but notably:
  • The alpha channel is now handled in a sensible and useful way.
  • Palettes can be manually specified without having to muck with PNG embedded palettes using -c!
  • rgbgfx -r can also "reverse" the process and generate a PNG from the binary data.
  • "At-files" allow storing the flags e.g. next to the image, instead of centralized within your Makefile/build script.
  • State-of-the-art packing algorithm ensures optimal palette generation 😎
  • Special thanks to @aaaaaa123456789 for randtilegen, used for testing; @eievui5, @MarkSixtyFour, and @Rangi42 for review and testing!
  • There's an egg somewhere in there?
• Unsigned right shift operator >>>!
• Binary AND & can now be constant if applied to a symbol with the right alignment.
• RGBLINK will now report floating sections' names when using -O.
• OPT r
• A .clang-format, though it it only applied to C++ files; we are gradually transitioning away from checkpatch style.

Removed:

• PRINTT, PRINTI, PRINTV, PRINTF (use PRINT/PRINTLN instead)
• _PI
• SET as an assignment operator (use = instead)
• rgbgfx -D, -f, and -F were not useful anymore

Changed:

• man pages are now all in a single directory; this affects the release tarballs!

Fixed:

• rgblink -S rejected a lot of valid arguments.
• rgblink -O could "forget" ROM0 if no such sections were defined, offsetting the entire file.
• Whitespace is now trimmed in macro arguments, even after line continuations.
• All *UTC* symbols could contain local time instead on some systems.
• contrib/gbdiff.bash correctly handles spaces in its arguments (oops)
• Version number will always be properly updated when building with CMake.
• Math equations could render incorrectly in rgbasm(5).
• RGBDS should be portable to more systems now.
• RGBASM has been optimized slightly yet again.

v0.6.0-welease-cnyandidayte

April Fools! Please do not use this release for anything serious, it's wildly incompatible—just a joke..!

We understand that assembly is a fairly dry and old-school language. We understand that it does not necessarily appeal to the modern programmer (and their socks) anymore.

Therefore, we have decided to experiment and shake up the instruction syntax a little bit. UTF-8 characters are now accepted as input, a handful of instructions have been renamed—as have been the registers, and more! 👀 We invite you to check out the new documentation for the full list of changes~

Pwease be warned that the new syntax is a teeny tiny bit expewimental, and so any ewwows should be wepowted to youw neawest /dev/null! ^w^

🐈

v0.5.2

Deprecated:

• SET for mutable definitions is deprecated; use =

Added:

• Bash completion scripts for rgbasm, rgblink, rgbfix, and rgbgfx!
• RGBFIX won't warn when overwriting a byte with the same value
• rgbfix -O to silence all "overwriting non-zero byte" warnings
• rgblink -S "scrambles" bank assignments to help find broken assumptions in your code
• Unindented macro invocations will be hinted at when encountered
• -Wnumeric-string=0|1|2 warns about use of strings as numbers
• Compound assignment for variables (e.g. DEF x += 1 for DEF x = x + 1)
• ! negates condition codes z/nz/c/nc
• Allow _ in gfx literals, e.g. `0123_3210

Updated:

• Zsh completions synced with RGBDS changes
• rgbfix -m MBC3+TIMER implies BATTERY, warning if not specified
• Symbol interpolation is now more prominently described
• -Wtruncation can be made less strict; use -Wtruncation=1 for more lax behavior

Fixed:

• rgbfix -m MBC3+TIMER+BATTERY didn't work
• LOAD offset wasn't reset when switching sections
• PUSHS inside UNION should work as expected
• Syntax errors after the first one were silenced
• Some syntax errors could break parsing
• Some invalid local labels could be defined
• Incorrect error text when merging misaligned sections
• Fixed-point formatting was slightly imprecise
• STRFMT documentation was cut in the middle
• Wrong rgbfix -m help text
• Man page formatting and grammar blunders
• Internal code cleanup

v0.5.1

Don't forget to check out our docs for more details on the updated functionality!

Added:

• RGBFIX now supports the homebrew TPP1 mapper! (The emulators BGB 1.5.9 and SameBoy 0.14.3 do too)
• New \<10> and \<num_sym> macro arg syntaxes
• SIZEOF("section") and STARTOF("section")
• CHARLEN and CHARSUB for working with charmap output units
• OPT L, OPT W, and OPT h
• REDEF EQU
• Linker scripts can use character escapes in section names ("\n \r \t \" \\")
• RGBFIX now reports when it's overwriting non-zero header bytes, helpful for spotting mistakes (thanks @GreenAndEievui!)
• rgbfix -m help will list the accepted MBC names
• rgbfix -m accepts $-prefixed hex literals

Changed:

• Parentheses in macro args implicitly escape commas now, like C. For example, macro STRCAT("foo", "bar") used to be 2 arguments, now it's only one!
• STRSUB and CHARSUB allow negative start positions, relative to the end of the string
• STRSUB's second parameter can be omitted to read until the end of the string
• A lot more errors are non-fatal now
• Any constant expression equal for $FF00 can be substituted to $ff00 in ld [$ff00 + c], a and ld a, [$ff00 + c]; and arbitrary whitespace, line continuations, and block comments are allowed

Removed:

• LOAD FRAGMENT had buggy behavior, and its use cases can be done differently

Fixed:

• Symbols in some SECTION UNION/FRAGMENT could be missing from the .sym file
• Interpolations could recurse infinitely outside of strings
• ld hl, sp - <expr> was broken in 0.5.0 (workaround: ld hl, sp + -<expr>)
• $ff00 + constant (or any symbol name starting with "c") would cause a syntax error since 0.4.2 (workarounds: ($ff00) + constant, constant + $ff00, or $ff00 + /**/ constant)
• Fixed a lexer bug that could crash RGBASM on "piped" input files
• jr could be incorrect within SECTION FRAGMENT
• PUSHS didn't reset the section scope correctly (regression), and didn't save the LOAD state
• REDEF EQUS had a few bugs
• RGBFIX incorrectly parsed options on some platforms
• RGBLINK should no longer leak memory
• Fixed some compiler warnings, notably on 32-bit platforms and macOS
• The source now uses _ISO_C11_SOURCE; this notably fixes building on FreeBSD (see #789 for more info)

Attention downstream packagers

An "annex" program, rgbobj, has been developed as an equivalent of objdump for RGBDS. It's not integrated with the rest of the codebase, as it's written in Rust. If you are distributing pre-built binaries, you may want to bundle it with RGBDS regardless.