RGBASM does this itself, so should not output sections with 16-bit
alignment, but an invalid object file could otherwise cause
`getPlacement` to infinitely loop.
Since SRAM sections start from 0, we had been using a signed
`int8_t curScrambleSRAM` counter to allow 0 as a scrambled bank,
but this actually just placed all floating SRAM sections in bank 0.
Commit 21eaa2d2cc missed some
intentional unsigned underflow that is needed to set `nbTilesInBank`.
Without it, some of the randomly-seeded RGBGFX tests, such as
`./rgbgfx_test seed8.bin -b 207 -N 54,256`, can fail with "Color
mismatch after round-tripping" errors.
- If both banks 0 and 1 were completely filled, then
`assume(bank == 0)` would false and potentially crash.
- If the input image had fully-background tiles, they would be
incorrectly counted towards `nbTiles` and could cause the
"Image contains N tiles, exceeding the limit" check to fail.
`tileData[realY + 1 % options.bitDepth]` relied on order of
operations and the fact that `1 % 1 == 0` but `1 % 2 == 1` for
correct indexing. However, it was not obvious at first glance,
and confusable with the more common `(base + offset) % size`
pattern. (And would need changing anyway if we ever support 4bpp.)
Negative macro arguments count from the end, i.e. `\<-1>`
is equivalent to `\<_NARG>`, even after `shift`ing them.
Negative arguments cannot be used to access shifted values.
Creating a `Symbol` with `type = SYM_LABEL` but `section = nullptr`
is inconsistent and dangerous. I was not able to cause any buggy
behavior so far, but it's safer and reasonable to not create such
a symbol in the first place.
The main consequence is that `DEF(LabelOutsideSection)` will now
evaluate as 0.
This value "has no impact unless `INSTALL_PARALLEL` is enabled",
and since our install procedure is so simple, I don't think we need
to add that. (The `make install` commands don't use `-j` either.)
- Use CTest labels to filter tests ("internal"/"external", "free"/"nonfree",
and individual tool+project names) instead of defining `TESTS_RUN_NONFREE`
- Allow each external test to run independently in CTest
- Remove the unused no-op `fetch-test-deps.sh --only-internal` option
We shouldn't assume how the user wants to install things.
In particular, `--break-system-packages` is egregious.
---------
Co-authored-by: Rangi <[email protected]>
We only use `$<INSTALL_PREFIX>`` when cross-compiling for MinGW on Linux,
so the relevant block is now wrapped in `if(WIN32)`
so a user can more easily lower the `cmake_minimum_required` version.
- Fix logic for color set comparison (which affects sorting them)
- Prune color sets which are proper subsets of newly-encountered ones
(a comment implied we were already doing this, but we weren't)
- Add more verbose logging to debug this behavior
Instead of reading 64 characters at a time into a rolling buffer
as `shiftChar()` is called, we read 8192 characters at a time into
a complete buffer before any `peek()`/`shiftChar()` operations.
This will let us use C++20 features that GCC 9's experimental
C++20 support did not yet cover, such as "concepts".
This reverts some commits:
- 6bcd79b997
- d5ce5329ea
- 728d14879b
Commit 63a911e657 switched
to `-std=c++20` since at the time we required GCC 10 or higher.
Commit d5ce5329ea partially reverted
to `-std=c++2a` since we once again support GCC 9, which did not
yet handle `std=c++20`.
The latter is not a Bash built-in,
and some environments turn out to produce non-conforming
return codes.
`type` is provided by Bash itself,
so we can rely on it better.
- Add more `assume()` checks in the lexer
- Replace double negative "`disable* = false`" with "`enable* = true`"
- Naming convention of "`std::deque<> *Stack`" when relying on
`.push_front()` and `.pop_back()`
MSBuild is slow, and its output is hard to parse visually
(it's all interwoven, like Make without `--output-sync`).
Since we use CMake anyway, we don't care about the build system.
We can, so let's not ask if we should!
More realistically, we can right now so it's nice to mark that we do, but this is subject to be re-evaluated if any later changes conflicts with this.
Note also that this only affects the binaries we distribute with our releases!
It may very well be possible to compile RGBDS on even older versions of Mac OS X if you have the appropriate compiler setup;
we're just not testing it nor offering such binaries ourselves, but third-party packagers are welcome to do so.
(Looking at you, TigerBrew! ;)
- Do not error about local labels following keywords in skips or captures (fixes#1955)
- Do not incompletely attempt to handle line continuations in skips (fixes#1956)
- Rename `skipToLeadingIdentifier` to `skipToLeadingKeyword`, refactor to merge
`skipToEOL` into it, and use it for both skips and captures
Automatically grabs and compiles libpng, and avoids having hacky lines in our Makefile
(the compiler specification *should* be orthogonal to the build target!)
Also move the MinGW package install to the `install_deps.sh` script,
to move logic off of the YAML.
- Turns out the variable wasn't being set, and thus the flags weren't being passed
- Passing the flags via those variables is basically a bad idea, and it
turns out to break libpng's config script
- The flags need to be passed during link as well, otherwise the binary
isn't linked as a fat one
Fixes#1916
This claim was true in v0.4.2, but intentionally changed in v0.5.0.
rgblink(1) already explains that "all visible labels and exported numeric constants"
will appear, which is a more appropriate location than rgbasm(5).
`uint32_t(param)` is actually functional notation of explicit casting,
not a direct constructor call. `uint32_t{param}` would be uniform
initialization syntax for a constructor call, but would not allow
narrowing from `uint64_t`. See issue #1904 for discussion.
- No fractional digits are necessary after the decimal point,
e.g. `42.` is valid instead of `42.0`
- Error messages refer to "fixed-point" not "integer" constants
- Test more carefully for lexing unrelated to underscores
- Updates `actions/checkout` from 4 to 6
- Updates `docker/login-action` from 3 to 4
- Updates `Chizkiyahu/delete-untagged-ghcr-action` from 5 to 6
- Updates `actions/upload-artifact` from 4 to 7
- Updates `actions/download-artifact` from 4 to 8
- Updates `cygwin/cygwin-install-action` from 4 to 6
Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Turns out those get new major releases somewhat often, and we get deprecation warnings and brownouts and all that.
Automatic bumps should help us avoid that, though I've set a *very* large scan interval to shield us from churn.
Besides the immediate performance improvement, reducing
the frequency of downloads should make spurious
failures (network, rate-limiting...) less bothersome.
`FetchContent` respects existing installs, and downloads and compiles the libs
if they aren't found.
This is admittedly a little finicky, since this ignores the usual `Find*`
modules provided by CMake, requiring a bit of glue on our side.
But, one upside is that this moves that logic from our CI into the build system,
which can thus benefit other downstream users.
This also opens the door to some improvements in upcoming commits.
Doing this with Bison turned out to be much more painful, however, due to
`FindBISON` providing the specific `bison_target` command; thus, it remains
installed externally, so that it can be picked up by `FindBISON`.
This also bumps our CMake version requirement slightly, though it's
possible that older versions keep working, or could be supported with small patches;
however, our CI doesn't provide anything below 3.31, so we can't check.
Set the flags in the build itself instead of trying to override the cache
(this was an artifact of when I didn't understand the CMake variable model),
which avoids them being duplicated on each re-configuration.
Also remove `-g`, since it's defined by the build type by default
(we leave it up to the user to choose Debug or RelWithDebInfo).
Make the common files into an object library, which lets them
be compiled only once (saving 41 build steps)
This also lends itself well to removing the per-program loop,
which simplifies the code somewhat.
Note that the DLL name created by CMake with `BUILD_SHARED_LIBS`
has changed from `zlib1.dll` to `z.dll`. This was caused by the
"Continued rewrite of CMake build [Vollstrecker]" from its
changelog <https://zlib.net/ChangeLog.txt>, and has been reported
in <https://github.com/madler/zlib/issues/1181>.
The MinGW package `libz-mingw-w64-dev` still calls it `libz1.dll`.
`bison -Wall` enables all diagnostics except `-Wcounterexamples`
(added in 3.7; we already pass it), `-Wyacc` (which we do not need),
and `-Wdangling-alias` (added in 3.5).
These were observed in https://udd.debian.org/lintian/?packages=rgbds
and can be reproduced by running:
for f in man/*; do
echo $f
LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=120 \
man --warnings -E UTF-8 -l -Tutf8 -Z "$f" >/dev/null
done
- ID numbers (for fstack nodes, sections, symbols, patches, etc)
might be too large for their associated collection
- Enum values might be invalid
- Bank values might be out of range for their section types
gcc 15.2.1 20250813 complains "address of automatic variable can
escape to `musttail` call" from `-Wmaybe-musttail-local-addr`,
and guaranteeing tail-call optimization cross-platform is more
trouble than it's worth.
RGBASM tests now use `rgblink -x` instead of `dd` to get trimmed
test output. RGBLINK tests cannot do so because some of them
(e.g. bank-numbers.asm and sizeof-startof.asm) rely on ROMX
sections above 1, and `-x` implies `-t` which breaks that.
* Use clang-tidy `misc-include-cleaner` for IWYU `#include` cleanup
* Use `std::optional<size_t>` instead of `ssize_t`
* Rename some functions in linkdefs.hpp
* Fix header order
- "Double quotes" for strings (filenames, section names, CLI option arguments, etc)
- 'Single quotes' for characters and CLI option flags
- `Backticks` for keywords and identifiers (symbol names, charmap names, etc)
CLI option flags also have their leading dashes
* Move the folder structure to ARCHITECTURE.md (which can be
expanded as per #707)
* Move the acknowledgements to CONTRIBUTORS.md
* Remove the history (it's a copy of man/rgbds.7)
This is an edge case of how the lexer changes behavior when
reading string literals versus reading unquoted source code.
Three double quotes would begin a multi-line string literal,
but just two are still ambiguous, so it has to `peek()` to
see whether it's inside a multi-line string literal or
outside an empty regular string.
Profiling RGBDS on building pret/pokecrystal reveals commit
cfe1f60e47 as a clear outlier
among the past few hundred commits for reducing performance
(an 8% increase on my machine from ~5 to ~5.4 seconds).
* Implement warning diagnostic flags for RGBFIX
* `-m/--mbc-type help` prints to stdout
* Support `-m list` as well as `-m help`
* Make invalid `rgbfix -l` characters a fatal error, like other invalid CLI arguments
* Refactor fix/main.cpp into multiple files
- Single unified routine for erroring out or handling missing dependencies
- Single three-state enum instead of two Booleans for missing dependencies
(this causes `-MC` to imply `-MG` instead of needing `-MG -MC`)
- Functions than can miss included files return a Boolean for whether the
parser should `YYACCEPT` and exit
Windows 2025 no longer has a D:/ drive
<https://github.com/actions/runner-images/issues/12416>
which affects where the cached files go.
This can result in one of two errors in the "Install zlib" step
after restoring from cache:
- file cannot create directory: D:/a/rgbds/rgbds/install_dir/lib.
Maybe need administrative privileges.
- file INSTALL cannot find "C:/a/rgbds/rgbds/zbuild/Release/zlib1.dll":
File exists.
Separate caches per OS should solve this problem.
* No need to use `locale`s
* Implement octal numbers, `_` digit separators, and `0x/0b/0o` prefixes in linkerscripts
* Refactor some functions out of `yylex`
* Support `\0` in linkerscripts
This feature is referred to as "code/data literals" in ASMotor,
and simply as "literals" in some older assemblers like MIDAS
for the PDP-10. RGBASM already had the "section fragments"
feature for keeping disparate contents together when linked,
so these worked naturally as "fragment literals".
* Remove `err` and `warn`, keep `errx` and `warnx`, using them in RGBGFX too
* Separate RGBGFX and RGBLINK warnings/errors from main options
* Separate `report` function into `error` and `fatal` messages
* Implicit newlines for most RGBASM errors
The original algorithm makes a simplifying assumption that one
proto-palette does not fully contain another, and we have no
particular reason to violate this condition.
ACT palette files support a transparent color index, but RGBGFX
cannot apply *one* such transparent color; it would need every
palette's first color to be transparent. Also ACT files tend to
say the first color is transparent anyway, which the user may
not have intended.
ACO palette files can specify version 2 color data, but it's
required to come after version 1 data, and the colors themselves
already exist in the earlier v1 data; v2 just adds UTF-16 names.
Thus, we do not need to be handling these data in those formats.
These fall into a few categories:
- `_unreachable()`
- Verbose print messages
- Errors that should never practically occur (alloc/read/write failure,
more than UINT32_MAX anonymous labels, etc)
`Expansion::advance()` can increase its offset beyond the size,
so I don't think this assumption was valid in the first place;
`BufferedContent::advance()` should be able to as well.
- `-fsanitize=undefined` encompasses multiple checks we were specifying
- "detect_leaks=1" for `__asan_default_options` checks for memory leaks
(except for with macOS clang++, which does not support LSan)
- `-fsanitize=float-divide-by-zero` is an extra UBSan check
(and reveals a UB bug to fix with fixed-point `DIV` and `LOG`)
This is primarily a correctness change, *not* a performance one.
The expected performance impact is minimal anyway.
The goal is to eliminate the use of platform-inconsistent floating-point operations
for this load-bearing task.
* Remove namespaces
* Prefer `bool operator==`, not `friend auto operator==`
* Prefer not to use `using`
* Use a `constexpr` function instead of a template for `flipTable`
Identify files by (device, inode), not by path, so that symlinks,
relative paths, case-insensitive paths, or other edge cases
do not result in double includes.
Part of that condition's purpose is to ensure that we read the correct
lexer state; but it's possible now for the fstack to be non-empty
*before* the lexer state is registered, i.e. if there is an error
in the function that registers it.
This causes a NULL pointer deref.
- The '#' component for type 's' now escapes the string characters
- The '#' component for type 'f' now prints a precision suffix
- The new 'q' component specifies a precision value
* Implement a '#' prefix for raw identifiers that may alias keywords
* Review comments
* Disallow hashless raw identifiers in interpolations
* Run clang-format
* Implement custom generic tagged union `Either`
This should be more efficient than `std::variant`, while still
keeping runtime safety as it `assert`s when `get`ting values.
* Use `Either` for RPN expressions
* Use `Either` for file stack node data
* Use `Either` for `File` buffer
* Use `Either` for `STRFMT` args
* Use `Either` for RGBLINK symbol values
* Support an equivalent of `std::monostate` for `Either`
* Use `Either` for lexer tokens
* Use `Either` for symbol values
* Use `Either` for lexer mmap/buffer state
This line was missing; in its absence, as soon as the array reallocs,
all registered symbol pointers are invalidated, leading to a crash
(e.g. when generating a sym file).
Made the reallocation check into a hard error, too.
Since fileSymbols gets registered with each section, we would have to
change that, and then it cascades throughout all of RGBLINK.
This will be handled correctly in the Rust port.
Passing a count parameter to the vector constructor does not reserve
count elements but instead fills the vector with count elements.
This caused the endianness check to fail first because the first 256
characters were null bytes.
The function only stopped at the end of the *arrays*,
not of *their used portions*!
This could cause false negatives one way or the other.
This appears not to affect the palette packing, since the packing algorithm
deals with them efficiently; but it should speed up processing slightly,
and as the test changes show, it also improves the UX of palette packing
error messages!
* Clarify the operator relationship of ordinary and fixed-point numbers
* Attempt to clarify description of fixed-point numbers
* Note that RGBASM does not check fixed-point precisions
* Simplify sine table example a bit
* Remove misleading equations describing `DIV`, `MUL`, and `FMOD`
* Various minor style and formatting fixups
The generated `result.pal` can change between platforms, it turns out
(due to "unstable sort" differences), and creates additional churn if
changing anything related to palette generation.
tl;dr this makes the test less flaky in the long run.
- FIX: `Label & const` was not actually doing the `& const` masking
(fixes#1446)
- ADD: `LOW(Label)` can be constant if `Label` is aligned to 8 or more bits
(resolves#1444)
- ADD: `!expr` can be constant 0 if `expr` has any non-zero bits
(resolves#1447)
- `LOW()` and `HIGH()` have their own RPN operator values
(resolves#1445)
The change to RPN values means that the object file version was incremented.
This also refactors unary operators and functions, combining their
evaluation similarly to binary ones.
Large sizes are more efficient when it's actually buffered,
but most of the time `mmap` is used instead, and the extra size
just slows down allocation of lexer states.
- Fixed-point formulas are implemented using IEEE-754 floating-point
internally, which could give infinity or NaN values whose conversion
to fixed-point integer was platform-dependent.
- Formatting fixed-point $8000_0000 (INT32_MIN, -2147483648) was
not putting the negative sign in front.
The Python Pillow image library gives different output for
`Image.getcolors()` in version 9 than version 10. This causes
libbet's SGB border to be built differently, giving a different
ROM hash and technically failing the test script.
This patches libbet to only keep the known-good colors. It also
adapts the coverage script to run all the tests, including
building the third-party projects.
This way, if a child context initializes `\@`, the parent won't
reset it. And if the child context did not initialize `\@`,
then resetting it would be redundant.
`std::visit` is (arguably) cleaner code, but older versions of gcc
and clang (not very old; the ones packaged with Ubuntu 22.04 LTS)
compile them as tables of function pointers, instead of efficient
jump tables.
This is a work in progress: its performance is unacceptably slow,
and it is obviously not a complete refactoring:
- The parser's semantic functions are still written for C-style
strings, taking `.c_str()` pointers instead of `std::string`
references (and using their methods, `<algorithm>`s, etc).
- Quoted string literals from the lexer still use our `String`
struct, which wraps around a fixed-size char array.
- Symbol values, macro arguments, and so forth are still pointers
to C-style strings with unclear ownership semantics (i.e. we
still have "leaks as a feature").
This allows us to control the order in which sections are iterated,
instead of it depending on the internals of `std::map`. (This order
is arbitrary, but should be deterministic regardless.)
It complains about *those* calls returning a dangling reference...
Unfortunately, GCC does not provide more information about what the
reference *is*. (It only mentions the temporary being destroyed at
the end of this *huge* expression.)
I am normally not one to just commit a thing that gets rid of a
warning if I can't explain why, but this eludes me.
Stubbing out the calls to only return a captured variable still
complains, which led me to test that the error wasn't stemming
from the `Visitor` itself... which it seems to?
But I don't see why a reference to the *visitor* should be kept...
Anyway, here is the obligatory part where I state my yearning for Rust :)
This still doesn't allow identical exported label constants.
That can be addressed when or if it's requested for a real use case.
Symbols only store one source filename + line number, so this
arbitrarily keeps the last read symbol as the reported one.
Fixes `make develop` with Clang 17.
The warning only triggers on the auto-generated `yynerrs_` in `src/asm/parser.cpp`,
so it's not very useful to us right now.
- Since we have style rules to include foo.hpp at the top of its
corresponding foo.cpp, this takes any headers included by foo.hpp
as being also guaranteed for foo.cpp.
- Use C-style <foo.h> instead of <cfoo>, since the latter only
guarantees putting symbols in the `std` namespace, which we are
not using for C functions (e.g. `printf` not `std::printf`).
- Remove now-unused `__PRETTY_FUNCTION__` reporting
We were not initializing some expressions, and they were using
the values of the previous expressions instead. This just so
happened to not crash the tests, and to sometimes even give valid
results (although `BANK()` of a non-label symbol being $4B4E4142,
the ASCII balue of "BANK", was something we missed).
* Avoid redirecting error messages in RGBLINK tests
We check that RGBLINK prints nothing to stdout, so all that
would be captured on stdout is a putative failure message.
* Require each RGBLINK test to check error output
Otherwise, you can have a test that just... checks nothing!
* Document how to add tests
Fixes#1300's last remaining item.
Also add `checkdiff` rules to remind us to update that doc if
any of the test driver scripts are updated.
This removes the last use of `strdup`
This required making a lot of related pointers be `const`.
That in turn conflicted with the need to `munmap()` a pointer
eventually, which was similar to the need to eventually `free()`
an `Expansion`'s contents, so I used the same solution of a
`union`. That lets us normally use the `const` pointer for
`const` correctness, and the non-`const` one for the not-really-
mutating destruction cases.
Split the declarations into those required for the `%union` and
those only required for the `code`.
Only declare functions on top; define them at the bottom.
* Replace FAMs with `std::vector`s (or one `std::string`) in four `struct`s
* Anonymous types declared in an anonymous union are also non-standard
Only Clang complains about this (-Wnested-anon-types)
* Fixes from temporarily re-enabling more compiler warnings
* More edits suggested by cppcheck
* Fix hanging on append_yylval_string
* Fix FOR loop increment
macOS 10.15 introduced full `std::filesystem::path` support.
Before that our use of it would cause the build to fail.
This was not caught because "-mmacosx-version-min=10.9" was only
being passed to clang++ for release builds.
This passes that flag in a new static CI test build, and introduces
a hack developed by @LIJI32 to silence the availability errors,
since we use features already available in macOS 10.9.
This means we are testing both "vanilla" building,
and building static binaries using the same configuration
as during release, which should help avoiding last-minute
surprises.
* Allow for optional sections in linker scripts
These are more useful for frameworks/toolchains.
* Check for an active mem region everywhere
Do you like segfaults? Too bad!
* Allow the address to be floating in linker scripts
Try and make the life of SDCC interop easier.
* Also validate alignment when floating
* Overhaul the linker script manual page
Documenting the new features, but also restructuring the
existing documentation to make the manual page (hopefully)
easier to understand.
Ensure consistency in linker script parser interface
Make the declaration and definition visible when compiling
so that the compiler can warn about inconsistencies.
Co-authored-by: ISSOtm <[email protected]>
Notable side effects:
* Use the standard-conformant MSVC preproc
* Add test for linker script INCLUDE
* Improve wording of placement conflict errors
* Fix errors from not newline-terminated files
* Teach checkdiff about the linker script doc
* Call linker script "commands" "directives" instead
---------
Co-authored-by: Rangi42 <[email protected]>
As reported by the following command:
mandoc -T lint man/* | grep -v "input text line longer than 80 bytes"
(One of them also showed up as a warning while setting up Debian packaging.)
Based on SameBoy's "accurate modern" colour mapping.
Special thanks to @Rangi42 for her patience throughout development, @LIJI32 for researching the colour curve and helping with the creation of the reverse mapping (colour spaces are *fun*!), and @coffeevalenbat for testing :)
Copy CMake-built test executables to test directory
Fixes CI failures on Windows.
CI should also have failed on Unices, but it turns out
we instead merely hit the fallback that the `make` path
relies on (building those executables with `make`),
which fails on Windows since `make` is not set up to
find libpng.
Allows better platform-agnostic path manipulation.
Also, using `std::optional` rather than empty strings allows
correctly handling empty arguments (treating them as such,
instead of acting as they were never passed).
Each symbol passed to purge is collected in a list before mass removal.
Fixes the issue described in gbdev/rgbds issue #1152.
---------
Co-authored-by: Rangi42 <[email protected]>
fix#1157 for the following source code
```
section "hSAVE_locals",HRAM
func3.hSpam: ds 1 ; no longer produces an error
;.hEggs: ds 1 ; uncomment this to see the new error
section "demo",ROM0
func3:
ldh a, [.hSpam]
ret
```
Remove two errors:
- `Not currently in the scope of 'func3'`
- `Local label 'func3.hSpam' in main scope`
Add one error:
- `Relative local label '.hSpam' in main scope`
Co-authored-by: Rangi <[email protected]>
The existing explanations have proven confusing to many,
and presenting the instructions in a more visual manner should help a lot.
Additionally, the Unicode codepoints are typed as-is in the source,
because that allows much more WYSIWYG editing, and god damn it this is the year
two thousand and twenty three, if your man and/or terminal software does't
support Unicode, then what are you *doing*.
The previous test did not expect failure when trying to stuff
$3000 bytes into $2000-byte WRAM; this is now fixed, and we
also test the reverse now (that we cannot stuff more than
$1000 bytes into WRAM0 without `-d`/`-w`.
The addition of SDCC objects required a change in the logic of
`mergeSections()` to dispatch based on `->data` instead of
`sect_HasData`, which implicitly assumes that `->data` is
always initialised (maybe NULL).
However, RGBDS sections did not do that!
- Changes most `/* comments */` to `// comments`
- Changes `/**` block comments consistently to `/*`
- Adds consistent license comments to all files
Also renames `T_POP_SET` to `T_Z80_SET`
Previously, indices would be wrapped after 256 even without a tilemap;
since RGBGFX can generate arbitrarily large tile data if `-N` is not used,
it should be possible to read those in.
Of course, this won't work if a tilemap is provided, but such "big blobs"
can't generate a meaningful tilemap anyway.
Replacing the big pre-formatted text block with a list brings:
- Better accessibility, obviously
- Responsiveness
- Better formatting (bold, etc.)
- Sub-sections that can now be linked to
- Hyperlink cross-refs to other pages
The slight disadvantage is that `ENDC` etc. are now individual
list items, whereas they'd be better as part of the same item.
No big deal though, it was much worse before.
Some descriptions have been overhauled for clarity, and some
outright corrected (such as Assertions' "Offset" field).
Co-authored-by: Antonio Vivace <[email protected]>
This function is made for text, e.g. accepts spaces, leading zeros, etc. before `%u`.
This way checks that the correct amount of bytes are read instead.
This requires a LOT of tricky code, mostly due to the format itself being,
er, not the most straightforward.
Everything is converted to existing RGBLINK concepts (sections, patches,
etc.), so the core code is essentially unchanged.
(A couple of genuine RGBLINK bugs were uncovered along the way, so some of
the core code *is* changed, notably regarding `SECTION FRAGMENT`s.)
All of this code was clean-roomed, so SDCC's GPLv2 license does not apply.
A black+white palette would turn into white+transparent, removing black pixels
from the palette (the third slot would be empty, and the 4th slot be set directly)
The sorting was performed without updating the mappings, which broke the world.
We can instead sort the IDs as they are inserted into the packing queue,
which should also be faster than moving the actual proto-pal objects around.
Not hooked to all RGBGFX flags yet, but good enough for most use cases
(and as a base for future development, should I need to `reset --hard`.)
TODOs marked appropriately.
Force version.c to be compiled as C++ (bodge, will need a proper fix for `version.c`)
Remove user-defined `ProtoPalette` assignment operator (same as default, anyway)
Currently missing from the old version:
- `-f` ("fixing" the input image to be indexed)
- `-m` (the code for detecting mirrored tiles is missing, but all of the
"plumbing" is otherwise there)
- `-C`
- `-d`
- `-x` (though I need to check the exact functionality the old one has)
- Also the man page is still a draft and needs to be fleshed out
More planned features are not implemented yet either:
- Explicit palette spec
- Better error messages, also error "images"
- Better 8x16 support, as well as other "dedup unit" sizes
- Support for arbitrary number of palettes & colors per palette
- Other output formats (for example, a "full" palette map for "streaming"
use cases like gb-open-world)
- Quantization?
Some things may also be bugged:
- Transparency support
- Tile offsets (not exposed yet)
- Tile counts per bank (not exposed yet)
...and performance remains to be checked.
We need to set up some tests, honestly.
It's unlikely that a specific value matters, though in theory possible;
however, an exhaustive test every time is really slow, and testing a couple
random values should, over time, cover everything.
It is fine to test random values because those tested will be logged,
so the problem can be manually reproduced later.
It does make CI technically not deterministic... but that should be fine.
Should not be followed for C files, to avoid mucking `blame`s,
but will be applied during the gradual C++ rollout, since that
will likely touch most lines in the codebase anyway.
Enhances some warnings as well as the sanitizers (Clang especially complained about it)
The `-f*` flags are to get better stack traces out of the sanitizers, as recommended
by Clang's docs: https://clang.llvm.org/docs/AddressSanitizer.html#usage
GCC's docs claim that these optimizations should not hinder the debugging
experience, and Clang's don't mention optimization flags at all.
Remove already-enabled warnings as pointed out by #969
Comments added to the CMakeLists because the Makefile format does not really allow them
"Plain" list also sorted alphabetically, the rest (somewhat) thematically
Attempting to build with this gave an "undefined reference to `yydebug'"
error (maybe a version issue with bison?), and I don't think it's been
used for recent parser debugging either.
Remove unreachable argument presence check (handled by `getopt`)
Merge allocation paths into a single `realloc` call
Avoid searching for string lengths multiple times
Tiny (compatible) change: no space between last dependent and colon if
`-MT` or `-MQ` is specified
* Add Bash completion script for RGBASM
Should have large feature parity with the Zsh completion
Co-authored-by: DaKnig <[email protected]>
* Register RGBASM Bash completion in `checkdiff`
Co-authored-by: ISSOtm <[email protected]>
* Add scramble flags to RGBLINK
-S and -W will scramble ROMX and WRAMX respectively.
* Modify scramble CLI
CLI now takes a list of comma-separated values.
Added arg_error to clean up messages.
Co-authored-by: Eldred Habert <[email protected]>
* Document scrambling functionality
Co-authored-by: Eldred Habert <[email protected]>
* Implement -Wtruncation=level
-Wtruncation=0 is the same as the current -Wno-truncation.
-Wtruncation=2 is the same as the current -Wtruncation.
-Wtruncation=1 is the new default; it's less strict, allowing
N-bit values to be between -2**N and 2**N (exclusive).
* Implement generic "parametrized warning" system
* Test more `Wtruncation` variants
Co-authored-by: ISSOtm <[email protected]>
* Reword label definition docs
A bunch of short sentences isn't very readable, this should be better
* Use correct wording for "computing difference"
Co-authored-by: Rangi <[email protected]>
* Explain how to define a label before mentioning local ones
* Move double-colon paragraph to make the explanation flow better
* Clarify what a label's value is
Co-authored-by: Rangi <[email protected]>
I think we've earned it, at least for being maintainers for a couple years.
I believe the work done by those before us is more important (relicensing & cleanup),
but we've both made significant changes on top of what they made possible.
`TIMER & BATTERY` is 0, but even `|` would only be checking if
*either* is set; instead, imply BATTERY as soon as TIMER is given,
printing a warning if it was not given.
`startCapture` did not initialize `lexerState->atLineStart`;
its final value is a consequence of the separate but similar
behaviors within `lexer_CaptureRept` and `lexer_CaptureMacroBody`.
- Don't warn if the non-zero byte being written is the same as the original byte
- Add a `-O` / `--overwrite` flag to silence all such warnings
Fixes#897
`DEF`, `REDEF`, etc disable EQUS expansion, and reading
macro or OPT arguments sets the lexer to raw mode.
Syntax errors resume normal parsing at the line's end,
but should resume normal tokenization even before that.
This message is only printed for identifiers parsed as
`T_LABEL` (since they're at the start of a line) but
already defined as macros. Otherwise it may not be
relevant, e.g. for `MyLabel;:` or `My Label::`.
Please ensure that the packages below work properly.
Once that's done, replace this text with the changelog, un-draft the release, and update the `release` branch.
By the way, if you forgot to update `include/version.hpp`, RGBASM's version test is going to fail in the tag's regression testing! (Use `git push --delete origin <tag>` to delete it)
Please ensure that the three assets below work properly.
Once that's done, replace this text with the changelog, un-draft the release, and update the `release` branch.
By the way, if you forgot to update `include/version.h`, RGBASM's version test is gonna fail in the tag's regression testing! (Use `git push --delete origin <tag>` to delete it)
draft:true# Don't publish the release quite yet...
RGBDS (Rednex Game Boy Development System) is a free assembler/linker package
for the Game Boy and Game Boy Color. It consists of:
- rgbasm (assembler)
- rgblink (linker)
- rgbfix (checksum/header fixer)
- rgbgfx (PNG‐to‐Game Boy graphics converter)
This is a fork of the original RGBDS which aims to make the programs more like
other UNIX tools.
This toolchain is maintained on `GitHub <https://github.com/rednex/rgbds>`__.
The documentation of this toolchain can be viewed online
`here <https://rgbds.gbdev.io/docs/>`__, it is generated from the man pages
found in this repository.
If you want to contribute or maintain RGBDS, and have questions regarding the code, its organisation, etc. you can find me `on GBDev <https://gbdev.io/chat>`__ or via mail at ``rgbds at eldred dot fr``.
1. Installing RGBDS
-------------------
The `installation procedure <https://rgbds.gbdev.io/install>`__ is available
online for various platforms. `Building from source <https://rgbds.gbdev.io/install/source>`__
is possible using ``make`` or ``cmake``; follow the link for more detailed instructions.
..code::sh
make
sudo make install
..code::sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
2. RGBDS Folder Organization
----------------------------
The RGBDS source code file structure somewhat resembles the following:
::
.
├── .github/
│ ├── actions/
│ │ └── ...
│ └── workflows/
│ └── ...
├── contrib/
│ ├── zsh_compl/
│ │ └── ...
│ └── ...
├── include/
│ └── ...
├── src/
│ ├── asm/
│ │ └── ...
│ ├── extern/
│ │ └── ...
│ ├── fix/
│ │ └── ...
│ ├── gfx/
│ │ └── ...
│ ├── link/
│ │ └── ...
│ ├── CMakeLists.txt
│ └── ...
├── test/
│ ├── ...
│ └── run-tests.sh
├── CMakeLists.txt
├── Makefile
└── README.rst
-``.github/`` - files and scripts related to the integration of the RGBDS codebase with
GitHub.
-``contrib/`` - scripts and other resources which may be useful to users and developers of
RGBDS.
*``zsh_compl`` contains tab completion scripts for use with zsh. Put them somewhere in your ``fpath``, and they should auto-load.
-``include/`` - header files for each respective C files in `src`.
-``src/`` - source code and manual pages for RGBDS.
* Note that the code unique to each RGBDS tool is stored in its respective subdirectory
(rgbasm -> ``src/asm/``, for example). ``src/extern/`` contains code imported from external sources.
-``test/`` - testing framework used to verify that changes to the code don't break or modify the behavior of RGBDS.
3. History
----------
- Around 1997, Carsten Sørensen (AKA SurfSmurf) writes ASMotor as a
general-purpose assembler/linker system for DOS/Win32
- Around 1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and
produce GBZ80 assembly/machine code, and releases this version as RGBDS.
- 2009, Vegard Nossum adapts the code to be more UNIX-like and releases
- 2010, Anthony J. Bentley forks that repository. The fork becomes the reference
implementation of rgbds.
- 2017, Bentley's repository is moved to a neutral name.
- 2018, codebase relicensed under the MIT license.
- 2020, repository is moved to the `gbdev <https://github.com/gbdev>`__ organisation. The `rgbds.gbdev.io <https://rgbds.gbdev.io>`__ website serving documentation and downloads is created.
The RGBDS package consists of four programs: RGBASM, RGBLINK, RGBFIX, and RGBGFX.
- RGBASM is the assembler. It takes assembly code as input, and produces an RGB object file as output (and optionally a state file, logging the final state of variables and constants).
- RGBLINK is the linker. It takes object files as input, and produces a ROM file as output (and optionally a symbol and/or map file, logging where the assembly declarations got placed in the ROM).
- RGBFIX is the checksum/header fixer. It takes a ROM file as input, and outputs the same ROM file (or modifies it in-place) with the cartridge header's checksum and other metadata fixed for consistency.
- RGBGFX is the graphics converter. It takes a PNG image file as input, and outputs the tile data, palettes, tilemap, attribute map, and/or palette map in formats that the Game Boy can use.
In the simplest case, a single pipeline can turn an assembly file into a ROM:
This document describes how these four programs are structured. It goes over each source code file, noting which data is *global* (and thus scoped in all files), *owned* by that file (i.e. that is where the data's memory is managed, via [RAII](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization)) or *referenced* by that file (i.e. there are non-owning pointers to some data, and care must be taken to not dereference those pointers after the data's owner has moved or deleted the data).
We assume that the programs are single-threaded; data structures and operations may not be thread-safe.
## Folder Organization
The RGBDS source code file structure is as follows:
```
rgbds/
├── .github/
│ ├── scripts/
│ │ └── ...
│ └── workflows/
│ └── ...
├── cmake/
│ └── ...
├── contrib/
│ ├── bash_compl/
│ ├── zsh_compl/
│ │ └── ...
│ └── ...
├── docs/
│ └── ...
├── include/
│ └── ...
├── man/
│ └── ...
├── src/
│ ├── asm/
│ │ └── ...
│ ├── extern/
│ │ └── ...
│ ├── fix/
│ │ └── ...
│ ├── gfx/
│ │ └── ...
│ ├── link/
│ │ └── ...
│ ├── CMakeLists.txt
│ ├── bison.sh
│ └── ...
├── test/
│ ├── run-tests.sh
│ ├── external/
│ │ ├── fetch-repos.sh
│ │ └── ...
│ └── ...
├── .clang-format
├── .clang-tidy
├── CMakeLists.txt
├── CMakePresets.json
├── Dockerfile
└── Makefile
```
- **`.github/`:**
Files related to the integration of the RGBDS codebase with GitHub features.
* **`scripts/`:**
Scripts used by GitHub Actions workflow files.
* **`workflows/`:**
GitHub Actions CI workflow description files. Used for automated testing, deployment, etc.
- **`cmake/`**:
Files relevant to our CMake build system that are not required to be somewhere else (e.g. `CMakePresets.json`*has* to be at the root).
- **`contrib/`:**
Scripts and other resources which may be useful to RGBDS users and developers.
* **`bash_compl/`:**
Tab completion scripts for use with `bash`. Run them with `source` somewhere in your `.bashrc`, and they should auto-load when you open a shell.
* **`zsh_compl/`:**
Tab completion scripts for use with `zsh`. Put them somewhere in your `fpath`, and they should auto-load when you open a shell.
- **`docs/`:**
Documentation related to the development and maintenance of RGBDS itself.
(The directory's name, as well as some of its file's names, are
[recognized by GitHub](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
and linked to in parts of its UI.)
Documentation for RGBDS itself exists as manual pages in `man/`.
- **`include/`:**
Header files for the respective source files in `src`.
- **`man/`:**
Manual pages to be read with `man`, written in the [`mandoc`](https://mandoc.bsd.lv) dialect.
- **`src/`:**
Source code of RGBDS.
* **`asm/`:**
Source code of RGBASM.
* **`extern/`:**
Source code copied from external sources.
* **`fix/`:**
Source code of RGBFIX.
* **`gfx/`:**
Source code of RGBGFX.
* **`link/`:**
Source code of RGBLINK.
* **`CMakeLists.txt`:**
Defines how to build individual RGBDS programs with CMake, including the source files that each program depends on.
* **`bison.sh`:**
Script used to run the Bison parser generator with the latest flags that the user's version supports.
- **`test/`:**
Testing framework used to verify that changes to the code don't break or modify the behavior of RGBDS.
The `test.sh` scripts inside each of the subdirectories are the individual test drivers.
* **`run-tests.sh`:**
Script used to run tests, including internal test cases and external repositories. `run-tests.sh --help` describes its options.
* **`external/`:**
Directory for third-party repos making use of RGBDS, which get cloned here and built during testing.
- **`fetch-repos.sh`:**
Script used to clone the external repositories. `fetch-repos.sh --help` describes its options.
- **`*.cfg`:**
Each `.cfg` file defines the parameters to clone, build, and verify an external repository.
- **`.clang-format`:**
Code style for automated C++ formatting with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) (for which we define the shortcut `make format`).
- **`.clang-tidy`:**
Configuration for C++ static analysis with [`clang-tidy`](https://clang.llvm.org/extra/clang-tidy/) (for which we define the shortcut `make tidy`).
- **`CMakeLists.txt`:**
Defines how to build RGBDS with CMake.
- **`CMakePresets.json`:**
Defines some [presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) useful for working with our CMake.
- **`Dockerfile`:**
Defines how to build RGBDS with Docker (which we do in CI to provide a [container image](https://github.com/gbdev/rgbds/pkgs/container/rgbds)).
- **`Makefile`:**
Defines how to build RGBDS with `make`, including the source files that each program depends on.
## RGBDS
These files in the `src/` directory are shared across multiple programs: often all four (RGBASM, RGBLINK, RGBFIX, and RGBGFX), sometimes only RGBASM and RGBLINK.
- **`backtrace.cpp`:**
Generic printing of location backtraces for RGBASM and RGBLINK. Allows configuring backtrace styles with a command-line flag (conventionally `-B/--backtrace`). Renders warnings in yellow, errors in red, and locations in cyan.
- **`cli.cpp`:**
A function for parsing command-line options, including RGBDS-specific "at-files" (a filename containing more options, prepended with an "`@`").
This is the only file to use the extern/getopt.cpp variables and functions.
- **`diagnostics.cpp`:**
Generic warning/error diagnostic support for all programs. Allows command-line flags (conventionally `-W`) to have `no-`, `error=`, or `no-error=` prefixes, and `=` level suffixes; allows "meta" flags to affect groups of individual flags; and counts how many total errors there have been. Every program has its own `warning.cpp` file that uses this.
- **`linkdefs.cpp`:**
Constants, data, and functions related to RGBDS object files, which are used for RGBASM output and RGBLINK input.
This file defines two *global* variables, `sectionTypeInfo` (metadata about each section type) and `sectionModNames` (names of section modifiers, for error reporting). RGBLINK may change some values in `sectionTypeInfo` depending on its command-line options (this only affects RGBLINK; `sectionTypeInfo` is immutable in RGBASM).
- **`opmath.cpp`:**
Functions for mathematical operations in RGBASM and RGBLINK that aren't trivially equivalent to built-in C++ ones, such as division and modulo with well-defined results for negative values.
- **`style.cpp`:**
Generic printing of cross-platform colored or bold text. Obeys the [`FORCE_COLOR`](https://force-color.org/) and [`NO_COLOR`](https://no-color.org/) environment variables, and allows configuring with a command-line flag (conventionally `--color`).
- **`usage.cpp`:**
Generic printing of usage information. Renders headings in green, flags in cyan, and URLs in blue. Every program has its own `main.cpp` file that uses this.
- **`util.cpp`:**
Utility functions applicable to most programs, mostly dealing with text strings, such as locale-independent character checks.
- **`verbosity.cpp`:**
Generic printing of messages conditionally at different verbosity levels. Allows configuring with a command-line flag (conventionally `-v/--verbose`).
- **`version.cpp`:**
RGBDS version number and string for all the programs.
## External
These files have been copied ("vendored") from external authors and adapted for use with RGBDS. Both of our vendored dependencies use the same MIT license as RGBDS.
- **`getopt.cpp`:**
Functions for parsing command-line options, including conventional single-dash and double-dash options.
This file defines some *global*`musl_opt*` variables, including `musl_optarg` (the argument given after an option flag) and `musl_optind` (the index of the next option in `argv`). Copied from [musl libc](https://musl.libc.org/).
- **`utf8decoder.cpp`:**
Function for decoding UTF-8 bytes into Unicode code points. Copied from [Björn Höhrmann](https://bjoern.hoehrmann.de/utf-8/decoder/dfa/).
## RGBASM
- **`actions.cpp`:**
Actions taken by the assembly language parser, to avoid large amounts of code going in the parser.y file.
- **`charmap.cpp`:**
Functions and data related to charmaps.
This file *owns* the `Charmap`s in its `charmaps` collection. It also maintains a static `currentCharmap` pointer, and a `charmapStack` stack of pointers to `Charmap`s within `charmaps` (which is affected by `PUSHC` and `POPC` directives).
- **`fixpoint.cpp`:**
Functions for fixed-point math, with configurable [Q*m*.*n*](https://en.wikipedia.org/wiki/Q_(number_format)) precision.
- **`format.cpp`:**
`FormatSpec` methods for parsing and applying format specs, as used by `{interpolations}` and `STRFMT`.
- **`fstack.cpp`:**
Functions and data related to "fstack" nodes (the contents of top-level or `INCLUDE`d files, macro expansions, or `REPT`/`FOR` loop iterations) and their "contexts" (metadata that is only relevant while a node's content is being lexed and parsed).
This file *owns* the `Context`s in its `contextStack` collection. Each of those `Context`s *owns* its `LexerState`, and *refers* to its `FileStackNode`, `uniqueIDStr`, and `macroArgs`. Each `FileStackNode` also *references* its `parent`.
- **`intern.cpp`:**
[Interned strings](https://en.wikipedia.org/wiki/String_interning), which are used for the names of keywords, symbols (labels, constants, variables, string constants, macros, etc), and charmaps.
This file *owns* the strings in its `internedStrings` collection, which its `internedIndexes` collection *references* by view and index.
- **`lexer.cpp`:**
Functions and data related to [lexing](https://en.wikipedia.org/wiki/Lexical_analysis) assembly source code into tokens, which can then be parsed.
This file maintains static `lexerState` and `lexerStateEOL` pointers to `LexerState`s from the `Context`s in `fstack.cpp`.
Each `LexerState`*owns* its `content` and its `expansionStack`'s content. Each `Expansion` (the contents of an `{interpolation}` or macro argument) in turn *owns* its `contents`.
The lexer and parser are interdependent: when the parser reaches certain tokens, it changes the lexer's mode, which affects how characters get lexed into tokens. For example, when the parser reaches a macro name, it changes the lexer to "raw" mode, which lexes the rest of the line as a sequence of string arguments to the macro.
- **`macro.cpp`:**
`MacroArgs` methods related to macro arguments. Each `MacroArgs`*references* its arguments' contents.
- **`main.cpp`:**
The `main` function for running RGBASM, including the initial handling of command-line options.
This file defines a *global*`options` variable with the parsed CLI options.
- **`opt.cpp`:**
Functions for parsing options specified by `OPT` or by certain command-line options.
This file *owns* the `OptStackEntry`s in its `stack` collection (which is affected by `PUSHO` and `POPO` directives).
- **`output.cpp`:**
Functions and data related to outputting object files (with `-o/--output`) and state files (with `-s/--state`).
This file *owns* its `assertions` (created by `ASSERT` and `STATIC_ASSERT` directives). Every assertion gets output in the object file.
This file also *references* some `fileStackNodes`, and maintains static pointers to `Symbol`s in `objectSymbols`. Only the "registered" symbols and fstack nodes get output in the object file. The `fileStackNodes` and `objectSymbols` collections keep track of which nodes and symbols have been registered for output.
- **`parser.y`:**
Grammar for the RGBASM assembly language, which Bison preprocesses into a [LALR(1) parser](https://en.wikipedia.org/wiki/LALR_parser).
The Bison-generated parser calls `yylex` (defined in `lexer.cpp`) to get the next token, and calls `yywrap` (defined in `fstack.cpp`) when the current context is out of tokens and returns `EOF`.
- **`rpn.cpp`:**
`Expression` methods and data related to "[RPN](https://en.wikipedia.org/wiki/Reverse_Polish_notation)" expressions. When a numeric expression is parsed, if its value cannot be calculated at assembly time, it is built up into a buffer of RPN-encoded operations to do so at link time by RGBLINK. The valid RPN operations are defined in [man/rgbds.5](/man/rgbds.5).
- **`section.cpp`:**
Functions and data related to `SECTION`s.
This file *owns* the `Section`s in its `sections` collection. It also maintains various static pointers to those sections, including the `currentSection`, `currentLoadSection`, and `sectionStack` (which is affected by `PUSHS` and `POPS` directives). (Note that sections cannot be deleted.)
- **`symbol.cpp`:**
Functions and data related to symbols (labels, constants, variables, string constants, macros, etc).
This file *owns* the `Symbol`s in its `symbols` collection, and the various built-in ones outside that collection (`PCSymbol` for "`@`", `NARGSymbol` for "`_NARG`", etc). It also maintains a static `purgedSymbols` collection to remember which symbol names have been `PURGE`d from `symbols`, for error reporting purposes.
- **`warning.cpp`:**
Functions and data for warning and error output.
This file defines a *global*`warnings` variable using the `diagnostics.cpp` code for RGBASM-specific warning flags.
## RGBFIX
- **`fix.cpp`:**
Functions for fixing the ROM header.
- **`main.cpp`:**
The `main` function for running RGBFIX, including the initial handling of command-line options.
This file defines a *global*`options` variable with the parsed CLI options.
- **`mbc.cpp`:**
Functions and data related to [MBCs](https://gbdev.io/pandocs/MBCs.html), including the names of known MBC values.
- **`warning.cpp`:**
Functions and data for warning and error output.
This file defines a *global*`warnings` variable using the `diagnostics.cpp` code for RGBFIX-specific warning flags.
## RGBGFX
- **`color_set.cpp`:**
`ColorSet` methods for creating and comparing sets of colors. A color set includes the unique colors used by a single tile, and these sets are then packed into palettes.
- **`main.cpp`:**
The `main` function for running RGBGFX, including the initial handling of command-line options.
This file defines a *global*`options` variable with the parsed CLI options.
- **`pal_packing.cpp`:**
Functions for packing color sets into palettes. This is done with an ["overload-and-remove" heuristic](https://arxiv.org/abs/1605.00558) for a pagination algorithm.
- **`pal_sorting.cpp`:**
Functions for sorting colors within palettes, which works differently for grayscale, RGB, or indexed-color palettes.
- **`pal_spec.cpp`:**
Functions for parsing various formats of palette specifications (from `-c/--colors`).
- **`palette.cpp`:**
`Palette` methods for working with up to four GBC-native (RGB555) colors.
- **`png.cpp`:**
`Png` methods for reading PNG image files, standardizing them to 8-bit RGBA pixels while also reading their indexed palette if there is one.
- **`process.cpp`:**
Functions related to generating and outputting files (tile data, palettes, tilemap, attribute map, and/or palette map).
- **`reverse.cpp`:**
Functions related to reverse-generating RGBGFX outputs into a PNG file (for `-r/--reverse`).
- **`rgba.cpp`:**
`Rgba` methods related to RGBA colors and their 8-bit or 5-bit representations.
- **`warning.cpp`:**
Functions and data for warning and error output.
This file defines a *global*`warnings` variable using the `diagnostics.cpp` code for RGBGFX-specific warning flags.
## RGBLINK
- **`assign.cpp`:**
Functions and data for assigning `SECTION`s to specific banks and addresses.
This file *owns* the `memory` table of free space: each section type is associated with a list of each bank's free address ranges, which are allocated to sections using a [first-fit decreasing](https://en.wikipedia.org/wiki/Bin_packing_problem#First-fit_algorithm) bin-packing algorithm.
- **`fstack.cpp`:**
Functions related to "fstack" nodes (the contents of top-level or `INCLUDE`d files, macro expansions, or `REPT`/`FOR` loop iterations) read from the object files. At link time, these nodes are only needed for printing of location backtraces.
- **`layout.cpp`:**
Actions taken by the linker script parser, to avoid large amounts of code going in the script.y file.
This file maintains some static data about the current bank and address layout, which get checked and updated for consistency as the linker script is parsed.
- **`lexer.cpp`:**
Functions and data related to [lexing](https://en.wikipedia.org/wiki/Lexical_analysis) linker script files into tokens, which can then be parsed.
This file *owns* the `LexerStackEntry`s in its `lexerStack` collection. Each of those `LexerStackEntry`s *owns* its `file`. The stack is updated as linker scripts can `INCLUDE` other linker script pieces.
The linker script lexer is simpler than the RGBASM one, and does not have modes.
- **`main.cpp`:**
The `main` function for running RGBLINK, including the initial handling of command-line options.
This file defines a *global*`options` variable with the parsed CLI options.
- **`object.cpp`:**
Functions and data for reading object files generated by RGBASM.
This file *owns* the `Symbol`s in its `symbolLists` collection, and the `FileStackNode`s in its `nodes` collection.
- **`output.cpp`:**
Functions and data related to outputting ROM files (with `-o/--output`), symbol files (with `-n/--sym`), and map files (with `-m/--map`).
This file *references* some `Symbol`s and `Section`s, in collections that keep them sorted by address and name, which allows the symbol and map output to be in order.
- **`patch.cpp`:**
Functions and data related to "[RPN](https://en.wikipedia.org/wiki/Reverse_Polish_notation)" expression patches read from the object files, including the ones for `ASSERT` conditions. After sections have been assigned specific locations, the RPN patches can have their values calculated and applied to the ROM. The valid RPN operations are defined in [man/rgbds.5](/man/rgbds.5).
This file *owns* the `Assertion`s in its `assertions` collection, and the `RPNStackEntry`s in its `rpnStack` collection.
- **`script.y`:**
Grammar for the linker script language, which Bison preprocesses into a [LALR(1) parser](https://en.wikipedia.org/wiki/LALR_parser).
The Bison-generated parser calls `yylex` (defined in `lexer.cpp`) to get the next token, and calls `yywrap` (also defined in `lexer.cpp`) when the current context is out of tokens and returns `EOF`.
- **`sdas_obj.cpp`:**
Functions and data for reading object files generated by [GBDK with SDCC](https://gbdk.org/). RGBLINK support for these object files is incomplete.
- **`section.cpp`:**
Functions and data related to `SECTION`s read from the object files.
This file *owns* the `Section`s in its `sections` collection.
- **`symbol.cpp`:**
Functions and data related to symbols read from the object files.
This file *references* the `Symbol`s in its `symbols` and `localSymbols` collections, which allow accessing symbols by name.
- **`warning.cpp`:**
Functions and data for warning and error output.
This file defines a *global*`warnings` variable using the `diagnostics.cpp` code for RGBLINK-specific warning flags.
2. Make sure that you have installed `groff` and `mandoc`. You will
need `mandoc` 1.14.5 or later to support `-O toc`.
3. Inside of the `man` directory, run <code><i><path/to/rgbds-www></i>/maintainer/man_to_html.sh <i><tag></i> *</code> then <code><i><path/to/rgbds-www></i>/maintainer/new_release.sh <i><tag></i></code>.
This will render the RGBDS documentation as HTML and PDF and copy it to
`rgbds-www`.
If you do not have `groff` installed, you can change
`groff -Tpdf -mdoc -wall` to `mandoc -Tpdf -I os=Linux` in
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Eldred Habert
Rangi
Eldred Habert
Rangi
vulcandth
ReiquelApplegate
Antonio Vivace
John Millikin
robbi-blechdose
Quinn
JL2210
Rangi42
sukus
Ruben Zwietering
Chris Pickel
orbea
SnDream
Evie
Marcus Huderle
Ron Nelson
Damian Yerrick
Damian YerrickandRangi
Tian(Maxwell) Yang
Antonio Vivace
rlewicki
EievuiandISSOtm
DaKnig
aaaaaa123456789
martendoandEldred Habert