Rgbds Versions Save

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

Please welcome two new contributors, @Rangi42 and @dannye! Rangi did more than half of the work on this release—our biggest one yet!

Changes since v0.5.0-rc1:

• New DEF <name> EQU/EQUS/SET/= ... syntax for defining constants! The old syntax will still be supported, but may eventually be phased out.
• Fix ALIGN[1] being ignored
• Fix jr in a LOAD FRAGMENT
• Fix an ELIF condition right after a taken IF/ELIF block still being evaluated
• Improve some error messages and documentation
• RGBLINK outputs USED space at the end of a .map file

Deprecated:

• _PI wasn't useful, so it's deprecated now
• PRINTT, PRINTV, PRINTF and PRINTI are obsoleted by the new PRINT/PRINTLN and STRFMT

Known issues:

• Regression: Expanding recurse EQUS "recurse" or recurse EQUS "\{recurse\}" hangs rgbasm (#696)
• .sym files miss some symbols from multiple SECTION UNIONs/FRAGMENTs (#809)

Added:

• New MACRO <name> syntax for defining macros! The old syntax will still be supported for a couple versions, but may eventually be phased out.
• RGBFIX can now be used in pipelines! Example: rgblink -o - obj/header.o obj/game.o | rgbfix -v -p0xFF >bin/dinos_with_lasers.gb
• {symbol} interpolation outside of strings, similar to macro args (differs from the pre-0.4.2 behavior!!)
• More complex format specifiers are now allowed in symbol interpolations
• Anonymous labels
• Environment var SOURCE_DATE_EPOCH can be used for reproducible builds
• Underscores can be used in numeric literals (e.g. %1101_1110_1010_1101)
• New string functions STRRIN, STRRPL and STRFMT
• \# to get all of a macro's arguments
• """Multi-line string literals"""
• FOR blocks!
• BREAK exits REPT and FOR early
• POW and LOG fixed-point functions
• ** exponent operator (for integers)
• REDEF to redefine EQUS much more conveniently
• RL has been reintroduced alongside RB and RW
• LOAD UNION and LOAD FRAGMENT

Changed:

• Syntax errors will now be more verbose! Be careful that YMMV depending on the Bison version that RGBASM was compiled with.
• Syntax errors are no longer fatal! If a line contains a syntax error, RGBASM will discard it and attempt to continue with the next line.
• RGBFIX's -m now accepts MBC names
• More symbols will be available in the .sym and .map files
• Slack totals are now included in the .map files
• Interaction of quotes and macro args should be more intuitive
• ds can now repeat patterns, not just a single byte
• Global labels can now be indented, not just local ones
• Trailing commas are allowed for most "list" directives, such as db
• STRCAT can now concat any amount of strings
• LOAD blocks cannot create ROM sections anymore (#576)
• ROUND, FLOOR and CEIL fixed-point builtins were present but undocumented
• Macro arguments can now be shifted by a negative amount, "un-shifting" them
• Macro args can now be empty, though this causes a warning

Removed:

• GLOBAL and XDEF keywords (deprecated aliases of EXPORT)
• Colon-less global labels
• *-comments
• rgbasm -v no longer prints the elapsed time (use time for that)

Fixed:

• Enabled several optimizations that should improve performance, especially RGBASM
• SECTION FRAGMENTs now respect their constraints at their respective beginnings, not as a whole
• Line numbers could be incorrect on Windows
• RGBASM will explicitly reject more than one input file, rather than silently ignore them
• Macro args weren't ignored in block comments
• Fixed a rare crash with unterminated REPT/FOR blocks
• Fixed incorrect handling of text after MACRO, ENDM and ENDR tokens
• Can't start a new section if another with the same name has been PUSHS'd
• ds N, @ could produce incorrect results
• ELIF and ELSE were allowed after ELSE
• . was treated as a label
• Performance of gbdiff.bash improved significantly
• Defining an EQUS after referencing it is now an error
• Passing -t and -O to RGBLINK generated an output too large

Attention downstream packagers

The yacc dependency has been changed to GNU Bison! Our Makefile relies on bison -V to conditionally enable some features (src/check_bison_ver.sh) and our CMakeLists on the Bison CMake package, so both should be compatible with many versions, at least 3.0 (3.0.4 successfully tested). Please report breakage in our issue tracker.

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

Please welcome two new contributors, @Rangi42 and @dannye! Rangi did more than half of the work on this release—our biggest one yet!

Deprecated:

• _PI wasn't useful, so it's deprecated now
• PRINTT, PRINTV, PRINTF and PRINTI are obsoleted by the new PRINT/PRINTLN and STRFMT

Known issues:

• An ELIF condition right after a taken IF/ELIF block is still evaluated (#764)
• Regression: Expanding recurse EQUS "recurse" hangs rgbasm (#696)

Added:

• New MACRO <name> syntax for defining macros! The old syntax will still be supported for a couple versions, but will eventually be phased out.
• RGBFIX can now be used in pipelines! Example: rgblink -o - obj/header.o obj/game.o | rgbfix -v -p0xFF >bin/dinos_with_lasers.gb
• {symbol} interpolation outside of strings, similar to macro args (differs from the pre-0.4.2 behavior!!)
• More complex format specifiers are now allowed in symbol interpolations
• Anonymous labels
• Environment var SOURCE_DATE_EPOCH can be used for reproducible builds
• Underscores can be used in numeric literals (e.g. %1101_1110_1010_1101)
• New string functions STRRIN, STRRPL and STRFMT
• \# to get all of a macro's arguments
• """Multi-line string literals"""
• FOR blocks!
• BREAK exits REPT and FOR early
• POW and LOG fixed-point functions
• ** exponent operator (for integers)
• REDEF to redefine EQUS much more conveniently
• RL has been reintroduced alongside RB and RW
• LOAD UNION and LOAD FRAGMENT

Changed:

• Syntax errors will now be more verbose! Be careful that YMMV depending on the Bison version that RGBASM was compiled with.
• Syntax errors are no longer fatal! If a line contains a syntax error, RGBASM will discard it and attempt to continue with the next line.
• RGBFIX's -m now accepts MBC names
• More symbols will be available in the .sym and .map files
• Slack totals are now included in the .map files
• Interaction of quotes and macro args should be more intuitive
• ds can now repeat patterns, not just a single byte
• Global labels can now be indented, not just local ones
• Trailing commas are allowed for most "list" directives, such as db
• STRCAT can now concat any amount of strings
• LOAD blocks cannot create ROM sections anymore (#576)
• ROUND, FLOOR and CEIL fixed-point builtins were present but undocumented
• Macro arguments can now be shifted by a negative amount, "un-shifting" them
• Macro args can now be empty, though this causes a warning

Removed:

• GLOBAL and XDEF keywords (deprecated aliases of EXPORT)
• Colon-less global labels
• *-comments
• rgbasm -vno longer prints the elapsed time (use time for that)

Fixed:

• Enabled several optimizations that should improve performance, especially RGBASM
• SECTION FRAGMENTs now respect their constraints at their respective beginnings, not as a whole
• Line numbers could be incorrect on Windows
• RGBASM will explicitly reject more than one input file, rather than silently ignore them
• Macro args weren't ignored in block comments
• Fixed a rare crash with unterminated REPT/FOR blocks
• Fixed incorrect handling of text after MACRO, ENDM and ENDR tokens
• Can't start a new section if another with the same name has been PUSHS'd
• ds N, @ could produce incorrect results
• ELIF and ELSE were allowed after ELSE
• . was treated as a label
• Performance of gbdiff.bash improved significantly
• Defining an EQUS after referencing it is now an error
• Passing -t and -O to RGBLINK generated an output too large

Attention downstream packagers

The yacc dependency has been changed to GNU Bison! Our Makefile relies on bison -V to conditionally enable some features (src/check_bison_ver.sh) and our CMakeLists on the Bison CMake package, so both should be compatible with many versions, at least 3.0 (3.0.4 successfully tested). Please report breakage in our issue tracker.

New:

• We have a website! Accordingly, HTML documentation is no longer distributed in the source or in the release artifacts below. All old documentation links now redirect to the latest release's documentation
• You may also have noticed the repo has been moved to gbdev instead of rednex! Don't worry, the same people are in charge.
• /* Block comments! */
• Whitespace is now allowed between the brackets in [bc], [de] and [hl], also allowing [\1] to work.
• The second number argument to INCBIN can now be omitted, going up to the end of the file
• The argument to rb and rw is now optional, defaulting to 1
• RGBASM and RGBLINK can both use stdin as input, and stdout as output (support yet to come to RGBFIX)
• zsh completion scripts are available in the contrib/ folder. (If you want to make bash ones, apply in #620)

Changes:

• Nested macros are now invalid, but a workaround is possible
• The lexer has been fully rewritten, which should make additions to it easier, and improve performance
• Removed arbitrary limits on charmap size and name length
• STRSUB will no longer warn when taking 0 characters at the end of the string
• RGBLINK will no longer report errors stemming from other errors
• RGBASM is now able to write more jrs without relying on RGBLINK, leading to smaller .o files and faster linking
• INCBIN should produce a slightly more useful error message
• A bunch of quality-of-life improvements for downstream packagers, especially using CMake
• Assertions have been removed from release builds, improving performance slightly
• charmaps now allocate memory as nodes are allocated, greatly reducing their size (by a factor of ~8)
• Documentation now mentions that SHIFT updates _NARG

Fixes:

• Two 6+ year-old crashing bugs have been fixed. They were thankfully rare, but should no longer be a problem now.
• LOAD blocks could produce incorrect output when at the beginning or end of a section
• __FILE__ caused syntax errors if the file name contained a quote
• jr in certain circumstances could crash RGBLINK
• Fixed inconsistent version numbering between the Makefile and the CMakeLists
• Documentation failed to mention SECTION FRAGMENT
• Documentation incorrectly listed bit 7 of symbol type as being the unionized section flag, and failed to mention the section fragment flag
• Documentation erroneously used to claim that symbol names could begin with a digit
• Error out when using align outside of a SECTION, or when using shift outside of a macro... instead of crashing
• Fixed a potential RGBASM crash with very large expressions
• Fixed overwriting a builtin symbol succeeding after insisting enough
• Fixed a crash when subtracting two invalid labels
• Fixed using _NARG outside of a macro crashing RGBASM

Note to Windows users

Release 0.4.1's binaries were compiled with MSVC instead of MinGW, giving apparently better results. Unfortunately, there is currently a problem with MSVC (not that we can do anything about it, yay!), so the binaries below are MinGW again. 0.4.3 should be compiled with MSVC again, though.

This is a pre-release! Do not expect this to be fully stable yet; please read the explanation at the end of the changelog.

New:

• We have a website! Accordingly, HTML documentation is no longer distributed in the source or in the release artifacts below. All old documentation links now redirect to the latest release's documentation
• You may also have noticed the repo has been moved to gbdev instead of rednex! Don't worry, the same people are in charge.
• Whitespace is now allowed between the brackets in [bc], [de] and [hl], also allowing [\1] to work.
• The second number argument to INCBIN can now be omitted, going to the end of the file

Changes:

• The lexer has been fully rewritten, which should make additions to it easier, and improve performance
• Removed arbitrary limits on charmap number and length of name
• STRSUB will no longer warn when talking 0 characters at the end of the string
• RGBLINK will no longer report errors stemming from other errors
• RGBASM is now able to write more jrs without relying on RGBLINK, leading to smaller .o files and faster linking
• INCBIN should produce a slightly more useful error message
• A bunch of quality-of-life improvements for downstream packagers, especially using CMake
• Assertions have been removed from release builds, improving performance slightly
• charmaps now allocate memory as nodes are allocated, greatly reducing their size (by a factor of ~8)

Fixes:

• Two 6+ year-old crashing bugs have been fixed. They were thankfully rare, but should no longer be a problem now.
• LOAD blocks could produce incorrect output when at the beginning or end of a section
• __FILE__ caused syntax errors if the file name contained a quote
• jr in certain circumstances could crash RGBLINK
• Fixed inconsistent version number between the Makefile and the CMakeLists
• Documentation failed to mention SECTION FRAGMENT
• Documentation incorrectly listed bit 7 of symbol type as being the unionized section flag, and failed to mention the section fragment flag

Why a pre-release?

The lexer, which is the core component of RGBASM, has been fully rewritten. Being also a very low-level piece of code, it's prone to crashing. The rewrite may also have changed some behavior (here is a known incompatibility). This pre-release is essentially to test the waters: see if anything breaks, assess how to handle it, and make 0.4.2 a good and stable release.

Why rewrite it? Didn't it work fine?

In short, the old lexer worked "fine" if you didn't look at it the wrong way. It was also hard to edit, and blocked a bunch of issues, 6 open at the time of writing. Further, the performance wasn't great, and we're hoping to improve it with this release.

It sucks! Stuff broke and it's slow!

Alright, we'd love to hear back about that. Check the "issues" tab near the top of the page for anything similar to your problem, otherwise open a new issue. We'd preferably need the code that you ran RGBASM on, so that we can see why it's slow.

⚠️ ATTENTION WINDOWS USERS ⚠️

RGBDS does not ship the Visual C++ runtime libraries anymore; if you don't have the 2019 ones (you should get an error message about some vcruntime DLL missing), you can install them from Microsoft's website.

The version that brought GBDK support! I mean, brought them our support?

New:

• RGBLINK tries to report more errors at once
• Two-argument ALIGN[] to additionally specify an offset
• Mid-section align directive
• A RGBLINK option to prevent padding its output
• A warning for empty db/dw/dl in ROM sections
• (Overdue) documentation of -MG, -MP, -MT and -MQ
• RGBDS can now be compiled using CMake, if you prefer; note that the Makefile is still the main build method
• RGBDS should be able to be compiled using MSVC now

Deprecations:

• -Wobsolete is now enabled by default! This is not a deprecation, but it should make it easier for you to notice deprecated changes
• *-comments are now deprecated, please use ;-comments instead

Changes:

• Consistently with RGBLINK, RGBASM now allows constants to be referenced prior to their definition (see #496 for details)
• RGBASM ISO 8601 symbols now correctly separate time with colons
• Macro can now have an arbitrary number of arguments; a sanity limit has been arbitrarily set to 99,999, which should be enough for everyone

Fixes:

• Fixed RGBLINK incorrectly computing PC inside LOAD blocks
• Fixed BANK(@) outside of sections crashing RGBASM
• Fixed BANK() of a constant crashing RGBLINK
• Fixed period not being accepted as second character of a label name
• Fixed possible RGBASM crash from an empty input file
• Fixed modulo by 0 crashing RGBLINK
• Fixed user-after-free from errors in INCLUDEd linker scripts
• Fixed 0-byte sections being incorrectly printed in .map files
• Fixed a rare RGBASM hang when deleting symbols
• Fixed uninitialized memory reads with -MT and -MQ
• Fixed incorrect explanation of pop af instruction
• Fixed incorrect reporting of overlapping sections
• Fixed incorrect documentation of unary !
• Fixed documentation not updated regarding behavior of RGBLINK's -t and -w
• Fixed implicitly relying on -fcommon: RGBDS now builds with GCC 10's default configuration
• RGBDS no longer relies on 32-bit int, making it more portable to e.g. DOS

Note for Windows users: The binaries below have been compiled on Windows using MSVC, instead of cross-compiled. No difference has been found after some testing, but if something breaks, please open an issue!

Very big release! This includes a lot of bug fixes, large portions of the code rewritten, and some features deprecated or removed. We hope not to break anyone's code, but we won't keep bugs for compatibility's sake. If your code broke and the change isn't in the list below, please open an issue in our tracker.

New:

• Added warning flags to RGBASM: by default, most warnings are disabled now. Please see man rgbasm for more info
• "LOAD blocks" simplify writing code that should run in RAM; users of unofficial program rgbbin may want to look into this
• Shiny new assertions, whose checking can be deferred to RGBLINK
• "Unionized" sections offer a sort of cross-file UNION
• More flags in the RGBASM -M family for better automatic dependency management
• Bracketed symbols can be nested (example)
• SHIFT can now shift multiple times at once
• Long options (such as --version for -V) have been added to all programs
• RGBASM now accepts escape \r in strings
• INCBIN now works with unseekable files as well

Deprecations and removals:

• As part of a cleanup effort, features previously marked as deprecated have been removed, such as the CODE section type
• Labels not starting with a dot nor followed by a colon have been deprecated; in a future version, they will be treated as macro invocations
• Deprecated OPT z in favor of new and more consistent OPT p
• Deprecated GLOBAL symbol (and its synonym XDEF), as it has the same effect as EXPORT
• Removed "section-local" charmap (deprecated in 0.3.9)

Changes:

• .sym and .map files are now output sorted
• The argument to rst does not need to be known to RGBASM anymore (so labels can be used at all times)
• Only labels may have dots in their name now
• Labels beginning with a dot may have whitespace before their declaration
• DEF() now accepts labels as arguments
• ROMX and WRAMX sections can be used in RGBLINK's -t and -w modes, respectively
• RGBLINK will report more detailed "error stacks", like RGBASM
• RGBASM tries harder to treat expressions as "constant"
• Second byte of stop can be specified without resorting to using db

For further information on new or changed features, please refer to our documentation.

Fixes:

• gbz80(7) had incorrect flag descriptions for sub
• Arguments to RGBASM -i have a / implicitly appended if they don't end with one
• = was treated as identical to set, so = 7, [hl] was valid; this has been fixed
• Corrected wrong line reporting with REPT blocks
• Changing sections now resets the label scope
• Built-ins and symbols referenced in link-time expressions can no longer be PURGEd
• __ISO_8601_UTC__ and __ISO_8601_LOCAL__ symbols fixed on Windows (with a caveat for the latter)

Notes:

• RGBDS is now compiled with optimizations by default. To disable optimizations, use make CFLAGS=-O0. To compile in "debug mode", build using make develop instead of make; this requires a fairly specific configuration, though, and might not work for you.
• Performance of RGBASM and RGBLINK should have been improved (beyond the above), but we would need help from someone experienced with YACC / Bison to make more significant changes
• Reliability across systems and platforms has been improved:
  • RGBASM parser grammar has been cleaned up
  • Undefined behavior has been removed from various programs
• Nightly builds are available for each commit now ("Actions" tab ⇒ "Regression testing" ⇒ click on the commit name)
• Docs have received an overhaul, including a more responsive and mobile-friendly styling
• General system stability improvements to enhance the user's experience

This release is merely a hotfix for 0.3.9 that undoes the mistake that __RGBDS_MAJOR__ etc. symbols were not being defined. Please upgrade from 0.3.9.

IMPORTANT This version is missing definitions of the __RGBDS_MAJOR__ etc. symbols. Please use 0.3.10 instead, which rectifies this problem (and does not introduce additional changes).

rgbasm:

• Enforced non-overwritability of some symbols
• - now allows assembling a file from stdin
• Allowed PUSHS to be used before a section declaration
• Prevented generating symbols with invalid names using macros
• Fixed the precedence of the == operator
• Added different output formats to bracketed symbols
• Fixed a parsing bug with some nested if constructs
• Improved error reporting now reports actual file line numbers as well as string expansions
• Added multiple charmaps (be careful as some feature has been deprecated, a warning has been added about it)
• Fixed bug with line numbers in some IF/ELIF/ELSE blocks
• Added configurable recursion limit to prevent infinite loops
• Fixed unary NOT being a no-op on constant expressions
• Made behavior consistent whether outputting a .o file or not
• Allowed tabs to be used before line continuations
• Allowed sections without content to be placed anywhere
• Made error message more explicit with macro argument 0

rgblink:

• Improved many error messages

rgbgfx:

• Added an option to use the GBC's color profile

other:

• Added more tests
• Did some internal cleanup
• Improved cross-platform compatibility of test suite

Also fixed a lot more bugs and crashes in rgbasm and rgblink.

• rgbasm and rgblink

  • Report correct filename and line number of symbols in error messages.
  • Fix long-standing issue of ambiguity in constant parsing.
  • Fix behaviour of parser regarding newlines and \.

• rgbfix

  • Fix regression on calculation of ROM checksum.

• Other

  • Documentation updates and cleanups.
  • Some new tests.
  • Re-enabled OS X build CI job.

• rgbasm and rgblink

  • Allow JR to numeric constants.
  • Fix behaviour of @ (including fixing the bug introduced in 0.3.6 related to JR).

• Other

  • Create target with most GCC warnings enabled for debug purpopses.
  • Several extra checks in the code.