Release v0.7.0

Downstream support seems to be too sparse for the time being,
not worth the tiny gain we get from it

.checkpatch.conf

@@ -1,88 +0,0 @@
-# Configuration for checkpatch.pl
-# ===============================
-
-# Enable more tests
---strict
-
-# Quiet
---quiet
-
-# No per-file summary
---no-summary
-
-# Don't expect the Linux kernel tree
---no-tree
-
-# Show file line, not input line
---showfile
-
-# Don't expect SPDX tag in the first line of a file
---ignore SPDX_LICENSE_TAG
-
-# Don't expect Signed-off-by lines in commit messages
---no-signoff
-
-# List of ignored rules
-# ---------------------
-
-# There's no BIT macro
---ignore BIT_MACRO
-
-# Don't complain when bools are used in structs
---ignore BOOL_MEMBER
-
-# Allow CamelCase
---ignore CAMELCASE
-
-# Comparing to NULL explicitly isn't a bad thing
---ignore COMPARISON_TO_NULL
-
-# Causes false positives
---ignore COMPLEX_MACRO
-
-# Don't complain about structs not being const
---ignore CONST_STRUCT
-
-# Don't complain about printing "warning:" without the function name, as warning
-# printing is relevant to the code being parsed, not RGBDS' code
---ignore EMBEDDED_FUNCTION_NAME
-
-# Do not check the format of commit messages
---ignore GIT_COMMIT_ID
-
-# Do not check for global initializers (this is specific to the kernel)
---ignore GLOBAL_INITIALISERS
-
-# Don't complain about initializing statics (this is specific to the kernel)
---ignore INITIALISED_STATIC
-
-# We don't have a MAINTAINERS file, don't complain about it.
---ignore FILE_PATH_CHANGES
-
-# Writing the continuation on the start of the line can make it clearer
---ignore LOGICAL_CONTINUATIONS
-
-# Don't complain if a line that contains a string is too long. It's better to
-# have a really long line that can be found with grep.
---ignore LONG_LINE_STRING
-
-# Don't complain when files are modified in 'include/asm'
---ignore MODIFIED_INCLUDE_ASM
-
-# Allow new typedefs
---ignore NEW_TYPEDEFS
-
-# We allow lines ending with parentheses for the usage prints
---ignore OPEN_ENDED_LINE
-
-# Prefer stdint.h types over kernel types
---ignore PREFER_KERNEL_TYPES
-
-# Don't ask to replace sscanf by kstrto
---ignore SSCANF_TO_KSTRTO
-
-# Parentheses can make the code clearer
---ignore UNNECESSARY_PARENTHESES
-
-# We don't have `fallthrough;` */
---ignore PREFER_FALLTHROUGH

.clang-format

@@ -93,7 +93,7 @@ SpacesInConditionalStatement: false
 SpacesInContainerLiterals: false
 SpacesInParentheses: false
 SpacesInSquareBrackets: false
-Standard: c++17
+Standard: c++20
 TabWidth: 4
 UseCRLF: false
 UseTab: ForIndentation

.dockerignore

@@ -1,7 +1,3 @@
-# This file is part of RGBDS.
-#
-# Copyright (c) 2018-2019, Phil Smith and RGBDS contributors.
-#
 # SPDX-License-Identifier: MIT
 .git
 docs

.gitattributes

@@ -1,2 +1,6 @@
 # Shell scripts need Unix line endings (see https://github.com/gbdev/rgbds/issues/841)
 *.sh text eol=lf
+*.bash text eol=lf
+
+# Flags also need Unix line endings (see https://github.com/gbdev/rgbds/issues/955)
+*.flags text eol=lf

.github/FUNDING.yml

@@ -1 +1,2 @@
 open_collective: gbdev
+github: gbdev

.github/actions/mingw-configure.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-
-source mingw-env @TRIPLE@
-echo LAST IS: $last
-
-# check if last arg is a path to configure, else use parent
-for last; do true; done
-if test -x "${last}/configure"; then
-  config_path="$last"
-else
-  config_path=".."
-fi
-
-${config_path}/configure \
-  --host=@TRIPLE@ --target=@TRIPLE@ --build="$CHOST" \
-  --prefix=/usr/@TRIPLE@ --libdir=/usr/@TRIPLE@/lib --includedir=/usr/@TRIPLE@/include \
-  --enable-shared --enable-static "$@"

.github/actions/mingw-env.sh

@@ -1,16 +0,0 @@
-#!/bin/sh
-
-_arch=$1
-
-default_mingw_pp_flags="-D_FORTIFY_SOURCE=2"
-default_mingw_compiler_flags="$default_mingw_pp_flags -O2 -pipe -fno-plt -fexceptions --param=ssp-buffer-size=4"
-default_mingw_linker_flags="-Wl,-O1,--sort-common,--as-needed -fstack-protector"
-
-export CPPFLAGS="${MINGW_CPPFLAGS:-$default_mingw_pp_flags $CPPFLAGS}"
-export CFLAGS="${MINGW_CFLAGS:-$default_mingw_compiler_flags $CFLAGS}"
-export CXXFLAGS="${MINGW_CXXFLAGS:-$default_mingw_compiler_flags $CXXFLAGS}"
-export LDFLAGS="${MINGW_LDFLAGS:-$default_mingw_linker_flags $LDFLAGS}"
-
-mingw_prefix=/usr/${_arch}
-export PKG_CONFIG_SYSROOT_DIR="${mingw_prefix}"
-export PKG_CONFIG_LIBDIR="${mingw_prefix}/lib/pkgconfig:${mingw_prefix}/share/pkgconfig"

.github/actions/mingw-w64-libpng-dev.sh

@@ -1,44 +0,0 @@
-#!/bin/sh
-
-# This script was written by ISSOtm while looking at Arch Linux's PKGBUILD for
-# the corresponding package. (And its dependencies)
-# https://aur.archlinux.org/packages/mingw-w64-libpng/
-
-set -e
-
-pngver=1.6.37
-_apngver=$pngver
-_arch="$1"
-
-
-## Install mingw-configure and mingw-env (both build dependencies)
-
-install -m 755 .github/actions/mingw-env.sh /usr/bin/mingw-env
-
-sed "s|@TRIPLE@|${_arch}|g" .github/actions/mingw-configure.sh > ${_arch}-configure
-install -m 755 ${_arch}-configure /usr/bin/
-
-
-## Grab sources and check them
-
-wget http://downloads.sourceforge.net/sourceforge/libpng/libpng-$pngver.tar.xz
-wget http://downloads.sourceforge.net/project/apng/libpng/libpng16/libpng-$_apngver-apng.patch.gz
-sha256sum -c .github/actions/mingw-w64-libpng-dev.sha256sums
-
-## Extract sources
-
-tar -xf libpng-$pngver.tar.xz
-gunzip libpng-$_apngver-apng.patch.gz
-
-
-## Start building!
-
-cd libpng-$pngver
-# Patch in apng support
-patch -p0 ../libpng-$_apngver-apng.patch
-
-mkdir -p build-${_arch}
-cd build-${_arch}
-${_arch}-configure LDFLAGS=-static-libgcc
-make
-make install

.github/scripts/get_win_deps.ps1

@@ -0,0 +1,23 @@
+function getlibrary ([string] $URI, [string] $filename, [string] $hash, [string] $destdir) {
+	$wc = New-Object Net.WebClient
+	[string] $downloadhash = $null
+	try {
+		$wc.DownloadFile($URI, $filename)
+		$downloadhash = $(Get-FileHash $filename -Algorithm SHA256).Hash
+	} catch {
+		Write-Host "${filename}: failed to download"
+		exit 1
+	}
+	if ($hash -ne $downloadhash) {
+		Write-Host "${filename}: SHA256 mismatch ($downloadhash)"
+		exit 1
+	}
+	Expand-Archive -DestinationPath $destdir $filename
+}
+
+getlibrary 'https://www.zlib.net/zlib13.zip' 'zlib.zip' 'c561d09347f674f0d72692e7c75d9898919326c532aab7f8c07bb43b07efeb38' .
+getlibrary 'https://github.com/glennrp/libpng/archive/refs/tags/v1.6.37.zip' 'libpng.zip'  'c2c50c13a727af73ecd3fc0167d78592cf5e0bca9611058ca414b6493339c784' .
+getlibrary 'https://github.com/lexxmark/winflexbison/releases/download/v2.5.24/win_flex_bison-2.5.24.zip' 'winflexbison.zip'  '39c6086ce211d5415500acc5ed2d8939861ca1696aee48909c7f6daf5122b505' install_dir
+
+Move-Item zlib-1.3 zlib
+Move-Item libpng-1.6.37 libpng

.github/scripts/install.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+install -d /usr/local/bin/ /usr/local/share/man/man1/ /usr/local/share/man/man5/ /usr/local/share/man/man7/
+install -s -m 755 rgbasm rgblink rgbfix rgbgfx /usr/local/bin/
+install -m 644 rgbasm.1 rgblink.1 rgbfix.1 rgbgfx.1 /usr/local/share/man/man1/
+install -m 644 rgbds.5 rgbasm.5 rgblink.5 /usr/local/share/man/man5/
+install -m 644 rgbds.7 gbz80.7 /usr/local/share/man/man7/

.github/scripts/install_deps.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e
 
 case "${1%-*}" in

.github/scripts/mingw-w64-libpng-dev.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+set -e
+
+pngver=1.6.37
+arch="$1"
+
+## Grab sources and check them
+
+wget http://downloads.sourceforge.net/project/libpng/libpng16/$pngver/libpng-$pngver.tar.xz
+wget http://downloads.sourceforge.net/project/apng/libpng/libpng16/libpng-$pngver-apng.patch.gz
+sha256sum -c .github/scripts/mingw-w64-libpng-dev.sha256sums
+
+## Extract sources and patch them
+
+tar -xf libpng-$pngver.tar.xz
+gunzip libpng-$pngver-apng.patch.gz
+
+# Patch in apng support
+env -C libpng-$pngver patch -p0 ../libpng-$pngver-apng.patch
+
+## Start building!
+
+mkdir -p build
+cd build
+../libpng-$pngver/configure \
+	--host="$arch" --target="$arch" \
+	--prefix="/usr/$arch" \
+	--enable-shared --disable-static \
+	CPPFLAGS="-D_FORTIFY_SOURCE=2" \
+	CFLAGS="-O2 -pipe -fno-plt -fexceptions --param=ssp-buffer-size=4" \
+	LDFLAGS="-Wl,-O1,--sort-common,--as-needed -fstack-protector"
+make -kj
+make install

.github/workflows/checkpatch.yml

@@ -1,25 +0,0 @@
-name: "Code style checking"
-on: pull_request
-
-jobs:
-  checkpatch:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Set up repo
-        run: |
-          git clone -b "${{ github.event.pull_request.head.ref }}" "${{ github.event.pull_request.head.repo.clone_url }}" rgbds
-          cd rgbds
-          git remote add upstream "${{ github.event.pull_request.base.repo.clone_url }}"
-          git fetch upstream
-      - name: Set up checkpatch
-        working-directory: rgbds
-        run: |
-          wget 'https://raw.githubusercontent.com/torvalds/linux/master/scripts/checkpatch.pl'
-          chmod +x checkpatch.pl
-          wget 'https://raw.githubusercontent.com/torvalds/linux/master/scripts/const_structs.checkpatch'
-          wget 'https://raw.githubusercontent.com/torvalds/linux/master/scripts/spelling.txt'
-      - name: Checkpatch
-        working-directory: rgbds
-        run: |
-          make checkpatch CHECKPATCH=./checkpatch.pl "BASE_REF=${{ github.event.pull_request.base.sha }}" Q= | tee log
-          if grep -q ERROR: log; then exit 1; else exit 0; fi

.github/workflows/create-release-artifacts.yaml

@@ -1,96 +0,0 @@
-name: "Create release artifacts"
-on:
-  push:
-    tags:
-      - v[0-9]*
-
-jobs:
-  windows:
-    runs-on: windows-2019
-    steps:
-      - uses: actions/checkout@v2
-      - name: Get version from tag
-        shell: bash
-        run: | # Turn "refs/tags/vX.Y.Z" into "X.Y.Z"
-          VERSION="${{ github.ref }}"
-          echo "version=${VERSION##*/v}" >> $GITHUB_ENV
-      - name: Get zlib, libpng and bison
-        run: | # TODO: use an array
-          $wc = New-Object System.Net.WebClient
-          $wc.DownloadFile('https://www.zlib.net/zlib1212.zip', 'zlib.zip')
-          $hash = (Get-FileHash "zlib.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '173e89893dcb8b4a150d7731cd72f0602f1d6b45e60e2a54efdf7f3fc3325fd7') {
-            Write-Host "zlib SHA256 mismatch! ($hash)"
-            exit 1
-          }
-          $wc.DownloadFile('https://download.sourceforge.net/libpng/lpng1637.zip', 'libpng.zip')
-          $hash = (Get-FileHash "libpng.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '3b4b1cbd0bae6822f749d39b1ccadd6297f05e2b85a83dd2ce6ecd7d09eabdf2') {
-            Write-Host "libpng SHA256 mismatch! ($hash)"
-            exit 1
-          }
-          $wc.DownloadFile('https://github.com/lexxmark/winflexbison/releases/download/v2.5.24/win_flex_bison-2.5.24.zip', 'winflexbison.zip')
-          $hash = (Get-FileHash "winflexbison.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '39c6086ce211d5415500acc5ed2d8939861ca1696aee48909c7f6daf5122b505') {
-            Write-Host "bison SHA256 mismatch! ($hash)"
-          }
-          Expand-Archive -DestinationPath .           "zlib.zip"
-          Expand-Archive -DestinationPath .           "libpng.zip"
-          Expand-Archive -DestinationPath install_dir "winflexbison.zip"
-          Move-Item zlib-1.2.12 zlib
-          Move-Item lpng1637 libpng
-      - name: Build 32-bit zlib
-        run: | # BUILD_SHARED_LIBS causes the output DLL to be correctly called `zlib1.dll`
-          cmake -S zlib -B zbuild32 -A Win32 -DCMAKE_INSTALL_PREFIX=install_dir -DBUILD_SHARED_LIBS=ON
-          cmake --build zbuild32 --config Release
-          cmake --install zbuild32
-      - name: Build 32-bit libpng
-        run: |
-          cmake -S libpng -B pngbuild32 -A Win32 -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=ON -DPNG_TESTS=OFF
-          cmake --build pngbuild32 --config Release
-          cmake --install pngbuild32
-      - name: Build 32-bit Windows binaries
-        run: |
-          cmake -S . -B build32 -A Win32 -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release
-          cmake --build build32 --config Release
-          cmake --install build32
-      - name: Package 32-bit binaries
-        run: |
-          Compress-Archive -LiteralPath @("install_dir/bin/rgbasm.exe", "install_dir/bin/rgblink.exe", "install_dir/bin/rgbfix.exe", "install_dir/bin/rgbgfx.exe", "install_dir/bin/zlib1.dll", "install_dir/bin/libpng16.dll") "rgbds-${{ env.version }}-win32.zip"
-      - name: Build 64-bit zlib
-        run: | # BUILD_SHARED_LIBS causes the output DLL to be correctly called `zlib1.dll`
-          cmake -S zlib -B zbuild64 -A x64 -DCMAKE_INSTALL_PREFIX=install_dir -DBUILD_SHARED_LIBS=ON
-          cmake --build zbuild64 --config Release
-          cmake --install zbuild64
-      - name: Build 64-bit libpng
-        run: |
-          cmake -S libpng -B pngbuild64 -A x64 -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=ON -DPNG_TESTS=OFF
-          cmake --build pngbuild64 --config Release
-          cmake --install pngbuild64
-      - name: Build 64-bit Windows binaries
-        run: |
-          cmake -S . -B build64 -A x64 -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release
-          cmake --build build64 --config Release
-          cmake --install build64
-      - name: Package 64-bit binaries
-        run: |
-          Compress-Archive -LiteralPath @("install_dir/bin/rgbasm.exe", "install_dir/bin/rgblink.exe", "install_dir/bin/rgbfix.exe", "install_dir/bin/rgbgfx.exe", "install_dir/bin/zlib1.dll", "install_dir/bin/libpng16.dll") "rgbds-${{ env.version }}-win64.zip"
-      - name: Package sources
-        run: |
-          make dist
-      - name: Release
-        uses: softprops/action-gh-release@v1
-        with:
-          body: |
-            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...
-          prerelease: ${{ contains(github.ref, '-rc') }}
-          files: |
-            rgbds-${{ env.version }}-win32.zip
-            rgbds-${{ env.version }}-win64.zip
-            rgbds-${{ env.version }}.tar.gz
-          fail_on_unmatched_files: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/create-release-artifacts.yml

@@ -0,0 +1,153 @@
+name: "Create release artifacts"
+on:
+  push:
+    tags:
+      - v[0-9]*
+
+jobs:
+  windows:
+    runs-on: windows-2022
+    strategy:
+      matrix:
+        bits: [32, 64]
+        include:
+          - bits: 32
+            arch: x86
+            platform: Win32
+          - bits: 64
+            arch: x86_x64
+            platform: x64
+      fail-fast: false
+    steps:
+      - name: Get version from tag
+        shell: bash
+        run: | # Turn "vX.Y.Z" into "X.Y.Z"
+          VERSION="${{ github.ref_name }}"
+          echo "version=${VERSION#v}" >> $GITHUB_ENV
+      - uses: actions/checkout@v3
+      - name: Install deps
+        run: .github/scripts/get_win_deps.ps1
+      - uses: actions/cache@v3
+        id: cache
+        with:
+          path: |
+            zbuild
+            pngbuild
+          key: ${{ matrix.arch }}-${{ hashFiles('zlib/**', 'libpng/**') }}
+      - name: Build zlib
+        run: | # BUILD_SHARED_LIBS causes the output DLL to be correctly called `zlib1.dll`
+          cmake -S zlib -B zbuild -A ${{ matrix.platform }} -Wno-dev -DCMAKE_INSTALL_PREFIX=install_dir -DBUILD_SHARED_LIBS=ON
+          cmake --build zbuild --config Release -j
+        if: steps.cache.outputs.cache-hit != 'true'
+      - name: Install zlib
+        run: |
+          cmake --install zbuild
+      - name: Build libpng
+        shell: bash
+        run: |
+          cmake -S libpng -B pngbuild -A ${{ matrix.platform }} -Wno-dev -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=OFF -DPNG_TESTS=OFF -DPNG_BUILD_ZLIB=ON -DZLIB_INCLUDE_DIR="$PWD"/install_dir/include -DZLIB_LIBRARY="$PWD"/install_dir/lib/zlib.lib
+          cmake --build pngbuild --config Release -j
+        if: steps.cache.outputs.cache-hit != 'true'
+      - name: Install libpng
+        run: |
+          cmake --install pngbuild
+      - name: Build Windows binaries
+        shell: bash
+        run: |
+          cmake -S . -B build -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release -DZLIB_LIBRARY="$PWD"/install_dir/lib/zlib.lib -DZLIB_INCLUDE_DIR="$PWD"/install_dir/include -DPNG_LIBRARY="$PWD"/install_dir/lib/libpng16.lib -DPNG_INCLUDE_DIR="$PWD"/install_dir/include
+          cmake --build build --config Release -j --verbose
+          cmake --install build --verbose --prefix install_dir --strip
+      - name: Package binaries
+        run: |
+          Compress-Archive -LiteralPath @("install_dir/bin/rgbasm.exe", "install_dir/bin/rgblink.exe", "install_dir/bin/rgbfix.exe", "install_dir/bin/rgbgfx.exe", "install_dir/bin/zlib1.dll", "install_dir/bin/libpng16.dll") "rgbds-${{ env.version }}-win${{ matrix.bits }}.zip"
+      - name: Upload Windows binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: win${{ matrix.bits }}
+          path: rgbds-${{ env.version }}-win${{ matrix.bits }}.zip
+
+  macos:
+    runs-on: macos-12
+    steps:
+      - name: Get version from tag
+        shell: bash
+        run: | # Turn "refs/tags/vX.Y.Z" into "X.Y.Z"
+          VERSION="${{ github.ref_name }}"
+          echo "version=${VERSION#v}" >> $GITHUB_ENV
+      - uses: actions/checkout@v3
+      - name: Install deps
+        shell: bash
+        run: |
+          ./.github/scripts/install_deps.sh macos-latest
+      # We force linking libpng statically; the other libs are provided by macOS itself
+      - name: Build binaries
+        run: |
+          export PATH="/usr/local/opt/bison/bin:$PATH"
+          make -j CXXFLAGS="-O3 -flto -DNDEBUG -mmacosx-version-min=10.9" PKG_CONFIG="pkg-config --static" PNGLDLIBS="$(pkg-config --static --libs-only-L libpng | cut -c 3-)/libpng.a $(pkg-config --static --libs-only-l libpng | sed s/-lpng[0-9]*//g)" Q=
+      - name: Package binaries
+        run: |
+          zip --junk-paths rgbds-${{ env.version }}-macos-x86_64.zip rgb{asm,link,fix,gfx} man/* .github/scripts/install.sh
+      - name: Upload macOS binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: macos
+          path: rgbds-${{ env.version }}-macos-x86_64.zip
+
+  linux:
+    runs-on: ubuntu-20.04 # Oldest supported, for best glibc compatibility.
+    steps:
+      - name: Get version from tag
+        shell: bash
+        run: | # Turn "refs/tags/vX.Y.Z" into "X.Y.Z"
+          VERSION="${{ github.ref_name }}"
+          echo "version=${VERSION#v}" >> $GITHUB_ENV
+      - uses: actions/checkout@v3
+      - name: Install deps
+        shell: bash
+        run: |
+          ./.github/scripts/install_deps.sh ubuntu-20.04
+      - name: Build binaries
+        run: |
+          make -j WARNFLAGS="-Wall -Wextra -pedantic  -static" PKG_CONFIG="pkg-config --static" Q=
+      - name: Package binaries
+        run: |
+          tar caf rgbds-${{ env.version }}-linux-x86_64.tar.xz --transform='s#.*/##' rgb{asm,link,fix,gfx} man/* .github/scripts/install.sh
+      - name: Upload Linux binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: linux
+          path: rgbds-${{ env.version }}-linux-x86_64.tar.xz
+
+  release:
+    runs-on: ubuntu-latest
+    needs: [windows, macos, linux]
+    steps:
+      - name: Get version from tag
+        shell: bash
+        run: | # Turn "refs/tags/vX.Y.Z" into "X.Y.Z"
+          VERSION="${{ github.ref_name }}"
+          echo "version=${VERSION#v}" >> $GITHUB_ENV
+      - uses: actions/checkout@v3
+      - name: Package sources
+        run: |
+          make dist Q=
+          ls
+      - uses: actions/download-artifact@v3
+      - name: Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: |
+            Please ensure that the four 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 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...
+          prerelease: ${{ contains(github.ref, '-rc') }}
+          files: |
+            win32/rgbds-${{ env.version }}-win32.zip
+            win64/rgbds-${{ env.version }}-win64.zip
+            macos/rgbds-${{ env.version }}-macos-x86_64.zip
+            linux/rgbds-${{ env.version }}-linux-x86_64.tar.xz
+            rgbds-${{ env.version }}.tar.gz
+          fail_on_unmatched_files: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/create-release-docs.yml

@@ -7,32 +7,26 @@ on:
 jobs:
   build:
     if: github.repository_owner == 'gbdev'
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout rgbds@release
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: rgbds
       - name: Checkout rgbds-www@master
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: ${{ github.repository_owner }}/rgbds-www
           path: rgbds-www
-      # `-O toc` was added in 1.14.5, but the repos only have 1.14.4
+      - name: Install groff and mandoc
-      - name: Build and install mandoc + install groff
         run: |
           sudo apt-get -qq update
-          sudo apt-get install -yq groff zlib1g-dev
+          sudo apt-get install -yq groff mandoc
-          wget 'http://mandoc.bsd.lv/snapshots/mandoc-1.14.6.tar.gz'
-          tar xf mandoc-1.14.6.tar.gz
-          cd mandoc-1.14.6
-          ./configure
-          make
-          sudo make install
       - name: Update pages
         working-directory: rgbds/man
         run: | # The ref appears to be in the format "refs/tags/<version>", so strip that
-          ../../rgbds-www/.github/actions/get-pages.sh ${GITHUB_REF##*/} *
+          ../../rgbds-www/maintainer/man_to_html.sh ${GITHUB_REF##*/} *
+          ../../rgbds-www/maintainer/new_release.sh ${GITHUB_REF##*/}
       - name: Push new pages
         working-directory: rgbds-www
         run: |

.github/workflows/testing.yml

@@ -4,48 +4,44 @@ on:
   - pull_request
 
 jobs:
-  unix-testing:
+  unix:
     strategy:
       matrix:
-        os: [ubuntu-20.04, ubuntu-18.04, macos-11.0, macos-10.15]
+        os: [ubuntu-20.04, ubuntu-22.04, macos-11, macos-12]
-        cc: [gcc, clang]
+        cxx: [g++, clang++]
         buildsys: [make, cmake]
         exclude:
-          # `gcc` is just an alias to `clang` on macOS, don't bother
+          # Don't use `g++` on macOS; it's just an alias to `clang++`.
-          - os: macos-10.15
+          - os: macos-11
-            cc: gcc
+            cxx: g++
-          - os: macos-11.0
+          - os: macos-12
-            cc: gcc
-        include:
-          - cc: gcc
             cxx: g++
-          - cc: clang
-            cxx: clang++
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Install deps
         shell: bash
         run: |
-          ./.github/actions/install_deps.sh ${{ matrix.os }}
+          ./.github/scripts/install_deps.sh ${{ matrix.os }}
-      # The `export` lines are to allow working on macOS...
+      # Export `bison` to allow using the version we install from Homebrew,
-      # Apple's base version is severely outdated, not even supporting -Wall,
+      # instead of the outdated one preinstalled on macOS (which doesn't
-      # but it overrides Homebrew's version nonetheless...
+      # even support `-Wall`...).
       - name: Build & install using Make
         if: matrix.buildsys == 'make'
         run: |
           export PATH="/usr/local/opt/bison/bin:$PATH"
-          make develop -j Q= CC=${{ matrix.cc }} CXX=${{ matrix.cxx }}
+          make develop -j Q= CXX=${{ matrix.cxx }}
           sudo make install -j Q=
       - name: Build & install using CMake
         if: matrix.buildsys == 'cmake'
         run: |
           export PATH="/usr/local/opt/bison/bin:$PATH"
-          cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=${{ matrix.cc }} -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} -DSANITIZERS=ON -DMORE_WARNINGS=ON
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} -DSANITIZERS=ON -DMORE_WARNINGS=ON
           cmake --build build -j --verbose
           cp build/src/rgb{asm,link,fix,gfx} .
           sudo cmake --install build --verbose
+          cmake --install build --verbose --component "Test support programs"
       - name: Package binaries
         run: |
           mkdir bins
@@ -53,17 +49,98 @@ jobs:
       - name: Upload binaries
         uses: actions/upload-artifact@v3
         with:
-          name: rgbds-canary-${{ matrix.os }}-${{ matrix.cc }}-${{ matrix.buildsys }}
+          name: rgbds-canary-${{ matrix.os }}-${{ matrix.cxx }}-${{ matrix.buildsys }}
           path: bins
-      - name: Test
+      - name: Compute test dependency cache params
+        id: test-deps-cache-params
+        shell: bash
+        run: |
+          paths=$(test/fetch-test-deps.sh --get-paths)
+          hash=$(test/fetch-test-deps.sh --get-hash)
+          tee -a <<<"paths=\"${paths//,/\\n}\"" $GITHUB_OUTPUT
+          tee -a <<<"hash=${hash%-}" $GITHUB_OUTPUT
+      - name: Check test dependency repositories cache
+        id: test-deps-cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ fromJSON(steps.test-deps-cache-params.outputs.paths) }}
+          key: ${{ matrix.os }}-${{ steps.test-deps-cache-params.outputs.hash }}
+      - if: steps.test-deps-cache.outputs.cache-hit != 'true'
+        name: Fetch test dependency repositories
+        continue-on-error: true
+        run: |
+          test/fetch-test-deps.sh
+      - name: Install test dependency dependencies
+        shell: bash
+        run: |
+          test/fetch-test-deps.sh --get-deps ${{ matrix.os }}
+      - name: Run tests
         shell: bash
         run: |
           test/run-tests.sh
 
-  windows-testing:
+  macos-static:
+    strategy:
+      matrix:
+        # Don't run on macOS 11; our setup makes clang segfault (YES).
+        os: [macos-12]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install deps
+        shell: bash
+        run: |
+          ./.github/scripts/install_deps.sh ${{ matrix.os }}
+      # Export `bison` to allow using the version we install from Homebrew,
+      # instead of the outdated one preinstalled on macOS (which doesn't
+      # even support `-Wall`...).
+      - name: Build & install
+        run: |
+          export PATH="/usr/local/opt/bison/bin:$PATH"
+          make -j CXXFLAGS="-O3 -flto -DNDEBUG -mmacosx-version-min=10.9" PKG_CONFIG="pkg-config --static" PNGLDLIBS="$(pkg-config --static --libs-only-L libpng | cut -c 3-)/libpng.a $(pkg-config --static --libs-only-l libpng | sed s/-lpng[0-9]*//g)" Q=
+      - name: Package binaries
+        run: |
+          mkdir bins
+          cp rgb{asm,link,fix,gfx} bins
+      - name: Upload binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: rgbds-canary-${{ matrix.os }}-${{ matrix.buildsys }}
+          path: bins
+      - name: Compute test dependency cache params
+        id: test-deps-cache-params
+        shell: bash
+        run: |
+          paths=$(test/fetch-test-deps.sh --get-paths)
+          hash=$(test/fetch-test-deps.sh --get-hash)
+          tee -a <<<"paths=\"${paths//,/\\n}\"" $GITHUB_OUTPUT
+          tee -a <<<"hash=${hash%-}" $GITHUB_OUTPUT
+      - name: Check test dependency repositories cache
+        id: test-deps-cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ fromJSON(steps.test-deps-cache-params.outputs.paths) }}
+          key: ${{ matrix.os }}-${{ steps.test-deps-cache-params.outputs.hash }}
+      - if: steps.test-deps-cache.outputs.cache-hit != 'true'
+        name: Fetch test dependency repositories
+        continue-on-error: true
+        run: |
+          test/fetch-test-deps.sh
+      - name: Install test dependency dependencies
+        shell: bash
+        run: |
+          test/fetch-test-deps.sh --get-deps ${{ matrix.os }}
+      - name: Run tests
+        shell: bash
+        run: |
+          test/run-tests.sh
+
+  windows:
     strategy:
       matrix:
         bits: [32, 64]
+        os: [windows-2019, windows-2022]
         include:
           - bits: 32
             arch: x86
@@ -72,34 +149,11 @@ jobs:
             arch: x86_x64
             platform: x64
       fail-fast: false
-    runs-on: windows-2019
+    runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
-      - name: Get zlib, libpng and bison
+      - name: Install deps
-        run: | # TODO: use an array; remember to update the versions being downloaded, *and* the paths being extracted! (`Move-Item`)
+        run: .github/scripts/get_win_deps.ps1
-          $wc = New-Object System.Net.WebClient
-          $wc.DownloadFile('https://www.zlib.net/zlib1212.zip', 'zlib.zip')
-          $hash = (Get-FileHash "zlib.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '173e89893dcb8b4a150d7731cd72f0602f1d6b45e60e2a54efdf7f3fc3325fd7') {
-            Write-Host "zlib SHA256 mismatch! ($hash)"
-            exit 1
-          }
-          $wc.DownloadFile('https://download.sourceforge.net/libpng/lpng1637.zip', 'libpng.zip')
-          $hash = (Get-FileHash "libpng.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '3b4b1cbd0bae6822f749d39b1ccadd6297f05e2b85a83dd2ce6ecd7d09eabdf2') {
-            Write-Host "libpng SHA256 mismatch! ($hash)"
-            exit 1
-          }
-          $wc.DownloadFile('https://github.com/lexxmark/winflexbison/releases/download/v2.5.24/win_flex_bison-2.5.24.zip', 'winflexbison.zip')
-          $hash = (Get-FileHash "winflexbison.zip" -Algorithm SHA256).Hash
-          if ($hash -ne '39c6086ce211d5415500acc5ed2d8939861ca1696aee48909c7f6daf5122b505') {
-            Write-Host "bison SHA256 mismatch! ($hash)"
-          }
-          Expand-Archive -DestinationPath .           "zlib.zip"
-          Expand-Archive -DestinationPath .           "libpng.zip"
-          Expand-Archive -DestinationPath install_dir "winflexbison.zip"
-          Move-Item zlib-1.2.12 zlib
-          Move-Item lpng1637 libpng
       - uses: actions/cache@v3
         id: cache
         with:
@@ -109,25 +163,28 @@ jobs:
           key: ${{ matrix.arch }}-${{ hashFiles('zlib/**', 'libpng/**') }}
       - name: Build zlib
         run: | # BUILD_SHARED_LIBS causes the output DLL to be correctly called `zlib1.dll`
-          cmake -S zlib -B zbuild -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DBUILD_SHARED_LIBS=ON
+          cmake -S zlib -B zbuild -A ${{ matrix.platform }} -Wno-dev -DCMAKE_INSTALL_PREFIX=install_dir -DBUILD_SHARED_LIBS=ON
           cmake --build zbuild --config Release -j
         if: steps.cache.outputs.cache-hit != 'true'
       - name: Install zlib
         run: |
           cmake --install zbuild
       - name: Build libpng
+        shell: bash
         run: |
-          cmake -S libpng -B pngbuild -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=ON -DPNG_TESTS=OFF
+          cmake -S libpng -B pngbuild -A ${{ matrix.platform }} -Wno-dev -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=OFF -DPNG_TESTS=OFF -DPNG_BUILD_ZLIB=ON -DZLIB_INCLUDE_DIR="$PWD"/install_dir/include -DZLIB_LIBRARY="$PWD"/install_dir/lib/zlib.lib
           cmake --build pngbuild --config Release -j
         if: steps.cache.outputs.cache-hit != 'true'
       - name: Install libpng
         run: |
           cmake --install pngbuild
       - name: Build Windows binaries
+        shell: bash
         run: |
-          cmake -S . -B build -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release
+          cmake -S . -B build -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release -DZLIB_LIBRARY="$PWD"/install_dir/lib/zlib.lib -DZLIB_INCLUDE_DIR="$PWD"/install_dir/include -DPNG_LIBRARY="$PWD"/install_dir/lib/libpng16.lib -DPNG_INCLUDE_DIR="$PWD"/install_dir/include
           cmake --build build --config Release -j --verbose
           cmake --install build --verbose --prefix install_dir
+          cmake --install build --verbose --component "Test support programs"
       - name: Package binaries
         shell: bash
         run: |
@@ -138,18 +195,41 @@ jobs:
         with:
           name: rgbds-canary-win${{ matrix.bits }}
           path: bins
-      - name: Test
+      - name: Compute test dependency cache params
+        id: test-deps-cache-params
+        shell: bash
+        run: |
+          paths=$(test/fetch-test-deps.sh --get-paths)
+          hash=$(test/fetch-test-deps.sh --get-hash)
+          tee -a <<<"paths=\"${paths//,/\\n}\"" $GITHUB_OUTPUT
+          tee -a <<<"hash=${hash%-}" $GITHUB_OUTPUT
+      - name: Check test dependency repositories cache
+        id: test-deps-cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ fromJSON(steps.test-deps-cache-params.outputs.paths) }}
+          key: ${{ matrix.os }}-${{ matrix.bits }}-${{ steps.test-deps-cache-params.outputs.hash }}
+      - if: steps.test-deps-cache.outputs.cache-hit != 'true'
+        name: Fetch test dependency repositories
+        shell: bash
+        continue-on-error: true
+        run: |
+          test/fetch-test-deps.sh
+      - name: Install test dependency dependencies
+        shell: bash
+        run: |
+          test/fetch-test-deps.sh --get-deps ${{ matrix.os }}
+      - name: Run tests
         shell: bash
         run: |
           cp bins/* .
           cp bins/*.dll test/gfx
           test/run-tests.sh
 
-  windows-xbuild:
+  windows-mingw-build:
     strategy:
       matrix:
         bits: [32, 64]
-        os: [ubuntu-18.04]
         include:
           - bits: 32
             arch: i686
@@ -158,36 +238,32 @@ jobs:
             arch: x86-64
             triplet: x86_64-w64-mingw32
       fail-fast: false
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-22.04
     env:
       DIST_DIR: win${{ matrix.bits }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Install deps
         shell: bash
         run: |
-          ./.github/actions/install_deps.sh ${{ matrix.os }}
+          ./.github/scripts/install_deps.sh ${{ matrix.os }}
       - name: Install MinGW
-        run: |
+        run: | # dpkg-dev is apparently required for pkg-config for cross-building
-          sudo apt-get install {gcc,g++}-mingw-w64-${{ matrix.arch }} mingw-w64-tools libz-mingw-w64-dev
+          sudo apt-get install g++-mingw-w64-${{ matrix.arch }}-win32 mingw-w64-tools libz-mingw-w64-dev dpkg-dev
       - name: Install libpng dev headers for MinGW
         run: |
-          sudo ./.github/actions/mingw-w64-libpng-dev.sh ${{ matrix.triplet }}
+          sudo ./.github/scripts/mingw-w64-libpng-dev.sh ${{ matrix.triplet }}
       - name: Cross-build Windows binaries
         run: |
           make mingw${{ matrix.bits }} -j Q=
       - name: Package binaries
-        run: |
+        run: | # DLL dependencies can be figured out using e.g. Dependency Walker or objdump -p
           mkdir bins
-          mv rgbasm bins/rgbasm.exe
+          mv -v rgb{asm,link,fix,gfx}.exe bins/
-          mv rgblink bins/rgblink.exe
+          cp -v /usr/${{ matrix.triplet }}/lib/zlib1.dll bins
-          mv rgbfix bins/rgbfix.exe
+          cp -v /usr/${{ matrix.triplet }}/bin/libpng16-16.dll bins
-          mv rgbgfx bins/rgbgfx.exe
+          cp -v /usr/lib/gcc/${{ matrix.triplet }}/10-win32/lib{ssp-0,stdc++-6}.dll bins
-          cp /usr/${{ matrix.triplet }}/lib/zlib1.dll bins
+          [ "${{ matrix.bits }}" -ne 32 ] || cp -v /usr/lib/gcc/${{ matrix.triplet }}/10-win32/libgcc_s_dw2-1.dll bins
-          cp /usr/${{ matrix.triplet }}/bin/libpng16-16.dll bins
-          if [ ${{ matrix.bits }} -eq 32 ]; then cp /usr/lib/gcc/${{ matrix.triplet }}/7.3-win32/lib{gcc_s_sjlj-1,stdc++-6}.dll bins; fi
-          mv test/gfx/randtilegen{,.exe}
-          mv test/gfx/rgbgfx_test{,.exe}
       - name: Upload Windows binaries
         uses: actions/upload-artifact@v3
         with:
@@ -201,15 +277,16 @@ jobs:
             test/gfx/randtilegen.exe
             test/gfx/rgbgfx_test.exe
 
-  windows-xtesting:
+  windows-mingw-testing:
-    needs: windows-xbuild
+    needs: windows-mingw-build
     strategy:
       matrix:
+        os: [windows-2019, windows-2022]
         bits: [32, 64]
       fail-fast: false
-    runs-on: windows-2019
+    runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Retrieve binaries
         uses: actions/download-artifact@v3
         with:
@@ -225,6 +302,30 @@ jobs:
         run: |
           cp bins/* .
           cp bins/*.dll test/gfx
+      - name: Compute test dependency cache params
+        id: test-deps-cache-params
+        shell: bash
+        run: |
+          paths=$(test/fetch-test-deps.sh --get-paths)
+          hash=$(test/fetch-test-deps.sh --get-hash)
+          tee -a <<<"paths=\"${paths//,/\\n}\"" $GITHUB_OUTPUT
+          tee -a <<<"hash=${hash%-}" $GITHUB_OUTPUT
+      - name: Check test dependency repositories cache
+        id: test-deps-cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ fromJSON(steps.test-deps-cache-params.outputs.paths) }}
+          key: mingw-${{ matrix.bits }}-${{ steps.test-deps-cache-params.outputs.hash }}
+      - if: steps.test-deps-cache.outputs.cache-hit != 'true'
+        name: Fetch test dependency repositories
+        shell: bash
+        continue-on-error: true
+        run: |
+          test/fetch-test-deps.sh
+      - name: Install test dependency dependencies
+        shell: bash
+        run: |
+          test/fetch-test-deps.sh --get-deps ${{ matrix.os }}
       - name: Run tests
         shell: bash
         run: |

.github/workflows/update-master-docs.yml

@@ -17,30 +17,24 @@ on:
 jobs:
   build:
     if: github.repository_owner == 'gbdev'
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout rgbds@master
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: gbdev/rgbds
           ref: master
           path: rgbds
       - name: Checkout rgbds-www@master
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: gbdev/rgbds-www
           ref: master
           path: rgbds-www
-      - name: Build and install mandoc + install groff
+      - name: Install groff and mandoc
         run: |
           sudo apt-get -qq update
-          sudo apt-get install -yq groff zlib1g-dev
+          sudo apt-get install -yq groff mandoc
-          wget 'http://mandoc.bsd.lv/snapshots/mandoc-1.14.6.tar.gz'
-          tar xf mandoc-1.14.6.tar.gz
-          cd mandoc-1.14.6
-          ./configure
-          make
-          sudo make install
       - name: Update pages
         working-directory: rgbds/man
         run: |

.gitignore

@@ -3,10 +3,13 @@
 /rgbfix
 /rgbgfx
 /rgbshim.sh
+/coverage/
 *.o
 *.exe
 *.dll
-.checkpatch-camelcase.*
+*.gcno
+*.gcda
+*.gcov
 CMakeCache.txt
 CMakeFiles/
 cmake_install.cmake

CMakeLists.txt

@@ -1,16 +1,10 @@
-#
-# This file is part of RGBDS.
-#
-# Copyright (c) 2020 RGBDS contributors.
-#
 # SPDX-License-Identifier: MIT
-#
 
 # 3.9 required for LTO checks
 cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
 
 project(rgbds
-        LANGUAGES C CXX)
+        LANGUAGES CXX)
 
 # get real path of source and binary directories
 get_filename_component(srcdir "${CMAKE_SOURCE_DIR}" REALPATH)
@@ -29,12 +23,9 @@ option(MORE_WARNINGS "Turn on more warnings" OFF) # Ignored on MSVC
 if(MSVC)
   # MSVC's standard library triggers warning C5105,
   # "macro expansion producing 'defined' has undefined behavior"
-  add_compile_options(/MP /wd5105)
+  # We also opt into the C++20-conformant preprocessor.
+  add_compile_options(/MP /wd5105 /Zc:preprocessor)
   add_definitions(/D_CRT_SECURE_NO_WARNINGS)
-  # Also, CMake appears not to pass the C11-enabling flag, so we must add it manually... but only for C!
-  if(NOT CMAKE_C_FLAGS MATCHES "std:c11") # The flag may already have been injected by an earlier CMake invocation, so don't add it twice
-    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std:c11" CACHE STRING "Flags used by the C compiler during all build types." FORCE)
-  endif()
 
   if(SANITIZERS)
     set(SAN_FLAGS /fsanitize=address)
@@ -42,8 +33,12 @@ if(MSVC)
     add_link_options(${SAN_FLAGS})
   endif()
 else()
-  add_compile_options(-Wall -pedantic)
+  # TODO: use -pedantic after non-C++ idioms are gone
-  add_definitions(-D_POSIX_C_SOURCE=200809L -D_ISOC11_SOURCE)
+  add_compile_options(-Wall)
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+    add_compile_options(-Wno-c99-designator)
+  endif()
+  add_definitions(-D_POSIX_C_SOURCE=200809L)
   if(SANITIZERS)
     set(SAN_FLAGS -fsanitize=shift -fsanitize=integer-divide-by-zero
                   -fsanitize=unreachable -fsanitize=vla-bound
@@ -52,9 +47,9 @@ else()
                   -fsanitize=alignment -fsanitize=null -fsanitize=address)
     add_compile_options(${SAN_FLAGS})
     add_link_options(${SAN_FLAGS})
+    add_definitions(-D_GLIBCXX_ASSERTIONS)
     # A non-zero optimization level is desired in debug mode, but allow overriding it nonetheless
     # TODO: this overrides anything previously set... that's a bit sloppy!
-    set(CMAKE_C_FLAGS_DEBUG "-g -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls" CACHE STRING "" FORCE)
     set(CMAKE_CXX_FLAGS_DEBUG "-g -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls" CACHE STRING "" FORCE)
   endif()
 
@@ -97,9 +92,7 @@ endif()
 
 include_directories("${PROJECT_SOURCE_DIR}/include")
 
-set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 20)
-set(CMAKE_C_STANDARD_REQUIRED True)
-set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 add_subdirectory(src)

CONTRIBUTING.rst

@@ -12,14 +12,14 @@ Bug reports are essential to improve RGBDS and they are always welcome. If you
 want to report a bug:
 
 1. Make sure that there isn't a similar issue already reported
-   `here <https://github.com/rednex/rgbds/issues>`__.
+   `here <https://github.com/gbdev/rgbds/issues>`__.
 
 2. Figure out a way of reproducing it reliably.
 
 3. If there is a piece of code that triggers the bug, try to reduce it to the
    smallest file you can.
 
-4. Create a new `issue <https://github.com/rednex/rgbds/issues>`__.
+4. Create a new `issue <https://github.com/gbdev/rgbds/issues>`__.
 
 Of course, it may not always be possible to give an accurate bug report, but it
 always helps to fix it.
@@ -30,7 +30,7 @@ Requesting new features
 If you come up with a good idea that could be implemented, you can propose it to
 be done.
 
-1. Create a new `issue <https://github.com/rednex/rgbds/issues>`__.
+1. Create a new `issue <https://github.com/gbdev/rgbds/issues>`__.
 
 2. Try to be as accurate as possible. Describe what you need and why you need
    it, maybe with examples.
@@ -49,7 +49,7 @@ if your change is going to be small (and likely to be accepted as-is) or big
 (and will have to go through some rework).
 
 Big changes will most likely require some discussion, so open an
-`issue <https://github.com/rednex/rgbds/issues>`__ and explain what you want to
+`issue <https://github.com/gbdev/rgbds/issues>`__ and explain what you want to
 do and how you intend to do it. If you already have a prototype, it's always a
 good idea to show it. Tests help, too.
 
@@ -74,22 +74,10 @@ copyright and the reference to the MIT License.
    new warning (but it may be possible to remove some warning checks if it makes
    the code much easier).
 
-5. Follow the Linux kernel coding style, which can be found in the file
+5. Format your changes according to ``clang-format``, which will reformat the
-   ``Documentation/process/coding-style.rst`` in the Linux kernel repository.
+   coding style according to our standards defined in ``.clang-format``.
-   Note that the coding style isn't written in stone, if there is a good reason
-   to deviate from it, it should be fine.
 
-6. Download the files ``checkpatch.pl``, ``const_structs.checkpatch`` and
+6. Create a pull request against the branch ``master``.
-   ``spelling.txt`` from the folder ``scripts`` in the Linux kernel repository.
 
-7. To use ``checkpatch.pl`` you can use ``make checkpatch``, which will check
+7. Be prepared to get some comments about your code and to modify it. Tip: Use
-   the coding style of all patches between the current one and the upstream
-   code. By default, the Makefile expects the script (and associate files) to be
-   located in ``../linux/scripts/``, but you can place them anywhere you like as
-   long as you specify it when executing the command:
-   ``make checkpatch CHECKPATCH=../path/to/folder``.
-
-8. Create a pull request against the branch ``master``.
-
-9. Be prepared to get some comments about your code and to modify it. Tip: Use
     ``git rebase -i origin/master`` to modify chains of commits.

CONTRIBUTORS.rst

@@ -21,7 +21,7 @@ Main contributors
 
 - Eldred "ISSOtm" Habert <eldredhabert0@gmail.com>
 
-- Rangi <http://github.com/Rangi42>
+- Sylvie "Rangi" Oukaour <http://github.com/Rangi42>
 
 Other contributors
 ------------------

Dockerfile

@@ -1,24 +1,14 @@
-# This file is part of RGBDS.
+FROM debian:11-slim
-#
+LABEL org.opencontainers.image.source=https://github.com/gbdev/rgbds
-# Copyright (c) 2018-2019, Phil Smith and RGBDS contributors.
+ARG version=0.7.0
-#
-# SPDX-License-Identifier: MIT
-# docker build -t rgbds:vX.X.X-alpine
-FROM alpine:latest
-RUN apk add --update \
-      build-base \
-      bison \
-      libpng-dev
-COPY . /rgbds
 WORKDIR /rgbds
-RUN make Q='' all
 
-FROM alpine:latest
+COPY . .
-RUN apk add --update \
+
-      libpng
+RUN apt-get update && \
-COPY --from=0 \
+    apt-get install sudo make cmake gcc build-essential -y
-  /rgbds/rgbasm \
+
-  /rgbds/rgbfix \
+RUN ./.github/scripts/install_deps.sh ubuntu-20.04
-  /rgbds/rgblink \
+RUN make -j CXXFLAGS="-O3 -flto -DNDEBUG -static" PKG_CONFIG="pkg-config --static" Q=
-  /rgbds/rgbgfx \
+
-  /bin/
+RUN tar caf rgbds-${version}-linux-x86_64.tar.xz --transform='s#.*/##' rgbasm rgblink rgbfix rgbgfx man/* .github/scripts/install.sh

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 1997-2020, Carsten Sorensen and RGBDS contributors.
+Copyright (c) 1997-2023, Carsten Sørensen and RGBDS contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

Makefile

@@ -1,13 +1,9 @@
-#
-# This file is part of RGBDS.
-#
-# Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
-#
 # SPDX-License-Identifier: MIT
-#
 
 .SUFFIXES:
-.SUFFIXES: .h .y .c .cpp .o
+.SUFFIXES: .cpp .y .o
+
+.PHONY: all clean install checkdiff develop debug coverage mingw32 mingw64 wine-shim dist
 
 # User-defined variables
 
@@ -18,7 +14,6 @@ mandir		:= ${PREFIX}/share/man
 STRIP		:= -s
 BINMODE		:= 755
 MANMODE		:= 644
-CHECKPATCH	:= ../linux/scripts/checkpatch.pl
 
 # Other variables
 
@@ -27,19 +22,16 @@ PNGCFLAGS	:= `${PKG_CONFIG} --cflags libpng`
 PNGLDFLAGS	:= `${PKG_CONFIG} --libs-only-L libpng`
 PNGLDLIBS	:= `${PKG_CONFIG} --libs-only-l libpng`
 
-# Note: if this comes up empty, `version.c` will automatically fall back to last release number
+# Note: if this comes up empty, `version.cpp` will automatically fall back to last release number
 VERSION_STRING	:= `git describe --tags --dirty --always 2>/dev/null`
 
-WARNFLAGS	:= -Wall -pedantic
+# TODO: use -pedantic after non-C++ idioms are gone
+WARNFLAGS	:= -Wall -Wno-unknown-warning-option -Wno-c99-designator
 
-# Overridable CFLAGS
+# Overridable CXXFLAGS
-CFLAGS		?= -O3 -flto -DNDEBUG
 CXXFLAGS	?= -O3 -flto -DNDEBUG
-# Non-overridable CFLAGS
+# Non-overridable CXXFLAGS
-# _ISOC11_SOURCE is required on certain platforms to get C11 on top of the C99-based POSIX 2008
+REALCXXFLAGS	:= ${CXXFLAGS} ${WARNFLAGS} -std=c++2a -I include \
-REALCFLAGS	:= ${CFLAGS} ${WARNFLAGS} -std=gnu11 -I include \
-		   -D_POSIX_C_SOURCE=200809L -D_ISOC11_SOURCE
-REALCXXFLAGS	:= ${CXXFLAGS} ${WARNFLAGS} -std=c++17 -I include \
 		   -D_POSIX_C_SOURCE=200809L -fno-exceptions -fno-rtti
 # Overridable LDFLAGS
 LDFLAGS		?=
@@ -47,9 +39,9 @@ LDFLAGS		?=
 REALLDFLAGS	:= ${LDFLAGS} ${WARNFLAGS} \
 		   -DBUILD_VERSION_STRING=\"${VERSION_STRING}\"
 
-YFLAGS		?= -Wall
+# Wrapper around bison that passes flags depending on what the version supports
+BISON		:= src/bison.sh
 
-BISON		:= bison
 RM		:= rm -rf
 
 # Used for checking pull requests
@@ -73,16 +65,16 @@ rgbasm_obj := \
 	src/asm/rpn.o \
 	src/asm/section.o \
 	src/asm/symbol.o \
-	src/asm/util.o \
 	src/asm/warning.o \
 	src/extern/getopt.o \
 	src/extern/utf8decoder.o \
 	src/error.o \
 	src/hashmap.o \
 	src/linkdefs.o \
-	src/opmath.o
+	src/opmath.o \
+	src/util.o
 
-src/asm/lexer.o src/asm/main.o: src/asm/parser.h
+src/asm/lexer.o src/asm/main.o: src/asm/parser.hpp
 
 rgblink_obj := \
 	src/link/assign.o \
@@ -95,10 +87,14 @@ rgblink_obj := \
 	src/link/section.o \
 	src/link/symbol.o \
 	src/extern/getopt.o \
+	src/extern/utf8decoder.o \
 	src/error.o \
 	src/hashmap.o \
 	src/linkdefs.o \
-	src/opmath.o
+	src/opmath.o \
+	src/util.o
+
+src/link/main.o: src/link/script.hpp
 
 rgbfix_obj := \
 	src/fix/main.o \
@@ -118,19 +114,19 @@ rgbgfx_obj := \
 	src/error.o
 
 rgbasm: ${rgbasm_obj}
-	$Q${CC} ${REALLDFLAGS} -o $@ ${rgbasm_obj} ${REALCFLAGS} src/version.c -lm
+	$Q${CXX} ${REALLDFLAGS} -o $@ ${rgbasm_obj} ${REALCXXFLAGS} src/version.cpp -lm
 
 rgblink: ${rgblink_obj}
-	$Q${CC} ${REALLDFLAGS} -o $@ ${rgblink_obj} ${REALCFLAGS} src/version.c
+	$Q${CXX} ${REALLDFLAGS} -o $@ ${rgblink_obj} ${REALCXXFLAGS} src/version.cpp
 
 rgbfix: ${rgbfix_obj}
-	$Q${CC} ${REALLDFLAGS} -o $@ ${rgbfix_obj} ${REALCFLAGS} src/version.c
+	$Q${CXX} ${REALLDFLAGS} -o $@ ${rgbfix_obj} ${REALCXXFLAGS} src/version.cpp
 
 rgbgfx: ${rgbgfx_obj}
-	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ ${rgbgfx_obj} ${REALCXXFLAGS} -x c++ src/version.c ${PNGLDLIBS}
+	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ ${rgbgfx_obj} ${REALCXXFLAGS} ${PNGLDLIBS} src/version.cpp
 
-test/gfx/randtilegen: test/gfx/randtilegen.c
+test/gfx/randtilegen: test/gfx/randtilegen.cpp
-	$Q${CC} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ $^ ${REALCFLAGS} ${PNGCFLAGS} ${PNGLDLIBS}
+	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ $^ ${REALCXXFLAGS} ${PNGCFLAGS} ${PNGLDLIBS}
 
 test/gfx/rgbgfx_test: test/gfx/rgbgfx_test.cpp
 	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ $^ ${REALCXXFLAGS} ${PNGLDLIBS}
@@ -140,30 +136,35 @@ test/gfx/rgbgfx_test: test/gfx/rgbgfx_test.cpp
 # We want the Bison invocation to pass through our rules, not default ones
 .y.o:
 
-# Bison-generated C files have an accompanying header
+.y.cpp:
-src/asm/parser.h: src/asm/parser.c
+	$Q${BISON} $@ $<
+
+# Bison-generated C++ files have an accompanying header
+src/asm/parser.hpp: src/asm/parser.cpp
+	$Qtouch $@
+src/link/script.hpp: src/link/script.cpp
 	$Qtouch $@
 
-src/asm/parser.c: src/asm/parser.y
+# Only RGBGFX uses libpng (POSIX make doesn't support pattern rules to cover all these)
-	$QDEFS=; \
+src/gfx/main.o: src/gfx/main.cpp
-	add_flag(){ \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-		if src/check_bison_ver.sh $$1 $$2; then \
+src/gfx/pal_packing.o: src/gfx/pal_packing.cpp
-			DEFS="-D$$3 $$DEFS"; \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-		fi \
+src/gfx/pal_sorting.o: src/gfx/pal_sorting.cpp
-	}; \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-	add_flag 3 5 api.token.raw=true; \
+src/gfx/pal_spec.o: src/gfx/pal_spec.cpp
-	add_flag 3 6 parse.error=detailed; \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-	add_flag 3 0 parse.error=verbose; \
+src/gfx/process.o: src/gfx/process.cpp
-	add_flag 3 0 parse.lac=full; \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-	add_flag 3 0 lr.type=ielr; \
+src/gfx/proto_palette.o: src/gfx/proto_palette.cpp
-	echo "DEFS=$$DEFS"; \
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-	${BISON} $$DEFS -d ${YFLAGS} -o $@ $<
+src/gfx/reverse.o: src/gfx/reverse.cpp
-
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
-.c.o:
+src/gfx/rgba.o: src/gfx/rgba.cpp
-	$Q${CC} ${REALCFLAGS} -c -o $@ $<
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
 
 .cpp.o:
-	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
+	$Q${CXX} ${REALCXXFLAGS} -c -o $@ $<
 
 # Target used to remove all files generated by other Makefile targets
 
@@ -173,52 +174,20 @@ clean:
 	$Q${RM} rgbfix rgbfix.exe
 	$Q${RM} rgbgfx rgbgfx.exe
 	$Qfind src/ -name "*.o" -exec rm {} \;
+	$Qfind . -type f \( -name "*.gcno" -o -name "*.gcda" -o -name "*.gcov" \) -exec rm {} \;
 	$Q${RM} rgbshim.sh
-	$Q${RM} src/asm/parser.c src/asm/parser.h
+	$Q${RM} src/asm/parser.cpp src/asm/parser.hpp
+	$Q${RM} src/link/script.cpp src/link/script.hpp src/link/stack.hh
 	$Q${RM} test/gfx/randtilegen test/gfx/rgbgfx_test
 
 # Target used to install the binaries and man pages.
 
 install: all
-	$Qmkdir -p ${DESTDIR}${bindir}
+	$Qinstall -d ${DESTDIR}${bindir}/ ${DESTDIR}${mandir}/man1/ ${DESTDIR}${mandir}/man5/ ${DESTDIR}${mandir}/man7/
-	$Qinstall ${STRIP} -m ${BINMODE} rgbasm ${DESTDIR}${bindir}/rgbasm
+	$Qinstall ${STRIP} -m ${BINMODE} rgbasm rgblink rgbfix rgbgfx ${DESTDIR}${bindir}/
-	$Qinstall ${STRIP} -m ${BINMODE} rgbfix ${DESTDIR}${bindir}/rgbfix
+	$Qinstall -m ${MANMODE} man/rgbasm.1 man/rgblink.1 man/rgbfix.1 man/rgbgfx.1 ${DESTDIR}${mandir}/man1/
-	$Qinstall ${STRIP} -m ${BINMODE} rgblink ${DESTDIR}${bindir}/rgblink
+	$Qinstall -m ${MANMODE} man/rgbds.5 man/rgbasm.5 man/rgblink.5 ${DESTDIR}${mandir}/man5/
-	$Qinstall ${STRIP} -m ${BINMODE} rgbgfx ${DESTDIR}${bindir}/rgbgfx
+	$Qinstall -m ${MANMODE} man/rgbds.7 man/gbz80.7 ${DESTDIR}${mandir}/man7/
-	$Qmkdir -p ${DESTDIR}${mandir}/man1 ${DESTDIR}${mandir}/man5 ${DESTDIR}${mandir}/man7
-	$Qinstall -m ${MANMODE} man/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
-	$Qinstall -m ${MANMODE} man/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
-	$Qinstall -m ${MANMODE} man/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5
-	$Qinstall -m ${MANMODE} man/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
-	$Qinstall -m ${MANMODE} man/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5
-	$Qinstall -m ${MANMODE} man/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
-	$Qinstall -m ${MANMODE} man/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
-	$Qinstall -m ${MANMODE} man/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
-	$Qinstall -m ${MANMODE} man/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1
-
-# Target used to check the coding style of the whole codebase.
-# `extern/` is excluded, as it contains external code that should not be patched
-# to meet our coding style, so applying upstream patches is easier.
-# `.y` files aren't checked, unfortunately...
-
-checkcodebase:
-	$Qfor file in `git ls-files | grep -E '(\.c|\.h)$$' | grep -Ev '(src|include)/extern/'`; do	\
-		${CHECKPATCH} -f "$$file";					\
-	done
-
-# Target used to check the coding style of the patches from the upstream branch
-# to the HEAD. Runs checkpatch once for each commit between the current HEAD and
-# the first common commit between the HEAD and origin/master.
-# `.y` files aren't checked, unfortunately...
-
-checkpatch:
-	$QCOMMON_COMMIT=`git merge-base HEAD ${BASE_REF}`;		\
-	for commit in `git rev-list $$COMMON_COMMIT..HEAD`; do		\
-		echo "[*] Analyzing commit '$$commit'";			\
-		git format-patch --stdout "$$commit~..$$commit"		\
-			-- src include '!src/extern' '!include/extern'	\
-			| ${CHECKPATCH} - || true;			\
-	done
 
 # Target used to check for suspiciously missing changed files.
 
@@ -231,24 +200,35 @@ checkdiff:
 # The rationale for some of the flags is documented in the CMakeLists.
 
 develop:
-	$Qenv ${MAKE} WARNFLAGS="-Werror -Wextra \
+	$Q${MAKE} WARNFLAGS="${WARNFLAGS} -Werror -Wextra \
 		-Walloc-zero -Wcast-align -Wcast-qual -Wduplicated-branches -Wduplicated-cond \
 		-Wfloat-equal -Wlogical-op -Wnull-dereference -Wshift-overflow=2 \
 		-Wstringop-overflow=4 -Wstrict-overflow=5 -Wundef -Wuninitialized -Wunused \
 		-Wshadow \
 		-Wformat=2 -Wformat-overflow=2 -Wformat-truncation=1 \
-		-Wno-format-nonliteral \
+		-Wno-format-nonliteral -Wno-strict-overflow \
 		-Wno-type-limits -Wno-tautological-constant-out-of-range-compare \
 		-Wvla \
-		-Wno-unknown-warning-option \
+		-D_GLIBCXX_ASSERTIONS \
 		-fsanitize=shift -fsanitize=integer-divide-by-zero \
 		-fsanitize=unreachable -fsanitize=vla-bound \
 		-fsanitize=signed-integer-overflow -fsanitize=bounds \
 		-fsanitize=object-size -fsanitize=bool -fsanitize=enum \
 		-fsanitize=alignment -fsanitize=null -fsanitize=address" \
-		CFLAGS="-ggdb3 -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls" \
 		CXXFLAGS="-ggdb3 -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls"
 
+# This target is used during development in order to more easily debug with gdb.
+
+debug:
+	$Qenv ${MAKE} \
+		CXXFLAGS="-ggdb3 -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls"
+
+# This target is used during development in order to inspect code coverage with gcov.
+
+coverage:
+	$Qenv ${MAKE} \
+		CXXFLAGS="-ggdb3 -Og --coverage -fno-omit-frame-pointer -fno-optimize-sibling-calls"
+
 # Targets for the project maintainer to easily create Windows exes.
 # This is not for Windows users!
 # If you're building on Windows with Cygwin or Mingw, just follow the Unix
@@ -256,16 +236,17 @@ develop:
 
 mingw32:
 	$Q${MAKE} all test/gfx/randtilegen test/gfx/rgbgfx_test \
-		CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ \
+		CXX=i686-w64-mingw32-g++ \
-		BISON=bison PKG_CONFIG=i686-w64-mingw32-pkg-config -j
+		CXXFLAGS="-O3 -flto -DNDEBUG -static-libgcc" \
+		PKG_CONFIG="PKG_CONFIG_SYSROOT_DIR=/usr/i686-w64-mingw32 pkg-config"
 
 mingw64:
 	$Q${MAKE} all test/gfx/randtilegen test/gfx/rgbgfx_test \
-		CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ \
+		CXX=x86_64-w64-mingw32-g++ \
-		BISON=bison PKG_CONFIG=x86_64-w64-mingw32-pkg-config -j
+		PKG_CONFIG="PKG_CONFIG_SYSROOT_DIR=/usr/x86_64-w64-mingw32 pkg-config"
 
 wine-shim:
-	$Qecho '#!/bin/bash' > rgbshim.sh
+	$Qecho '#!/usr/bin/env bash' > rgbshim.sh
 	$Qecho 'WINEDEBUG=-all wine $$0.exe "$${@:1}"' >> rgbshim.sh
 	$Qchmod +x rgbshim.sh
 	$Qln -s rgbshim.sh rgbasm

README.rst

@@ -14,16 +14,20 @@ other UNIX tools.
 
 This toolchain is maintained `on GitHub <https://github.com/gbdev/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.
+The documentation of this toolchain can be viewed online `here <https://rgbds.gbdev.io/docs/>`__.
-The source code of the website itself is on GitHub as well under the repo `rgbds-www <https://github.com/gbdev/rgbds-www>`__.
+It is generated from the man pages found in this repository.
+The source code of the website itself is on GitHub as well under the repo
+`rgbds-www <https://github.com/gbdev/rgbds-www>`__.
 
-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``.
+If you want to contribute or maintain RGBDS, and have questions regarding the code, its
+organisation, etc. you can find the maintainers `on the gbdev community channels <https://gbdev.io/chat>`__
+or via mail at ``rgbds at gbdev dot io``.
 
 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/#building-from-source>`__
+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
@@ -40,13 +44,13 @@ is possible using ``make`` or ``cmake``; follow the link for more detailed instr
 2. RGBDS Folder Organization
 ----------------------------
 
-The RGBDS source code file structure somewhat resembles the following:
+The RGBDS source code file structure is as follows:
 
 ::
 
        .
        ├── .github/
-       │   ├── actions/
+       │   ├── scripts/
        │   │   └── ...
        │   └── workflows/
        │       └── ...
@@ -76,6 +80,7 @@ The RGBDS source code file structure somewhat resembles the following:
        │   └── run-tests.sh
        ├── .clang-format
        ├── CMakeLists.txt
+       ├── Dockerfile
        ├── Makefile
        └── README.rst
 
@@ -85,50 +90,75 @@ The RGBDS source code file structure somewhat resembles the following:
 - ``.github/`` - files and scripts related to the integration of the RGBDS codebase with
   GitHub.
 
-  * ``actions/`` - scripts used by workflow files.
+  * ``scripts/`` - scripts used by workflow files.
   * ``workflows/`` - CI workflow description files.
 
 - ``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.
+  * ``zsh_compl`` contains tab completion scripts for use with zsh. Put them somewhere in
+    your ``fpath``, and they should auto-load.
 
-  * ``bash_compl`` contains tab completion scripts for use with bash. Run them with ``source`` somewhere in your ``.bashrc``, and they should load every time you open a shell.
+  * ``bash_compl`` contains tab completion scripts for use with bash. Run them with ``source``
+    somewhere in your ``.bashrc``, and they should load every time you open a shell.
 
-- ``include/`` - header files for each respective C files in `src`.
+- ``include/`` - header files for the respective source files in `src`.
 
 - ``man/`` - manual pages.
 
 - ``src/`` - source code of 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.
+    (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.
+- ``test/`` - testing framework used to verify that changes to the code don't break or
+  modify the behavior of RGBDS.
 
-- ``.clang-format`` - code style for automated formatting with |clang-format|_. The C code does not currently follow this style, but all C++ code should.
+- ``.clang-format`` - code style for automated C++ formatting with |clang-format|_.
+
+- ``Dockerfile`` - defines how to build RGBDS with Docker.
 
 3. History
 ----------
 
-- Around 1997, Carsten Sørensen (AKA SurfSmurf) writes ASMotor as a
+- 1996-10-01: Carsten Sørensen (a.k.a. SurfSmurf) releases
-  general-purpose assembler/linker system for DOS/Win32
+  `xAsm <http://otakunozoku.com/RGBDSdocs/asm.htm>`__,
+  `xLink <http://otakunozoku.com/RGBDSdocs/link.htm>`__, and
+  `RGBFix <http://otakunozoku.com/RGBDSdocs/fix.htm>`__,
+  a Game Boy SM83 (GBZ80) assembler/linker system for DOS/Win32.
 
-- Around 1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and
+- 1997-07-03: Sørensen releases `ASMotor <http://otakunozoku.com/RGBDSdocs/geninfo.htm>`__,
-  produce GBZ80 assembly/machine code, and releases this version as RGBDS.
+  packaging the three programs together and moving towards making them a
+  general-purpose target-independent system.
 
-- 2009, Vegard Nossum adapts the code to be more UNIX-like and releases
+- 1999-08-01: Justin Lloyd (a.k.a. Otaku no Zoku) adapts ASMotor to re-focus
-  this version as rgbds-linux on
+  on SM83 assembly/machine code, and releases this version as
-  `GitHub <https://github.com/vegard/rgbds-linux>`__.
+  `RGBDS <http://otakunozoku.com/rednex-gameboy-development-system/>`__.
 
-- 2010, Anthony J. Bentley forks that repository. The fork becomes the reference
+- 2009-06-11: Vegard Nossum adapts the code to be more UNIX-like and releases
-  implementation of rgbds.
+  this version as `rgbds-linux <https://github.com/vegard/rgbds-linux>`__.
 
-- 2017, Bentley's repository is moved to a neutral name.
+- 2010-01-12: Anthony J. Bentley `forks <https://github.com/bentley>`__ Nossum's
+  repository. The fork becomes the reference implementation of RGBDS.
 
-- 2018, codebase relicensed under the MIT license.
+- 2015-01-18: stag019 begins implementing `rgbgfx <https://github.com/stag019/rgbgfx>`__,
+  a PNG‐to‐Game Boy graphics converter, for eventual integration into RGBDS.
 
-- 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.
+- 2016-09-05: rgbgfx is `integrated <https://github.com/gbdev/rgbds/commit/c3c31138ddbd8680d4e67957e387f2816798a71b>`__
+  into Bentley's repository.
+
+- 2017-02-23: Bentley's repository is moved to the `rednex <https://github.com/rednex>`__
+  organization.
+
+- 2018-01-26: The codebase is `relicensed <https://github.com/gbdev/rgbds/issues/128>`__
+  under the MIT license.
+
+- 2020-09-15: The repository is `moved <https://github.com/gbdev/rgbds/issues/567>`__
+  to the `gbdev <https://github.com/gbdev>`__ organization.
+
+- 2022-05-17: The `rgbds.gbdev.io <https://rgbds.gbdev.io>`__ website for RGBDS
+  documentation and downloads is published.
 
 4. Acknowledgements
 -------------------
@@ -137,3 +167,5 @@ RGBGFX generates palettes using algorithms found in the paper
 `"Algorithms for the Pagination Problem, a Bin Packing with Overlapping Items" <http://arxiv.org/abs/1605.00558>`__
 (`GitHub <https://github.com/pagination-problem/pagination>`__, MIT license),
 by Aristide Grange, Imed Kacem, and Sébastien Martin.
+
+RGBGFX's color palette was taken from `SameBoy <https://sameboy.github.io>`__, with permission and help by `LIJI <https://github.com/LIJI32>`__.

RELEASE.rst

@@ -4,16 +4,17 @@ Releasing
 This describes for the maintainers of RGBDS how to publish a new release on
 GitHub.
 
-1. Update, commit, and push `include/version.h <include/version.h>`__ with
+1. Update, commit, and push `include/version.hpp <include/version.hpp>`__ with
    values for ``PACKAGE_VERSION_MAJOR``, ``PACKAGE_VERSION_MINOR``,
-   ``PACKAGE_VERSION_PATCH``, and ``PACKAGE_VERSION_RC``. Only define
+   ``PACKAGE_VERSION_PATCH``, and ``PACKAGE_VERSION_RC``, as well as
+   `Dockerfile <Dockerfile>`__ with a value for ``ARG version``. Only define
    ``PACKAGE_VERSION_RC`` if you are publishing a release candidate! You can
    use ``git commit -m "Release <version>"`` and ``git push origin master``.
 
 2. Create a Git tag formatted as ``v<MAJOR>.<MINOR>.<PATCH>``, or
    ``v<MAJOR>.<MINOR>.<PATCH>-rc<RC>`` for a release candidate. ``MAJOR``,
    ``MINOR``, ``PATCH``, and ``RC`` should match their values from
-   `include/version.h <include/version.h>`__. You can use ``git tag <tag>``.
+   `include/version.hpp <include/version.hpp>`__. You can use ``git tag <tag>``.
 
 3. Push the tag to GitHub. You can use ``git push origin <tag>``.
 

contrib/bash_compl/_rgbasm.bash

@@ -35,13 +35,15 @@ _rgbasm_completions() {
 		[b]="binary-digits:unk"
 		[D]="define:unk"
 		[g]="gfx-chars:unk"
-		[i]="include:dir"
+		[I]="include:dir"
 		[M]="dependfile:glob-*.mk *.d"
 		[o]="output:glob-*.o"
+		[P]="preinclude:glob-*.asm *.inc"
 		[p]="pad-value:unk"
 		[Q]="q-precision:unk"
 		[r]="recursion-depth:unk"
 		[W]="warning:warning"
+		[X]="max-errors:unk"
 	)
 	# Parse command-line up to current word
 	local opt_ena=true

contrib/bash_compl/_rgbgfx.bash

@@ -10,11 +10,12 @@ _rgbgfx_completions() {
 		[V]="version:normal"
 		[C]="color-curve:normal"
 		[m]="mirror-tiles:normal"
+		[O]="group-outputs:normal"
 		[u]="unique-tiles:normal"
 		[v]="verbose:normal"
 		[Z]="columns:normal"
 		[a]="attr-map:glob-*.attrmap"
-		[A]="output-attr-map:normal"
+		[A]="auto-attr-map:normal"
 		[b]="base-tiles:unk"
 		[d]="depth:unk"
 		[L]="slice:unk"
@@ -22,13 +23,13 @@ _rgbgfx_completions() {
 		[n]="nb-palettes:unk"
 		[o]="output:glob-*.2bpp"
 		[p]="palette:glob-*.pal"
-		[P]="output-palette:normal"
+		[P]="auto-palette:normal"
 		[q]="palette-map:glob-*.palmap"
-		[Q]="output-palette-map:normal"
+		[Q]="auto-palette-map:normal"
 		[r]="reverse:unk"
 		[s]="palette-size:unk"
 		[t]="tilemap:glob-*.tilemap"
-		[T]="output-tilemap:normal"
+		[T]="auto-tilemap:normal"
 		[x]="trim-end:unk"
 	)
 	# Parse command-line up to current word

contrib/checkdiff.bash

@@ -1,26 +1,6 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 # SPDX-License-Identifier: MIT
-#
-# Copyright (c) 2021 Rangi
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
 
 declare -A FILES
 while read -r -d '' file; do
@@ -40,46 +20,49 @@ dependency () {
 # Pull requests that edit the first file without the second may be correct,
 # but are suspicious enough to require review.
 
-dependency include/linkdefs.h    man/rgbds.5 \
+dependency include/linkdefs.hpp    man/rgbds.5 \
            "Was the object file format changed?"
 
-dependency src/asm/parser.y      man/rgbasm.5 \
+dependency src/asm/parser.y        man/rgbasm.5 \
            "Was the rgbasm grammar changed?"
 
-dependency include/asm/warning.h man/rgbasm.1 \
+dependency src/link/script.y       man/rgblink.5 \
+           "Was the linker script grammar changed?"
+
+dependency include/asm/warning.hpp man/rgbasm.1 \
            "Were the rgbasm warnings changed?"
 
-dependency src/asm/object.c      include/linkdefs.h \
+dependency src/asm/object.cpp      include/linkdefs.hpp \
            "Should the object file revision be bumped?"
-dependency src/link/object.c     include/linkdefs.h \
+dependency src/link/object.cpp     include/linkdefs.hpp \
            "Should the object file revision be bumped?"
 
-dependency Makefile              CMakeLists.txt \
+dependency Makefile                CMakeLists.txt \
            "Did the build process change?"
-dependency Makefile              src/CMakeLists.txt \
+dependency Makefile                src/CMakeLists.txt \
            "Did the build process change?"
 
-dependency src/asm/main.c        man/rgbasm.1 \
+dependency src/asm/main.cpp        man/rgbasm.1 \
            "Did the rgbasm CLI change?"
-dependency src/asm/main.c        contrib/zsh_compl/_rgbasm \
+dependency src/asm/main.cpp        contrib/zsh_compl/_rgbasm \
            "Did the rgbasm CLI change?"
-dependency src/asm/main.c        contrib/bash_compl/_rgbasm.bash \
+dependency src/asm/main.cpp        contrib/bash_compl/_rgbasm.bash \
            "Did the rgbasm CLI change?"
-dependency src/link/main.c       man/rgblink.1 \
+dependency src/link/main.cpp       man/rgblink.1 \
            "Did the rgblink CLI change?"
-dependency src/link/main.c       contrib/zsh_compl/_rgblink \
+dependency src/link/main.cpp       contrib/zsh_compl/_rgblink \
            "Did the rgblink CLI change?"
-dependency src/link/main.c        contrib/bash_compl/_rgblink.bash \
+dependency src/link/main.cpp        contrib/bash_compl/_rgblink.bash \
            "Did the rgblink CLI change?"
-dependency src/fix/main.c        man/rgbfix.1 \
+dependency src/fix/main.cpp        man/rgbfix.1 \
            "Did the rgbfix CLI change?"
-dependency src/fix/main.c        contrib/zsh_compl/_rgbfix \
+dependency src/fix/main.cpp        contrib/zsh_compl/_rgbfix \
            "Did the rgbfix CLI change?"
-dependency src/fix/main.c        contrib/bash_compl/_rgbfix.bash \
+dependency src/fix/main.cpp        contrib/bash_compl/_rgbfix.bash \
            "Did the rgbfix CLI change?"
-dependency src/gfx/main.cpp      man/rgbgfx.1 \
+dependency src/gfx/main.cpp        man/rgbgfx.1 \
            "Did the rgbgfx CLI change?"
-dependency src/gfx/main.cpp      contrib/zsh_compl/_rgbgfx \
+dependency src/gfx/main.cpp        contrib/zsh_compl/_rgbgfx \
            "Did the rgbgfx CLI change?"
-dependency src/gfx/main.cpp      contrib/bash_compl/_rgbgfx.bash \
+dependency src/gfx/main.cpp        contrib/bash_compl/_rgbgfx.bash \
            "Did the rgbgfx CLI change?"

contrib/coverage.bash

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -e
+
+# Build RGBDS with gcov support
+make coverage -j
+
+# Run the tests
+for dir in asm link fix gfx; do
+	pushd test/$dir
+	./test.sh
+	popd
+done
+
+# Generate coverage logs
+gcov src/**/*.{c,cpp}
+mkdir -p coverage
+
+# Generate coverage report
+lcov -c --no-external -d . -o coverage/coverage.info
+genhtml -f -s -o coverage/ coverage/coverage.info
+
+# Open report in web browser
+if [ "$(uname)" == "Darwin" ]; then
+  open coverage/index.html
+else
+  xdg-open coverage/index.html
+fi

contrib/gbdiff.bash

@@ -1,26 +1,6 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 # SPDX-License-Identifier: MIT
-#
-# Copyright (c) 2020 Eldred Habert
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
 
 STATE=0
 diff <(xxd "$1") <(xxd "$2") | while read -r LINE; do
@@ -57,7 +37,7 @@ diff <(xxd "$1") <(xxd "$2") | while read -r LINE; do
 			 while read -r SYMADDR SYM; do
 				SYMADDR=$((0x${SYMADDR#*:}))
 				if [[ $SYMADDR -le $ADDR ]]; then
-					printf " (%s+%#x)\n" "$SYM" $((ADDR - SYMADDR))
+					printf " (%s+0x%x)\n" "$SYM" $((ADDR - SYMADDR))
 				fi
 			# TODO: assumes sorted sym files
 			done | tail -n 1

contrib/zsh_compl/_rgbasm

@@ -29,7 +29,7 @@ _rgbasm_warnings() {
 		'user:Warn when executing the WARN built-in'
 	)
 	# TODO: handle `no-` and `error=` somehow?
-	# TODO: handle `=0|1|2` levels for `numeric-string` and `truncation`?
+	# TODO: handle `=0|1|2` levels for `numeric-string`, `truncation`, and `unmapped-char`?
 	_describe warning warnings
 }
 
@@ -48,17 +48,19 @@ local args=(
 	'(-b --binary-digits)'{-b,--binary-digits}'+[Change chars for binary constants]:digit spec:'
 	'*'{-D,--define}'+[Define a string symbol]:name + value (default 1):'
 	'(-g --gfx-chars)'{-g,--gfx-chars}'+[Change chars for gfx constants]:chars spec:'
-	'(-i --include)'{-i,--include}'+[Add an include directory]:include path:_files -/'
+	'(-I --include)'{-I,--include}'+[Add an include directory]:include path:_files -/'
 	'(-M --dependfile)'{-M,--dependfile}"+[List deps in make format]:output file:_files -g '*.{d,mk}'"
 	-MG'[Assume missing files should be generated]'
 	-MP'[Add phony targets to all deps]'
 	'*'-MT"+[Add a target to the rules]:target:_files -g '*.{d,mk,o}'"
 	'*'-MQ"+[Add a target to the rules]:target:_files -g '*.{d,mk,o}'"
 	'(-o --output)'{-o,--output}'+[Output file]:output file:_files'
+	'(-P --preinclude)'{-P,--preinclude}"+[Pre-include a file]:include file:_files -g '*.{asm,inc}'"
 	'(-p --pad-value)'{-p,--pad-value}'+[Set padding byte]:padding byte:'
 	'(-Q --q-precision)'{-Q,--q-precision}'+[Set fixed-point precision]:precision:'
 	'(-r --recursion-depth)'{-r,--recursion-depth}'+[Set maximum recursion depth]:depth:'
 	'(-W --warning)'{-W,--warning}'+[Toggle warning flags]:warning flag:_rgbasm_warnings'
+	'(-X --max-errors)'{-X,--max-errors}'+[Set maximum errors before aborting]:maximum errors:'
 
 	":assembly sources:_files -g '*.asm'"
 )

contrib/zsh_compl/_rgbgfx

@@ -13,28 +13,29 @@ local args=(
 	# Arguments are listed here in the same order as in the manual, except for the version
 	'(- : * options)'{-V,--version}'[Print version number]'
 
-	'(-a --attr-map -A --output-attr-map)'{-A,--output-attr-map}'[Shortcut for -a <file>.attrmap]'
+	'(-a --attr-map -A --auto-attr-map)'{-A,--auto-attr-map}'[Shortcut for -a <file>.attrmap]'
 	'(-C --color-curve)'{-C,--color-curve}'[Generate palettes using GBC color curve]'
 	'(-m --mirror-tiles)'{-m,--mirror-tiles}'[Eliminate mirrored tiles from output]'
-	'(-p --palette -P --output-palette)'{-P,--output-palette}'[Shortcut for -p <file>.pal]'
+	'(-O --group-outputs)'{-O,--group-outputs}'[Base "shortcut" options on the output path, not input]'
-	'(-q --palette-map -Q --output-palette-map)'{-Q,--output-palette-map}'[Shortcut for -p <file>.palmap]'
+	'(-p --palette -P --auto-palette)'{-P,--auto-palette}'[Shortcut for -p <file>.pal]'
-	'(-t --tilemap -T --output-tilemap)'{-T,--output-tilemap}'[Shortcut for -t <file>.tilemap]'
+	'(-q --palette-map -Q --auto-palette-map)'{-Q,--auto-palette-map}'[Shortcut for -p <file>.palmap]'
+	'(-t --tilemap -T --auto-tilemap)'{-T,--auto-tilemap}'[Shortcut for -t <file>.tilemap]'
 	'(-u --unique-tiles)'{-u,--unique-tiles}'[Eliminate redundant tiles]'
 	{-v,--verbose}'[Enable verbose output]'
-	'(-h --horizontal -Z --columns)'{-Z,--columns}'[Read the image in column-major order]'
+	'(-Z --columns)'{-Z,--columns}'[Read the image in column-major order]'
 
-	'(-a --attr-map -A --output-attr-map)'{-a,--attr-map}'+[Generate a map of tile attributes (mirroring)]:attrmap file:_files'
+	'(-a --attr-map -A --auto-attr-map)'{-a,--attr-map}'+[Generate a map of tile attributes (mirroring)]:attrmap file:_files'
 	'(-b --base-tiles)'{-b,--base-tiles}'+[Base tile IDs for tile map output]:base tile IDs:'
 	'(-d --depth)'{-d,--depth}'+[Set bit depth]:bit depth:_depths'
 	'(-L --slice)'{-L,--slice}'+[Only process a portion of the image]:input slice:'
-	'(-N --nb-tiles)'{-n,--nb-tiles}'+[Limit number of tiles]:tile count:'
+	'(-N --nb-tiles)'{-N,--nb-tiles}'+[Limit number of tiles]:tile count:'
 	'(-n --nb-palettes)'{-n,--nb-palettes}'+[Limit number of palettes]:palette count:'
 	'(-o --output)'{-o,--output}'+[Set output file]:output file:_files'
-	'(-p --palette -P --output-palette)'{-p,--palette}"+[Output the image's palette in little-endian native RGB555 format]:palette file:_files"
+	'(-p --palette -P --auto-palette)'{-p,--palette}"+[Output the image's palette in little-endian native RGB555 format]:palette file:_files"
-	'(-q --palette-map -Q --output-palette-map)'{-p,--palette-map}"+[Output the image's palette map]:palette map file:_files"
+	'(-q --palette-map -Q --auto-palette-map)'{-q,--palette-map}"+[Output the image's palette map]:palette map file:_files"
 	'(-r --reverse)'{-r,--reverse}'+[Yield an image from binary data]:image width (in tiles):'
 	'(-s --palette-size)'{-s,--palette-size}'+[Limit palette size]:palette size:'
-	'(-t --tilemap -T --output-tilemap)'{-t,--tilemap}'+[Generate a map of tile indices]:tilemap file:_files'
+	'(-t --tilemap -T --auto-tilemap)'{-t,--tilemap}'+[Generate a map of tile indices]:tilemap file:_files'
 	'(-x --trim-end)'{-x,--trim-end}'+[Trim end of output by this many tiles]:tile count:'
 
 	":input png file:_files -g '*.png'"

include/asm/charmap.hpp

@@ -1,22 +1,19 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_ASM_CHARMAP_H
 #define RGBDS_ASM_CHARMAP_H
 
+#include <stdbool.h>
 #include <stdint.h>
 
+#define DEFAULT_CHARMAP_NAME "main"
+
 struct Charmap *charmap_New(char const *name, char const *baseName);
-void charmap_Delete(struct Charmap *charmap);
 void charmap_Set(char const *name);
 void charmap_Push(void);
 void charmap_Pop(void);
 void charmap_Add(char *mapping, uint8_t value);
+bool charmap_HasChar(char const *input);
 size_t charmap_Convert(char const *input, uint8_t *output);
 size_t charmap_ConvertNext(char const **input, uint8_t **output);
 

include/asm/fixpoint.h

@@ -1,34 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2021, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef RGBDS_ASM_FIXPOINT_H
-#define RGBDS_ASM_FIXPOINT_H
-
-#include <stdint.h>
-
-extern uint8_t fixPrecision;
-
-double fix_PrecisionFactor(void);
-void fix_Print(int32_t i);
-int32_t fix_Sin(int32_t i);
-int32_t fix_Cos(int32_t i);
-int32_t fix_Tan(int32_t i);
-int32_t fix_ASin(int32_t i);
-int32_t fix_ACos(int32_t i);
-int32_t fix_ATan(int32_t i);
-int32_t fix_ATan2(int32_t i, int32_t j);
-int32_t fix_Mul(int32_t i, int32_t j);
-int32_t fix_Mod(int32_t i, int32_t j);
-int32_t fix_Div(int32_t i, int32_t j);
-int32_t fix_Pow(int32_t i, int32_t j);
-int32_t fix_Log(int32_t i, int32_t j);
-int32_t fix_Round(int32_t i);
-int32_t fix_Ceil(int32_t i);
-int32_t fix_Floor(int32_t i);
-
-#endif // RGBDS_ASM_FIXPOINT_H

include/asm/fixpoint.hpp

@@ -0,0 +1,28 @@
+/* SPDX-License-Identifier: MIT */
+
+#ifndef RGBDS_ASM_FIXPOINT_H
+#define RGBDS_ASM_FIXPOINT_H
+
+#include <stdint.h>
+
+extern uint8_t fixPrecision;
+
+uint8_t fix_Precision(void);
+double fix_PrecisionFactor(void);
+int32_t fix_Sin(int32_t i, int32_t q);
+int32_t fix_Cos(int32_t i, int32_t q);
+int32_t fix_Tan(int32_t i, int32_t q);
+int32_t fix_ASin(int32_t i, int32_t q);
+int32_t fix_ACos(int32_t i, int32_t q);
+int32_t fix_ATan(int32_t i, int32_t q);
+int32_t fix_ATan2(int32_t i, int32_t j, int32_t q);
+int32_t fix_Mul(int32_t i, int32_t j, int32_t q);
+int32_t fix_Mod(int32_t i, int32_t j, int32_t q);
+int32_t fix_Div(int32_t i, int32_t j, int32_t q);
+int32_t fix_Pow(int32_t i, int32_t j, int32_t q);
+int32_t fix_Log(int32_t i, int32_t j, int32_t q);
+int32_t fix_Round(int32_t i, int32_t q);
+int32_t fix_Ceil(int32_t i, int32_t q);
+int32_t fix_Floor(int32_t i, int32_t q);
+
+#endif // RGBDS_ASM_FIXPOINT_H

include/asm/format.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020, RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_FORMAT_SPEC_H
 #define RGBDS_FORMAT_SPEC_H

include/asm/fstack.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Contains some assembler-wide defines and externs
 
@@ -15,8 +9,9 @@
 #include <stdint.h>
 #include <stdio.h>
 
-#include "asm/lexer.h"
+#include "asm/lexer.hpp"
 
+#include "linkdefs.hpp"
 
 struct FileStackNode {
 	struct FileStackNode *parent; // Pointer to parent node, for error reporting
@@ -27,11 +22,7 @@ struct FileStackNode {
 	bool referenced; // If referenced, don't free!
 	uint32_t ID; // Set only if referenced: ID within the object file, -1 if not output yet
 
-	enum {
+	enum FileStackNodeType type;
-		NODE_REPT,
-		NODE_FILE,
-		NODE_MACRO,
-	} type;
 };
 
 struct FileStackReptNode { // NODE_REPT
@@ -58,6 +49,7 @@ struct FileStackNode *fstk_GetFileStack(void);
 char const *fstk_GetFileName(void);
 
 void fstk_AddIncludePath(char const *s);
+void fstk_SetPreIncludeFile(char const *s);
 /*
  * @param path The user-provided file name
  * @param fullPath The address of a pointer, which will be made to point at the full path

include/asm/lexer.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_ASM_LEXER_H
 #define RGBDS_ASM_LEXER_H
@@ -90,6 +84,11 @@ int yylex(void);
 bool lexer_CaptureRept(struct CaptureBody *capture);
 bool lexer_CaptureMacroBody(struct CaptureBody *capture);
 
+struct AlignmentSpec {
+	uint8_t alignment;
+	uint16_t alignOfs;
+};
+
 #define INITIAL_DS_ARG_SIZE 2
 struct DsArgList {
 	size_t nbArgs;
@@ -97,4 +96,11 @@ struct DsArgList {
 	struct Expression *args;
 };
 
+#define INITIAL_PURGE_ARG_SIZE 2
+struct PurgeArgList {
+	size_t nbArgs;
+	size_t capacity;
+	char **args;
+};
+
 #endif // RGBDS_ASM_LEXER_H

include/asm/macro.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_MACRO_H
 #define RGBDS_MACRO_H
@@ -13,9 +7,9 @@
 #include <stdbool.h>
 #include <stdlib.h>
 
-#include "asm/warning.h"
+#include "asm/warning.hpp"
 
-#include "helpers.h"
+#include "helpers.hpp"
 
 struct MacroArgs;
 

include/asm/main.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2021, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_MAIN_H
 #define RGBDS_MAIN_H
@@ -13,9 +7,9 @@
 #include <stdint.h>
 #include <stdio.h>
 
-#include "helpers.h"
+#include "helpers.hpp"
 
-extern bool haltnop;
+extern bool haltNop;
 extern bool warnOnHaltNop;
 extern bool optimizeLoads;
 extern bool warnOnLdOpt;

include/asm/opt.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2021, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_OPT_H
 #define RGBDS_OPT_H
@@ -17,8 +11,8 @@ void opt_G(char const chars[4]);
 void opt_P(uint8_t padByte);
 void opt_Q(uint8_t precision);
 void opt_L(bool optimize);
-void opt_W(char const *flag);
+void opt_W(char *flag);
-void opt_Parse(char const *option);
+void opt_Parse(char *option);
 
 void opt_Push(void);
 void opt_Pop(void);

include/asm/output.hpp

@@ -1,17 +1,11 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_ASM_OUTPUT_H
 #define RGBDS_ASM_OUTPUT_H
 
 #include <stdint.h>
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
 
 struct Expression;
 struct FileStackNode;

include/asm/rpn.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_ASM_RPN_H
 #define RGBDS_ASM_RPN_H
@@ -12,7 +6,7 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
 
 #define MAXRPNLEN 1048576
 
@@ -50,13 +44,15 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 void rpn_HIGH(struct Expression *expr, const struct Expression *src);
 void rpn_LOW(struct Expression *expr, const struct Expression *src);
 void rpn_ISCONST(struct Expression *expr, const struct Expression *src);
-void rpn_UNNEG(struct Expression *expr, const struct Expression *src);
+void rpn_NEG(struct Expression *expr, const struct Expression *src);
-void rpn_UNNOT(struct Expression *expr, const struct Expression *src);
+void rpn_NOT(struct Expression *expr, const struct Expression *src);
 void rpn_BankSymbol(struct Expression *expr, char const *symName);
 void rpn_BankSection(struct Expression *expr, char const *sectionName);
 void rpn_BankSelf(struct Expression *expr);
 void rpn_SizeOfSection(struct Expression *expr, char const *sectionName);
 void rpn_StartOfSection(struct Expression *expr, char const *sectionName);
+void rpn_SizeOfSectionType(struct Expression *expr, enum SectionType type);
+void rpn_StartOfSectionType(struct Expression *expr, enum SectionType type);
 void rpn_Free(struct Expression *expr);
 void rpn_CheckHRAM(struct Expression *expr, const struct Expression *src);
 void rpn_CheckRST(struct Expression *expr, const struct Expression *src);

include/asm/section.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_SECTION_H
 #define RGBDS_SECTION_H
@@ -12,8 +6,8 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
-#include "platform.h" // NONNULL
+#include "platform.hpp" // NONNULL
 
 extern uint8_t fillByte;
 
@@ -44,15 +38,16 @@ struct SectionSpec {
 extern struct Section *currentSection;
 
 struct Section *sect_FindSectionByName(char const *name);
-void sect_NewSection(char const *name, uint32_t secttype, uint32_t org,
+void sect_NewSection(char const *name, enum SectionType type, uint32_t org,
 		     struct SectionSpec const *attributes, enum SectionModifier mod);
-void sect_SetLoadSection(char const *name, uint32_t secttype, uint32_t org,
+void sect_SetLoadSection(char const *name, enum SectionType type, uint32_t org,
 			 struct SectionSpec const *attributes, enum SectionModifier mod);
 void sect_EndLoadSection(void);
 
 struct Section *sect_GetSymbolSection(void);
 uint32_t sect_GetSymbolOffset(void);
 uint32_t sect_GetOutputOffset(void);
+uint32_t sect_GetAlignBytes(uint8_t alignment, uint16_t offset);
 void sect_AlignPC(uint8_t alignment, uint16_t offset);
 
 void sect_StartUnion(void);
@@ -65,7 +60,6 @@ void sect_AbsByteGroup(uint8_t const *s, size_t length);
 void sect_AbsWordGroup(uint8_t const *s, size_t length);
 void sect_AbsLongGroup(uint8_t const *s, size_t length);
 void sect_Skip(uint32_t skip, bool ds);
-void sect_String(char const *s);
 void sect_RelByte(struct Expression *expr, uint32_t pcShift);
 void sect_RelBytes(uint32_t n, struct Expression *exprs, size_t size);
 void sect_RelWord(struct Expression *expr, uint32_t pcShift);
@@ -74,6 +68,7 @@ void sect_PCRelByte(struct Expression *expr, uint32_t pcShift);
 void sect_BinaryFile(char const *s, int32_t startPos);
 void sect_BinaryFileSlice(char const *s, int32_t start_pos, int32_t length);
 
+void sect_EndSection(void);
 void sect_PushSection(void);
 void sect_PopSection(void);
 

include/asm/symbol.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2020, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_SYMBOL_H
 #define RGBDS_SYMBOL_H
@@ -14,9 +8,9 @@
 #include <string.h>
 #include <time.h>
 
-#include "asm/section.h"
+#include "asm/section.hpp"
 
-#include "platform.h" // MIN_NB_ELMS
+#include "platform.hpp" // MIN_NB_ELMS
 
 #define MAXSYMLEN	255
 
@@ -123,10 +117,10 @@ uint32_t sym_GetConstantSymValue(struct Symbol const *sym);
 uint32_t sym_GetConstantValue(char const *symName);
 // Find a symbol by exact name, bypassing expansion checks
 struct Symbol *sym_FindExactSymbol(char const *symName);
-// Find a symbol by exact name; may not be scoped, produces an error if it is
-struct Symbol *sym_FindUnscopedSymbol(char const *symName);
 // Find a symbol, possibly scoped, by name
 struct Symbol *sym_FindScopedSymbol(char const *symName);
+// Find a scoped symbol by name; do not return `@` or `_NARG` when they have no value
+struct Symbol *sym_FindScopedValidSymbol(char const *symName);
 struct Symbol const *sym_GetPC(void);
 struct Symbol *sym_AddMacro(char const *symName, int32_t defLineNo, char *body, size_t size);
 struct Symbol *sym_Ref(char const *symName);

include/asm/warning.hpp

@@ -1,17 +1,11 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2019, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef WARNING_H
 #define WARNING_H
 
-#include "helpers.h"
+#include "helpers.hpp"
 
-extern unsigned int nbErrors;
+extern unsigned int nbErrors, maxErrors;
 
 enum WarningState {
 	WARNING_DEFAULT,
@@ -36,7 +30,6 @@ enum WarningID {
 	WARNING_OBSOLETE,	      // Obsolete things
 	WARNING_SHIFT,		      // Shifting undefined behavior
 	WARNING_SHIFT_AMOUNT,	      // Strange shift amount
-	WARNING_UNMAPPED_CHAR,	      // Character without charmap entry
 	WARNING_USER,		      // User warnings
 
 	NB_PLAIN_WARNINGS,
@@ -49,6 +42,9 @@ enum WarningID {
 	// Implicit truncation loses some bits
 	WARNING_TRUNCATION_1,
 	WARNING_TRUNCATION_2,
+	// Character without charmap entry
+	WARNING_UNMAPPED_CHAR_1,
+	WARNING_UNMAPPED_CHAR_2,
 
 	NB_PLAIN_AND_PARAM_WARNINGS,
 #define NB_PARAM_WARNINGS (NB_PLAIN_AND_PARAM_WARNINGS - PARAM_WARNINGS_START)
@@ -81,7 +77,7 @@ void warning(enum WarningID id, char const *fmt, ...) format_(printf, 2, 3);
  * It is also used when the assembler goes into an invalid state (for example,
  * when it fails to allocate memory).
  */
-_Noreturn void fatalerror(char const *fmt, ...) format_(printf, 1, 2);
+[[noreturn]] void fatalerror(char const *fmt, ...) format_(printf, 1, 2);
 
 /*
  * Used for errors that make it impossible to assemble correctly, but don't

include/error.h

@@ -1,29 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2021, RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef RGBDS_ERROR_H
-#define RGBDS_ERROR_H
-
-#include "helpers.h"
-#include "platform.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-void warn(char const NONNULL(fmt), ...) format_(printf, 1, 2);
-void warnx(char const NONNULL(fmt), ...) format_(printf, 1, 2);
-
-_Noreturn void err(char const NONNULL(fmt), ...) format_(printf, 1, 2);
-_Noreturn void errx(char const NONNULL(fmt), ...) format_(printf, 1, 2);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif // RGBDS_ERROR_H

include/error.hpp

@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: MIT */
+
+#ifndef RGBDS_ERROR_H
+#define RGBDS_ERROR_H
+
+#include "helpers.hpp"
+#include "platform.hpp"
+
+extern "C" {
+
+void warn(char const NONNULL(fmt), ...) format_(printf, 1, 2);
+void warnx(char const NONNULL(fmt), ...) format_(printf, 1, 2);
+
+[[noreturn]] void err(char const NONNULL(fmt), ...) format_(printf, 1, 2);
+[[noreturn]] void errx(char const NONNULL(fmt), ...) format_(printf, 1, 2);
+
+}
+
+#endif // RGBDS_ERROR_H

include/extern/getopt.h

@@ -1,54 +0,0 @@
-/*
- * Copyright © 2005-2020 Rich Felker, et al.
- *
- * Permission is hereby granted, free of charge, to any person obtaining
- * a copy of this software and associated documentation files (the
- * "Software"), to deal in the Software without restriction, including
- * without limitation the rights to use, copy, modify, merge, publish,
- * distribute, sublicense, and/or sell copies of the Software, and to
- * permit persons to whom the Software is furnished to do so, subject to
- * the following conditions:
- *
- * The above copyright notice and this permission notice shall be
- * included in all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
- * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
- * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
- * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- */
-
-/* This implementation was taken from musl and modified for RGBDS */
-
-#ifndef RGBDS_EXTERN_GETOPT_H
-#define RGBDS_EXTERN_GETOPT_H
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern char *musl_optarg;
-extern int musl_optind, musl_opterr, musl_optopt, musl_optreset;
-
-struct option {
-	char const *name;
-	int has_arg;
-	int *flag;
-	int val;
-};
-
-int musl_getopt_long_only(int argc, char **argv, char const *optstring,
-			  const struct option *longopts, int *idx);
-
-#define no_argument        0
-#define required_argument  1
-#define optional_argument  2
-
-#ifdef __cplusplus
-} // extern "C"
-#endif
-
-#endif

include/extern/getopt.hpp

@@ -0,0 +1,29 @@
+/* SPDX-License-Identifier: MIT */
+
+/* This implementation was taken from musl and modified for RGBDS */
+
+#ifndef RGBDS_EXTERN_GETOPT_H
+#define RGBDS_EXTERN_GETOPT_H
+
+extern "C" {
+
+extern char *musl_optarg;
+extern int musl_optind, musl_opterr, musl_optopt, musl_optreset;
+
+struct option {
+	char const *name;
+	int has_arg;
+	int *flag;
+	int val;
+};
+
+int musl_getopt_long_only(int argc, char **argv, char const *optstring,
+			  const struct option *longopts, int *idx);
+
+#define no_argument        0
+#define required_argument  1
+#define optional_argument  2
+
+} // extern "C"
+
+#endif

include/extern/utf8decoder.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2018, Antonio Nino Diaz and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef EXTERN_UTF8DECODER_H
 #define EXTERN_UTF8DECODER_H

include/file.hpp

@@ -0,0 +1,98 @@
+/* SPDX-License-Identifier: MIT */
+
+#ifndef RGBDS_FILE_HPP
+#define RGBDS_FILE_HPP
+
+#include <array>
+#include <assert.h>
+#include <cassert>
+#include <fcntl.h>
+#include <fstream>
+#include <ios>
+#include <iostream>
+#include <streambuf>
+#include <string>
+#include <string.h>
+#include <string_view>
+#include <variant>
+
+#include "helpers.hpp"
+#include "platform.hpp"
+
+#include "gfx/main.hpp"
+
+// Convenience feature for visiting the below.
+template<typename... Ts>
+struct Visitor : Ts... {
+	using Ts::operator()...;
+};
+template<typename... Ts>
+Visitor(Ts...) -> Visitor<Ts...>;
+
+class File {
+	// Construct a `std::streambuf *` by default, since it's probably lighter than a `filebuf`.
+	std::variant<std::streambuf *, std::filebuf> _file;
+
+public:
+	File() {}
+	~File() { close(); }
+
+	/**
+	 * This should only be called once, and before doing any `->` operations.
+	 * Returns `nullptr` on error, and a non-null pointer otherwise.
+	 */
+	File *open(std::string const &path, std::ios_base::openmode mode) {
+		if (path != "-") {
+			return _file.emplace<std::filebuf>().open(path, mode) ? this : nullptr;
+		} else if (mode & std::ios_base::in) {
+			assert(!(mode & std::ios_base::out));
+			_file.emplace<std::streambuf *>(std::cin.rdbuf());
+			if (setmode(STDIN_FILENO, mode & std::ios_base::binary ? O_BINARY : O_TEXT) == -1) {
+				fatal("Failed to set stdin to %s mode: %s",
+				      mode & std::ios_base::binary ? "binary" : "text", strerror(errno));
+			}
+		} else {
+			assert(mode & std::ios_base::out);
+			_file.emplace<std::streambuf *>(std::cout.rdbuf());
+		}
+		return this;
+	}
+	std::streambuf &operator*() {
+		return std::visit(Visitor{[](std::filebuf &file) -> std::streambuf & { return file; },
+		                          [](std::streambuf *buf) -> std::streambuf & { return *buf; }},
+		                  _file);
+	}
+	std::streambuf const &operator*() const {
+		// The non-`const` version does not perform any modifications, so it's okay.
+		return **const_cast<File *>(this);
+	}
+	std::streambuf *operator->() { return &**this; }
+	std::streambuf const *operator->() const {
+		// See the `operator*` equivalent.
+		return const_cast<File *>(this)->operator->();
+	}
+
+	File *close() {
+		return std::visit(Visitor{[this](std::filebuf &file) {
+			                          // This is called by the destructor, and an explicit `close`
+			                          // shouldn't close twice.
+			                          _file.emplace<std::streambuf *>(nullptr);
+			                          return file.close() != nullptr;
+		                          },
+		                          [](std::streambuf *buf) { return buf != nullptr; }},
+		                  _file)
+		           ? this
+		           : nullptr;
+	}
+
+	char const *c_str(std::string const &path) const {
+		return std::visit(Visitor{[&path](std::filebuf const &) { return path.c_str(); },
+		                          [](std::streambuf const *buf) {
+			                          return buf == std::cin.rdbuf()
+			                                 ? "<stdin>" : "<stdout>";
+		                          }},
+		                  _file);
+	}
+};
+
+#endif // RGBDS_FILE_HPP

include/gfx/main.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_MAIN_HPP
 #define RGBDS_GFX_MAIN_HPP
@@ -16,7 +10,7 @@
 #include <utility>
 #include <vector>
 
-#include "helpers.h"
+#include "helpers.hpp"
 
 #include "gfx/rgba.hpp"
 
@@ -116,7 +110,8 @@ static constexpr auto flipTable(std::integer_sequence<T, i...>) {
 		return byte;
 	}(i)...};
 }
-}
+} // namespace detail
+
 // Flipping tends to happen fairly often, so take a bite out of dcache to speed it up
 static constexpr auto flipTable = detail::flipTable(std::make_integer_sequence<uint16_t, 256>());
 

include/gfx/pal_packing.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_PAL_PACKING_HPP
 #define RGBDS_GFX_PAL_PACKING_HPP
@@ -27,6 +21,6 @@ namespace packing {
 std::tuple<DefaultInitVec<size_t>, size_t>
     overloadAndRemove(std::vector<ProtoPalette> const &protoPalettes);
 
-}
+} // namespace packing
 
 #endif // RGBDS_GFX_PAL_PACKING_HPP

include/gfx/pal_sorting.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_PAL_SORTING_HPP
 #define RGBDS_GFX_PAL_SORTING_HPP
@@ -22,11 +16,11 @@ struct Palette;
 namespace sorting {
 
 void indexed(std::vector<Palette> &palettes, int palSize, png_color const *palRGB,
-             png_byte *palAlpha);
+             int palAlphaSize, png_byte *palAlpha);
 void grayscale(std::vector<Palette> &palettes,
                std::array<std::optional<Rgba>, 0x8001> const &colors);
 void rgb(std::vector<Palette> &palettes);
 
-}
+} // namespace sorting
 
 #endif // RGBDS_GFX_PAL_SORTING_HPP

include/gfx/pal_spec.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_PAL_SPEC_HPP
 #define RGBDS_GFX_PAL_SPEC_HPP

include/gfx/process.hpp

@@ -1,14 +1,9 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_CONVERT_HPP
 #define RGBDS_GFX_CONVERT_HPP
 
+void processPalettes();
 void process();
 
 #endif // RGBDS_GFX_CONVERT_HPP

include/gfx/proto_palette.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_PROTO_PALETTE_HPP
 #define RGBDS_GFX_PROTO_PALETTE_HPP
@@ -15,15 +9,20 @@
 #include <stdint.h>
 
 class ProtoPalette {
+public:
+	static constexpr size_t capacity = 4;
+
+private:
 	// Up to 4 colors, sorted, and where SIZE_MAX means the slot is empty
 	// (OK because it's not a valid color index)
 	// Sorting is done on the raw numerical values to lessen `compare`'s complexity
-	std::array<uint16_t, 4> _colorIndices{UINT16_MAX, UINT16_MAX, UINT16_MAX, UINT16_MAX};
+	std::array<uint16_t, capacity> _colorIndices{UINT16_MAX, UINT16_MAX, UINT16_MAX, UINT16_MAX};
 
 public:
 	/*
-	 * Adds the specified color to the set
+	 * Adds the specified color to the set, or **silently drops it** if the set is full.
-	 * Returns false if the set is full
+	 *
+	 * Returns whether the color was unique.
 	 */
 	bool add(uint16_t color);
 

include/gfx/reverse.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_REVERSE_HPP
 #define RGBDS_GFX_REVERSE_HPP

include/gfx/rgba.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_GFX_RGBA_HPP
 #define RGBDS_GFX_RGBA_HPP
@@ -43,6 +37,7 @@ struct Rgba {
 		auto shl = [](uint8_t val, unsigned shift) { return static_cast<uint32_t>(val) << shift; };
 		return shl(red, 24) | shl(green, 16) | shl(blue, 8) | shl(alpha, 0);
 	}
+	friend bool operator==(Rgba const &lhs, Rgba const &rhs) { return lhs.toCSS() == rhs.toCSS(); }
 	friend bool operator!=(Rgba const &lhs, Rgba const &rhs) { return lhs.toCSS() != rhs.toCSS(); }
 
 	/*

include/hashmap.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Generic hashmap implementation (C++ templates are calling...)
 #ifndef RGBDS_LINK_HASHMAP_H

include/helpers.hpp

@@ -1,19 +1,8 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2014-2020, RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef HELPERS_H
 #define HELPERS_H
 
-// Of course, MSVC does not support C11, so no _Noreturn there...
-#ifdef _MSC_VER
-	#define _Noreturn __declspec(noreturn)
-#endif
-
 // Ideally, we'd use `__has_attribute` and `__has_builtin`, but these were only introduced in GCC 9
 #ifdef __GNUC__ // GCC or compatible
 	#define format_(archetype, str_index, first_arg) \
@@ -30,8 +19,8 @@
 	#define format_(archetype, str_index, first_arg)
 	#define attr_(...)
 	// This seems to generate similar code to __builtin_unreachable, despite different semantics
-	// Note that executing this is undefined behavior (declared _Noreturn, but does return)
+	// Note that executing this is undefined behavior (declared [[noreturn]], but does return)
-	static inline _Noreturn void unreachable_(void) {}
+	[[noreturn]] static inline void unreachable_(void) {}
 #endif
 
 // Use builtins whenever possible, and shim them otherwise
@@ -93,4 +82,7 @@
 // (Having two instances of `arr` is OK because the contents of `sizeof` are not evaluated.)
 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof *(arr))
 
+// For lack of <ranges>, this adds some more brevity
+#define RANGE(s) std::begin(s), std::end(s)
+
 #endif // HELPERS_H

include/itertools.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_ITERTOOLS_HPP
 #define RGBDS_ITERTOOLS_HPP
@@ -12,11 +6,49 @@
 #include <tuple>
 #include <utility>
 
+#include "platform.hpp" // __PRETTY_FUNCTION__
+
 template<typename... Ts>
 static inline void report() {
 	puts(__PRETTY_FUNCTION__);
 }
 
+template<typename T>
+class EnumSeqIterator {
+	T _value;
+
+public:
+	explicit EnumSeqIterator(T value) : _value(value) {}
+
+	EnumSeqIterator &operator++() {
+		_value = (T)(_value + 1);
+		return *this;
+	}
+
+	auto operator*() const { return _value; }
+
+	friend auto operator==(EnumSeqIterator const &lhs, EnumSeqIterator const &rhs) {
+		return lhs._value == rhs._value;
+	}
+
+	friend auto operator!=(EnumSeqIterator const &lhs, EnumSeqIterator const &rhs) {
+		return lhs._value != rhs._value;
+	}
+};
+
+template<typename T>
+class EnumSeq {
+	T _start;
+	T _stop;
+
+public:
+	explicit EnumSeq(T stop) : _start((T)0), _stop(stop) {}
+	explicit EnumSeq(T start, T stop) : _start(start), _stop(stop) {}
+
+	EnumSeqIterator<T> begin() { return EnumSeqIterator(_start); }
+	EnumSeqIterator<T> end() { return EnumSeqIterator(_stop); }
+};
+
 // This is not a fully generic implementation; its current use cases only require for-loop behavior.
 // We also assume that all iterators have the same length.
 template<typename... Iters>
@@ -77,7 +109,7 @@ public:
 template<typename T>
 using Holder = std::conditional_t<std::is_lvalue_reference_v<T>, T,
                                   std::remove_cv_t<std::remove_reference_t<T>>>;
-}
+} // namespace detail
 
 // Does the same number of iterations as the first container's iterator!
 template<typename... Containers>

include/link/assign.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Assigning all sections a place
 #ifndef RGBDS_LINK_ASSIGN_H

include/link/main.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Declarations that all modules use, as well as `main` and related
 #ifndef RGBDS_LINK_MAIN_H
@@ -14,7 +8,8 @@
 #include <stdbool.h>
 #include <stdio.h>
 
-#include "helpers.h"
+#include "helpers.hpp"
+#include "linkdefs.hpp"
 
 // Variables related to CLI options
 extern bool isDmgMode;
@@ -38,11 +33,7 @@ struct FileStackNode {
 	// Line at which the parent context was exited; meaningless for the root level
 	uint32_t lineNo;
 
-	enum {
+	enum FileStackNodeType type;
-		NODE_REPT,
-		NODE_FILE,
-		NODE_MACRO,
-	} type;
 	union {
 		char *name; // NODE_FILE, NODE_MACRO
 		struct { // NODE_REPT
@@ -70,7 +61,7 @@ void warning(struct FileStackNode const *where, uint32_t lineNo,
 void error(struct FileStackNode const *where, uint32_t lineNo,
 	   char const *fmt, ...) format_(printf, 3, 4);
 
-_Noreturn void fatal(struct FileStackNode const *where, uint32_t lineNo,
+[[noreturn]] void fatal(struct FileStackNode const *where, uint32_t lineNo,
 		     char const *fmt, ...) format_(printf, 3, 4);
 
 /*

include/link/object.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Declarations related to processing of object (.o) files
 

include/link/output.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Outputting the result of linking
 #ifndef RGBDS_LINK_OUTPUT_H
@@ -12,7 +6,7 @@
 
 #include <stdint.h>
 
-#include "link/section.h"
+#include "link/section.hpp"
 
 /*
  * Registers a section for output.

include/link/patch.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Applying patches to SECTIONs
 #ifndef RGBDS_LINK_PATCH_H
@@ -13,9 +7,9 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-#include "link/section.h"
+#include "link/section.hpp"
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
 
 struct Assertion {
 	struct Patch patch;

include/link/script.h

@@ -1,38 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-// Parsing a linker script
-#ifndef RGBDS_LINK_SCRIPT_H
-#define RGBDS_LINK_SCRIPT_H
-
-#include <stdint.h>
-#include "linkdefs.h"
-
-extern FILE * linkerScript;
-
-struct SectionPlacement {
-	struct Section *section;
-        enum SectionType type;
-	uint16_t org;
-	uint32_t bank;
-};
-
-extern uint64_t script_lineNo;
-
-/*
- * Parses the linker script to return the next section constraint
- * @return A pointer to a struct, or NULL on EOF. The pointer shouldn't be freed
- */
-struct SectionPlacement *script_NextSection(void);
-
-/*
- * `free`s all assignment memory that was allocated.
- */
-void script_Cleanup(void);
-
-#endif // RGBDS_LINK_SCRIPT_H

include/link/sdas_obj.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Assigning all sections a place
 #ifndef RGBDS_LINK_SDAS_OBJ_H

include/link/section.hpp

@@ -1,23 +1,17 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Declarations manipulating symbols
 #ifndef RGBDS_LINK_SECTION_H
 #define RGBDS_LINK_SECTION_H
 
-// GUIDELINE: external code MUST NOT BE AWARE of the data structure used!!
+// GUIDELINE: external code MUST NOT BE AWARE of the data structure used!
 
 #include <stdint.h>
 #include <stdbool.h>
 
-#include "link/main.h"
+#include "link/main.hpp"
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
 
 struct FileStackNode;
 struct Section;

include/link/symbol.hpp

@@ -1,20 +1,14 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // Declarations manipulating symbols
 #ifndef RGBDS_LINK_SYMBOL_H
 #define RGBDS_LINK_SYMBOL_H
 
-// GUIDELINE: external code MUST NOT BE AWARE of the data structure used!!
+// GUIDELINE: external code MUST NOT BE AWARE of the data structure used!
 
 #include <stdint.h>
 
-#include "linkdefs.h"
+#include "linkdefs.hpp"
 
 struct FileStackNode;
 

include/linkdefs.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_LINKDEFS_H
 #define RGBDS_LINKDEFS_H
@@ -12,6 +6,7 @@
 #include <assert.h>
 #include <stdbool.h>
 #include <stdint.h>
+#include <string>
 
 #define RGBDS_OBJECT_VERSION_STRING "RGB9"
 #define RGBDS_OBJECT_REV 9U
@@ -28,17 +23,17 @@ enum RPNCommand {
 	RPN_MUL			= 0x02,
 	RPN_DIV			= 0x03,
 	RPN_MOD			= 0x04,
-	RPN_UNSUB		= 0x05, // FIXME: should be renamed to "NEG" for consistency
+	RPN_NEG			= 0x05,
 	RPN_EXP			= 0x06,
 
 	RPN_OR			= 0x10,
 	RPN_AND			= 0x11,
 	RPN_XOR			= 0x12,
-	RPN_UNNOT		= 0x13, // FIXME: should be renamed to "NOT" for consistency
+	RPN_NOT			= 0x13,
 
 	RPN_LOGAND		= 0x21,
 	RPN_LOGOR		= 0x22,
-	RPN_LOGUNNOT		= 0x23, // FIXME: should be renamed to "LOGNOT" for consistency
+	RPN_LOGNOT		= 0x23,
 
 	RPN_LOGEQ		= 0x30,
 	RPN_LOGNE		= 0x31,
@@ -56,6 +51,8 @@ enum RPNCommand {
 	RPN_BANK_SELF		= 0x52,
 	RPN_SIZEOF_SECT		= 0x53,
 	RPN_STARTOF_SECT	= 0x54,
+	RPN_SIZEOF_SECTTYPE     = 0x55,
+	RPN_STARTOF_SECTTYPE    = 0x56,
 
 	RPN_HRAM		= 0x60,
 	RPN_RST			= 0x61,
@@ -79,9 +76,15 @@ enum SectionType {
 	SECTTYPE_INVALID
 };
 
+enum FileStackNodeType {
+	NODE_REPT,
+	NODE_FILE,
+	NODE_MACRO,
+};
+
 // Nont-`const` members may be patched in RGBLINK depending on CLI flags
 extern struct SectionTypeInfo {
-	char const *const name;
+	std::string const name;
 	uint16_t const startAddr;
 	uint16_t size;
 	uint32_t const firstBank;

include/opmath.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2021, RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_OP_MATH_H
 #define RGBDS_OP_MATH_H

include/platform.hpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020 RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 // platform-specific hacks
 
@@ -33,6 +27,15 @@
 # define S_ISDIR(mode) (((mode) & S_IFMT) == S_IFDIR)
 #endif
 
+// gcc has __PRETTY_FUNCTION__, MSVC has __FUNCSIG__, __func__ is standard
+#ifndef __PRETTY_FUNCTION__
+# ifdef __FUNCSIG__
+#  define __PRETTY_FUNCTION__ __FUNCSIG__
+# else
+#  define __PRETTY_FUNCTION__ __func__
+# endif
+#endif
+
 // MSVC doesn't use POSIX types or defines for `read`
 #ifdef _MSC_VER
 # include <io.h>
@@ -46,15 +49,17 @@
 # include <unistd.h>
 #endif
 
-// MSVC doesn't support `[static N]` for array arguments from C99 or C11
+// C++ doesn't support `[static N]` for array arguments from C99 or C11
-#ifdef _MSC_VER
+#define MIN_NB_ELMS(N) // static (N)
-# define MIN_NB_ELMS(N)
+#define ARR_QUALS(...) // __VA_ARGS__
-# define ARR_QUALS(...)
+#define NONNULL(ptr) *ptr // ptr[static 1]
-# define NONNULL(ptr) *ptr
+#define restrict
+
+// C++ doesn't support designated array initializers, but they're a gcc extension
+#ifdef __GNUC__
+# define AT(index) [index] =
 #else
-# define MIN_NB_ELMS(N) static (N)
+# define AT(index)
-# define ARR_QUALS(...) __VA_ARGS__
-# define NONNULL(ptr) ptr[static 1]
 #endif
 
 // MSVC uses a different name for O_RDWR, and needs an additional _O_BINARY flag
@@ -63,8 +68,10 @@
 # define O_RDWR _O_RDWR
 # define S_ISREG(field) ((field) & _S_IFREG)
 # define O_BINARY _O_BINARY
+# define O_TEXT _O_TEXT
 #elif !defined(O_BINARY) // Cross-compilers define O_BINARY
 # define O_BINARY 0 // POSIX says we shouldn't care!
+# define O_TEXT 0 // Assume that it's not defined either
 #endif // _MSC_VER
 
 // Windows has stdin and stdout open as text by default, which we may not want
@@ -72,7 +79,7 @@
 # include <io.h>
 # define setmode(fd, mode) _setmode(fd, mode)
 #else
-# define setmode(fd, mode) ((void)0)
+# define setmode(fd, mode) (0)
 #endif
 
 #endif // RGBDS_PLATFORM_H

include/util.hpp

@@ -1,14 +1,9 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2019, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #ifndef RGBDS_UTIL_H
 #define RGBDS_UTIL_H
 
+#include <stddef.h>
 #include <stdint.h>
 
 char const *printChar(int c);

include/version.h

@@ -1,27 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef EXTERN_VERSION_H
-#define EXTERN_VERSION_H
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#define PACKAGE_VERSION_MAJOR 0
-#define PACKAGE_VERSION_MINOR 6
-#define PACKAGE_VERSION_PATCH 0
-#define PACKAGE_VERSION_RC 2
-
-char const *get_package_version_string(void);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif // EXTERN_VERSION_H

include/version.hpp

@@ -0,0 +1,16 @@
+/* SPDX-License-Identifier: MIT */
+
+#ifndef EXTERN_VERSION_H
+#define EXTERN_VERSION_H
+
+extern "C" {
+
+#define PACKAGE_VERSION_MAJOR 0
+#define PACKAGE_VERSION_MINOR 7
+#define PACKAGE_VERSION_PATCH 0
+
+char const *get_package_version_string(void);
+
+}
+
+#endif // EXTERN_VERSION_H

man/gbz80.7

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt GBZ80 7
 .Os
 .Sh NAME
@@ -633,7 +628,7 @@ Enter CPU low-power consumption mode until an interrupt occurs.
 The exact behavior of this instruction depends on the state of the
 .Sy IME
 flag.
-.Bl -tag -width indent
+.Bl -tag -width Ds
 .It Sy IME No set
 The CPU enters low-power mode until
 .Em after
@@ -645,7 +640,7 @@ when that returns.
 The behavior depends on whether an interrupt is pending (i.e.\&
 .Ql [IE] & [IF]
 is non-zero).
-.Bl -tag -width indent
+.Bl -tag -width Ds
 .It None pending
 As soon as an interrupt becomes pending, the CPU resumes execution.
 This is like the above, except that the handler is
@@ -1321,9 +1316,13 @@ Flags: None affected.
 .Ss RL r8
 Rotate bits in register
 .Ar r8
-left through carry.
+left, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- C
+  ┏━ Flags ━┓ ┏━━━━━━━ r8 ━━━━━━┓
+┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
+│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1343,9 +1342,13 @@ Set according to result.
 .Ss RL [HL]
 Rotate the byte pointed to by
 .Sy HL
-left through carry.
+left, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- C
+  ┏━ Flags ━┓ ┏━━━━━━ [HL] ━━━━━┓
+┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
+│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1356,9 +1359,13 @@ Flags: See
 .Ss RLA
 Rotate register
 .Sy A
-left through carry.
+left, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- C
+  ┏━ Flags ━┓ ┏━━━━━━━ A ━━━━━━━┓
+┌─╂─   C   ←╂─╂─ b7 ← ... ← b0 ←╂─┐
+│ ┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 1
 .Pp
@@ -1379,8 +1386,12 @@ Set according to result.
 Rotate register
 .Ar r8
 left.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- [7]
+┏━ Flags ━┓   ┏━━━━━━━ r8 ━━━━━━┓
+┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
+┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
+            └─────────────────────┘
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1401,8 +1412,12 @@ Set according to result.
 Rotate the byte pointed to by
 .Sy HL
 left.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- [7]
+┏━ Flags ━┓   ┏━━━━━━ [HL] ━━━━━┓
+┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
+┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
+            └─────────────────────┘
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1414,8 +1429,12 @@ Flags: See
 Rotate register
 .Sy A
 left.
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- [7]
+┏━ Flags ━┓   ┏━━━━━━━ A ━━━━━━━┓
+┃    C   ←╂─┬─╂─ b7 ← ... ← b0 ←╂─┐
+┗━━━━━━━━━┛ │ ┗━━━━━━━━━━━━━━━━━┛ │
+            └─────────────────────┘
+.Ed
 .Pp
 Cycles: 1
 .Pp
@@ -1435,9 +1454,13 @@ Set according to result.
 .Ss RR r8
 Rotate register
 .Ar r8
-right through carry.
+right, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C -> [7 -> 0] -> C
+  ┏━━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
+│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1457,9 +1480,13 @@ Set according to result.
 .Ss RR [HL]
 Rotate the byte pointed to by
 .Sy HL
-right through carry.
+right, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C -> [7 -> 0] -> C
+  ┏━━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
+│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1470,9 +1497,13 @@ Flags: See
 .Ss RRA
 Rotate register
 .Sy A
-right through carry.
+right, through the carry flag.
-.Pp
+.Bd -literal
-.D1 C -> [7 -> 0] -> C
+  ┏━━━━━━━ A ━━━━━━━┓ ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─╂→   C   ─╂─┐
+│ ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛ │
+└─────────────────────────────────┘
+.Ed
 .Pp
 Cycles: 1
 .Pp
@@ -1493,8 +1524,12 @@ Set according to result.
 Rotate register
 .Ar r8
 right.
-.Pp
+.Bd -literal
-.D1 [0] -> [7 -> 0] -> C
+  ┏━━━━━━━ r8 ━━━━━━┓   ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
+│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
+└─────────────────────┘
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1515,8 +1550,12 @@ Set according to result.
 Rotate the byte pointed to by
 .Sy HL
 right.
-.Pp
+.Bd -literal
-.D1 [0] -> [7 -> 0] -> C
+  ┏━━━━━━ [HL] ━━━━━┓   ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
+│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
+└─────────────────────┘
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1528,8 +1567,12 @@ Flags: See
 Rotate register
 .Sy A
 right.
-.Pp
+.Bd -literal
-.D1 [0] -> [7 -> 0] -> C
+  ┏━━━━━━━ A ━━━━━━━┓   ┏━ Flags ━┓
+┌─╂→ b7 → ... → b0 ─╂─┬─╂→   C    ┃
+│ ┗━━━━━━━━━━━━━━━━━┛ │ ┗━━━━━━━━━┛
+└─────────────────────┘
+.Ed
 .Pp
 Cycles: 1
 .Pp
@@ -1653,8 +1696,11 @@ Flags: None affected.
 .Ss SLA r8
 Shift Left Arithmetically register
 .Ar r8 .
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- 0
+┏━ Flags ━┓ ┏━━━━━━━ r8 ━━━━━━┓
+┃    C   ←╂─╂─ b7 ← ... ← b0 ←╂─ 0
+┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1674,8 +1720,11 @@ Set according to result.
 .Ss SLA [HL]
 Shift Left Arithmetically the byte pointed to by
 .Sy HL .
-.Pp
+.Bd -literal
-.D1 C <- [7 <- 0] <- 0
+┏━ Flags ━┓ ┏━━━━━━ [HL] ━━━━━┓
+┃    C   ←╂─╂─ b7 ← ... ← b0 ←╂─ 0
+┗━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1685,9 +1734,13 @@ Flags: See
 .Sx SLA r8
 .Ss SRA r8
 Shift Right Arithmetically register
-.Ar r8 .
+.Ar r8
-.Pp
+.Pq bit 7 of Ar r8 No is unchanged .
-.D1 [7] -> [7 -> 0] -> C
+.Bd -literal
+┏━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
+┃ b7 → ... → b0 ─╂─╂→   C    ┃
+┗━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1706,9 +1759,13 @@ Set according to result.
 .El
 .Ss SRA [HL]
 Shift Right Arithmetically the byte pointed to by
-.Sy HL .
+.Sy HL
-.Pp
+.Pq bit 7 of the byte pointed to by Sy HL No is unchanged .
-.D1 [7] -> [7 -> 0] -> C
+.Bd -literal
+┏━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
+┃ b7 → ... → b0 ─╂─╂→   C    ┃
+┗━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 4
 .Pp
@@ -1719,8 +1776,11 @@ Flags: See
 .Ss SRL r8
 Shift Right Logically register
 .Ar r8 .
-.Pp
+.Bd -literal
-.D1 0 -> [7 -> 0] -> C
+   ┏━━━━━━━ r8 ━━━━━━┓ ┏━ Flags ━┓
+0 ─╂→ b7 → ... → b0 ─╂─╂→   C    ┃
+   ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 2
 .Pp
@@ -1740,15 +1800,18 @@ Set according to result.
 .Ss SRL [HL]
 Shift Right Logically the byte pointed to by
 .Sy HL .
-.Pp
+.Bd -literal
-.D1 0 -> [7 -> 0] -> C
+   ┏━━━━━━ [HL] ━━━━━┓ ┏━ Flags ━┓
+0 ─╂→ b7 → ... → b0 ─╂─╂→   C    ┃
+   ┗━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━┛
+.Ed
 .Pp
 Cycles: 4
 .Pp
 Bytes: 2
 .Pp
 Flags: See
-.Sx SRA r8
+.Sx SRL r8
 .Ss STOP
 Enter CPU very low power mode.
 Also used to switch between double and normal speed CPU modes in GBC.
@@ -1884,10 +1947,15 @@ Flags: See
 .Sx XOR A,r8
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
 .Xr rgbds 7
 .Sh HISTORY
-.Nm rgbds
+.Xr rgbasm 1
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
+was originally written by
-and was later packaged in RGBDS by Justin Lloyd.
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgbasm.1

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBASM 1
 .Os
 .Sh NAME
@@ -17,43 +12,47 @@
 .Op Fl b Ar chars
 .Op Fl D Ar name Ns Op = Ns Ar value
 .Op Fl g Ar chars
-.Op Fl i Ar path
+.Op Fl I Ar path
 .Op Fl M Ar depend_file
 .Op Fl MG
 .Op Fl MP
 .Op Fl MT Ar target_file
 .Op Fl MQ Ar target_file
 .Op Fl o Ar out_file
+.Op Fl P Ar include_file
 .Op Fl p Ar pad_value
 .Op Fl Q Ar fix_precision
 .Op Fl r Ar recursion_depth
 .Op Fl W Ar warning
-.Ar
+.Op Fl X Ar max_errors
+.Ar asmfile
 .Sh DESCRIPTION
 The
 .Nm
 program creates an RGB object file from an assembly source file.
+The object file format is documented in
+.Xr rgbds 5 .
+.Pp
 The input
-.Ar file
+.Ar asmfile
-can be a file path, or
+can be a path to a file, or
 .Cm \-
-denoting
+to read from standard input.
-.Cm stdin .
 .Pp
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
+.Fl \-verb
 is
-.Fl Fl verbose ,
+.Fl \-verbose ,
 but
-.Fl Fl ver
+.Fl \-ver
 is invalid because it could also be
-.Fl Fl version .
+.Fl \-version .
 The arguments are as follows:
 .Bl -tag -width Ds
-.It Fl b Ar chars , Fl Fl binary-digits Ar chars
+.It Fl b Ar chars , Fl \-binary-digits Ar chars
 Change the two characters used for binary constants.
 The defaults are 01.
-.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc
+.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl \-define Ar name Ns Oo = Ns Ar value Oc
 Add a string symbol to the compiled source code.
 This is equivalent to
 .Ql Ar name Ic EQUS No \(dq Ns Ar value Ns \(dq
@@ -62,49 +61,44 @@ in code, or
 if
 .Ar value
 is not specified.
-.It Fl E , Fl Fl export-all
+.It Fl E , Fl \-export-all
 Export all labels, including unreferenced and local labels.
-.It Fl g Ar chars , Fl Fl gfx-chars Ar chars
+.It Fl g Ar chars , Fl \-gfx-chars Ar chars
 Change the four characters used for gfx constants.
 The defaults are 0123.
-.It Fl H , Fl Fl nop-after-halt
+.It Fl H , Fl \-nop-after-halt
-By default,
+Inserts a
-.Nm
-inserts a
-.Ic nop
-instruction immediately after any
-.Ic halt
-instruction,
-but this has been deprecated and prints a warning message the first time it occurs.
-The
-.Fl H
-option opts into this insertion,
-so no warning will be printed.
-.It Fl h , Fl Fl halt-without-nop
-Disables inserting a
 .Ic nop
 instruction immediately after any
 .Ic halt
 instruction.
-.It Fl i Ar path , Fl Fl include Ar path
+This option is deprecated and will be removed in the next version.
-Add an include path.
+.It Fl h , Fl \-halt-without-nop
-.It Fl L , Fl Fl preserve-ld
+This option is redundant and will be removed in the next version.
-By default,
+.It Fl I Ar path , Fl \-include Ar path
+Add a new
+.Dq include path ;
+.Ar path
+must point to a directory.
+When a
+.Ic INCLUDE
+.Pq including the implicit one from Fl P
+or
+.Ic INCBIN
+is attempted,
 .Nm
-optimizes loads of the form
+first looks up the provided path from its working directory; if this fails, it tries again from each of the
-.Ic LD [$FF00+n8],A
+.Dq include path
-into the opcode
+directories, in the order they were provided.
-.Ic LDH [$FF00+n8],A ,
+.It Fl L , Fl \-preserve-ld
-but this has been deprecated and prints a warning message the first time it occurs.
+This option is redundant and will be removed in the next version.
-The
+.It Fl l , Fl \-auto-ldh
-.Fl L
-option disables this optimization.
-.It Fl l , Fl Fl auto-ldh
 Optimize loads of the form
 .Ic LD [$FF00+n8],A
 into the opcode
 .Ic LDH [$FF00+n8],A .
-.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
+This option is deprecated and will be removed in the next version.
+.It Fl M Ar depend_file , Fl \-dependfile Ar depend_file
 Print
 .Xr make 1
 dependencies to
@@ -116,6 +110,7 @@ This makes
 .Nm
 assume that missing files are auto-generated: when
 .Ic INCLUDE
+.Pq including the implicit one from Fl P
 or
 .Ic INCBIN
 is attempted on a non-existent file, it is added as a dependency, then
@@ -144,26 +139,34 @@ but additionally escapes any special
 .Xr make 1
 characters, essentially
 .Sq $ .
-.It Fl o Ar out_file , Fl Fl output Ar out_file
+.It Fl o Ar out_file , Fl \-output Ar out_file
 Write an object file to the given filename.
-.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
+.It Fl P Ar include_file , Fl \-preinclude Ar include_file
-When padding an image, pad with this value.
+Pre-include a file.
+This acts as if a
+.Ql Ic INCLUDE Qq Ar include_file
+was read before the input
+.Ar asmfile .
+.It Fl p Ar pad_value , Fl \-pad-value Ar pad_value
+Use this as the value for
+.Ic DS
+directives in ROM sections, unless overridden.
 The default is 0x00.
-.It Fl Q Ar fix_precision , Fl Fl q-precision Ar fix_precision
+.It Fl Q Ar fix_precision , Fl \-q-precision Ar fix_precision
 Use this as the precision of fixed-point numbers after the decimal point, unless they specify their own precision.
 The default is 16, so fixed-point numbers are Q16.16 (since they are 32-bit integers).
 The argument may start with a
 .Ql \&.
 to match the Q notation, for example,
 .Ql Fl Q Ar .16 .
-.It Fl r Ar recursion_depth , Fl Fl recursion-depth Ar recursion_depth
+.It Fl r Ar recursion_depth , Fl \-recursion-depth Ar recursion_depth
 Specifies the recursion depth past which RGBASM will assume being in an infinite loop.
 The default is 64.
-.It Fl V , Fl Fl version
+.It Fl V , Fl \-version
 Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
+.It Fl v , Fl \-verbose
 Be verbose.
-.It Fl W Ar warning , Fl Fl warning Ar warning
+.It Fl W Ar warning , Fl \-warning Ar warning
 Set warning flag
 .Ar warning .
 A warning message will be printed if
@@ -174,6 +177,13 @@ See the
 section for a list of warnings.
 .It Fl w
 Disable all warning output, even when turned into errors.
+.It Fl X Ar max_errors , Fl \-max-errors Ar max_errors
+If more than this number of errors (not warnings) occur, then abort the assembly process;
+.Fl X 0
+disables this behavior.
+The default is 100 if
+.Nm
+is printing errors to a terminal, and 0 otherwise.
 .El
 .Sh DIAGNOSTICS
 Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process.
@@ -296,17 +306,24 @@ or
 .Fl Wno-truncation
 disables this warning.
 .Fl Wtruncation=1
-warns when an N-bit value's absolute value is 2**N or greater.
+warns when an N-bit value is 2**N or greater, or less than -2**N.
 .Fl Wtruncation=2
 or just
 .Fl Wtruncation
 also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding.
-.It Fl Wunmapped-char
+.It Fl Wunmapped-char=
 Warn when a character goes through charmap conversion but has no defined mapping.
-This warning is always disabled if the active charmap is empty, and/or is the default charmap
+.Fl Wunmapped-char=0
+or
+.Fl Wunmapped-char
+disables this warning.
+.Fl Wunmapped-char=1
+or just
+.Fl Wunmapped-char
+only warns if the active charmap is not empty.
+.Fl Wunmapped-char=2
+warns if the active charmap is empty, and/or is not the default charmap
 .Sq main .
-This warning is enabled by
-.Fl Wall .
 .It Fl Wno-user
 Warn when the
 .Ic WARN
@@ -336,13 +353,17 @@ Please report bugs on
 .Lk https://github.com/gbdev/rgbds/issues GitHub .
 .Sh SEE ALSO
 .Xr rgbasm 5 ,
-.Xr rgbfix 1 ,
 .Xr rgblink 1 ,
+.Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
 .Xr rgbds 5 ,
-.Xr rgbds 7 ,
+.Xr rgbds 7
-.Xr gbz80 7
 .Sh HISTORY
 .Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
+was originally written by
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgbasm.5

@@ -1,12 +1,8 @@
 '\" e
 .\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBASM 5
 .Os
 .Sh NAME
@@ -18,7 +14,7 @@ This is the full description of the language used by
 The description of the instructions supported by the Game Boy CPU is in
 .Xr gbz80 7 .
 .Pp
-It is strongly recommended to have some familiarity with the Game Boy hardware before reading this document.
+It is advisable to have some familiarity with the Game Boy hardware before reading this document.
 RGBDS is specifically targeted at the Game Boy, and thus a lot of its features tie directly to its concepts.
 This document is not intended to be a Game Boy hardware reference.
 .Pp
@@ -30,54 +26,72 @@ but any program that processes RGBDS object files (described in
 .Xr rgbds 5 )
 can be used in its place.
 .Sh SYNTAX
-The syntax is line-based, just as in any other assembler, meaning that you do one instruction or directive per line:
+The syntax is line-based, just as in any other assembler.
+Each line may have components in this order:
 .Pp
-.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
+.Dl Oo Ar directive Oc Oo ;\  Ns Ar comment Oc
+.Dl Oo Ar label : Oc Oo Ar instruction Oo :: Ar instruction ... Oc Oc Oo ;\  Ns Ar comment Oc
 .Pp
-Example:
+Directives are commands to the assembler itself, such as
-.Bd -literal -offset indent
+.Ic PRINTLN ,
-John: ld a,87 ;Weee
+.Ic SECTION ,
-.Ed
+or
+.Ic OPT .
 .Pp
-All reserved keywords (directives, mnemonics, registers, etc.) are case-insensitive;
+Labels tie a name to a specific location within a section (see
-all identifiers (symbol names) are case-sensitive.
+.Sx Labels
+below).
+They must come first in the line.
+.Pp
+Instructions are assembled into Game Boy opcodes.
+Multiple instructions on one line can be separated by double colons
+.Ql :: .
+.Pp
+All reserved keywords (directives, register names, etc.) are case-insensitive;
+all identifiers (labels and other symbol names) are case-sensitive.
 .Pp
 Comments are used to give humans information about the code, such as explanations.
 The assembler
 .Em always
 ignores comments and their contents.
 .Pp
-There are two syntaxes for comments.
+There are two kinds of comments, inline and block.
-The most common is that anything that follows a semicolon
+Inline comments are anything that follows a semicolon
 .Ql \&;
-not inside a string, is a comment until the end of the line.
+not inside a string, until the end of the line.
-The second is a block comment, beginning with
+Block comments, beginning with
 .Ql /*
 and ending with
-.Ql */ .
+.Ql */ ,
-It can be split across multiple lines, or occur in the middle of an expression:
+can be split across multiple lines, or occur in the middle of an expression.
+.Pp
+An example demonstrating these syntax features:
 .Bd -literal -offset indent
-X = /* the value of x
+SECTION "My Code", ROM0\ \ ;\ a directive
-       should be 3 */ 3
+MyFunction:\ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ a label
+    push hl\ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ an instruction
+    /* ...and multiple instructions,
+       with mixed case */
+    ld a, [hli] :: LD H, [HL] :: Ld l, a
+    pop /*wait for it*/ hl
+    ret
 .Ed
 .Pp
 Sometimes lines can be too long and it may be necessary to split them.
 To do so, put a backslash at the end of the line:
 .Bd -literal -offset indent
-    DB 1, 2, 3,\ \[rs]
+    DB 1, 2, 3,\ \e
-       4, 5, 6,\ \[rs]\ ;\ Put it before any comments
+       4, 5, 6,\ \e\ ;\ Put it before any comments
        7, 8, 9
-    DB "Hello,\ \[rs]\ \ ;\ Space before the \[rs] is included
+    DB "Hello,\ \e\ \ ;\ Space before the \e is included
 world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included
 .Ed
 .Ss Symbol interpolation
-A funky feature is
+A funky feature is writing a symbol between
-.Ql {symbol}
+.Ql {braces} ,
-within a string, called
+called
 .Dq symbol interpolation .
-This will paste the contents of
+This will paste the symbol's contents as if they were part of the source file.
-.Ql symbol
-as if they were part of the source file.
 If it is a string symbol, its characters are simply inserted as-is.
 If it is a numeric symbol, its value is converted to hexadecimal notation with a dollar sign
 .Sq $
@@ -85,7 +99,7 @@ prepended.
 .Pp
 Symbol interpolations can be nested, too!
 .Bd -literal -offset indent
-DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
+DEF topic EQUS "life, the universe, and \e"everything\e""
 DEF meaning EQUS "answer"
 ;\ Defines answer = 42
 DEF {meaning} = 42
@@ -170,27 +184,27 @@ Valid print types are:
 Examples:
 .Bd -literal -offset indent
 SECTION "Test", ROM0[2]
-X:             ;\ This works with labels **whose address is known**
+X:                 ;\ This works with labels **whose address is known**
-Y = 3          ;\ This also works with variables
+DEF Y = 3          ;\ This also works with variables
-SUM equ X + Y  ;\ And likewise with numeric constants
+DEF SUM EQU X + Y  ;\ And likewise with numeric constants
 ; Prints "%0010 + $3 == 5"
 PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"
 
 rsset 32
-PERCENT rb 1   ;\ Same with offset constants
+DEF PERCENT rb 1   ;\ Same with offset constants
-VALUE = 20
+DEF VALUE = 20
-RESULT = MUL(20.0, 0.32)
+DEF RESULT = MUL(20.0, 0.32)
 ; Prints "32% of 20 = 6.40"
 PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"
 
-WHO equs STRLWR("WORLD")
+DEF WHO EQUS STRLWR("WORLD")
 ; Prints "Hello world!"
 PRINTLN "Hello {s:WHO}!"
 .Ed
 .Pp
 Although, for these examples,
 .Ic STRFMT
-would be more approriate; see
+would be more appropriate; see
 .Sx String expressions
 further below.
 .Sh EXPRESSIONS
@@ -326,7 +340,7 @@ The following functions are designed to operate with fixed-point numbers:
 .EQ
 delim $$
 .EN
-.Bl -column -offset indent "ATAN2(x, y)"
+.Bl -column -offset indent "ATAN2(y, x)"
 .It Sy Name Ta Sy Operation
 .It Fn DIV x y Ta Fixed-point division $( x \[di] y ) \[mu] ( 2 ^ precision )$
 .It Fn MUL x y Ta Fixed-point multiplication $( x \[mu] y ) \[di] ( 2 ^ precision )$
@@ -342,60 +356,78 @@ delim $$
 .It Fn ASIN x Ta Inverse sine of $x$
 .It Fn ACOS x Ta Inverse cosine of $x$
 .It Fn ATAN x Ta Inverse tangent of $x$
-.It Fn ATAN2 x y Ta Angle between $( x , y )$ and $( 1 , 0 )$
+.It Fn ATAN2 y x Ta Angle between $( x , y )$ and $( 1 , 0 )$
 .El
 .EQ
 delim off
 .EN
 .Pp
+All of these fixed-point functions can take an optional final argument, which is the precision to use.
+For example,
+.Ql MUL(6.0q8, 7.0q8, 8)
+will evaluate to
+.Ql 42.0q8
+no matter what value is set as the current
+.Cm Q
+option.
+.Pp
 The trigonometry functions (
 .Ic SIN ,
 .Ic COS ,
 .Ic TAN ,
-etc) are defined in terms of a circle divided into 65535.0 degrees.
+etc) are defined in terms of a circle divided into 1.0 "turns" (equal to 2pi radians or 360 degrees).
 .Pp
 These functions are useful for automatic generation of various tables.
 For example:
 .Bd -literal -offset indent
-; Generate a 256-byte sine table with values in the range [0, 128]
+; Generate a table of sine values from sin(0.0) to sin(1.0), with
-; (shifted and scaled from the range [-1.0, 1.0])
+; amplitude scaled from [-1.0, 1.0] to [0.0, 128.0]
-ANGLE = 0.0
+DEF turns = 0.0
-    REPT 256
+REPT 256
-        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+    db MUL(64.0, SIN(turns) + 1.0) >> 16
-ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
+    DEF turns += 1.0 / 256
-    ENDR
+ENDR
 .Ed
 .Ss String expressions
 The most basic string expression is any number of characters contained in double quotes
 .Pq Ql \&"for instance" .
 The backslash character
-.Ql \[rs]
+.Ql \e
 is special in that it causes the character following it to be
 .Dq escaped ,
 meaning that it is treated differently from normal.
 There are a number of escape sequences you can use within a string:
-.Bl -column -offset indent "Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc"
+.Bl -column -offset indent "Qo \e1 Qc \[en] Qo \e9 Qc"
 .It Sy String Ta Sy Meaning
-.It Ql \[rs]\[rs] Ta Produces a backslash
+.It Ql \e\e Ta Produces a backslash
-.It Ql \[rs]" Ta Produces a double quote without terminating
+.It Ql \e" Ta Produces a double quote without terminating
-.It Ql \[rs]{ Ta Curly bracket left
+.It Ql \e{ Ta Curly bracket left
-.It Ql \[rs]} Ta Curly bracket right
+.It Ql \e} Ta Curly bracket right
-.It Ql \[rs]n Ta Newline ($0A)
+.It Ql \en Ta Newline ($0A)
-.It Ql \[rs]r Ta Carriage return ($0D)
+.It Ql \er Ta Carriage return ($0D)
-.It Ql \[rs]t Ta Tab ($09)
+.It Ql \et Ta Tab ($09)
-.It Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc Ta Macro argument (Only in the body of a macro; see Sx Invoking macros )
+.It Qo \e1 Qc \[en] Qo \e9 Qc Ta Macro argument Pq Only in the body of a macro; see Sx Invoking macros
-.It Ql \[rs]# Ta All Dv _NARG No macro arguments, separated by commas (Only in the body of a macro)
+.It Ql \e# Ta All Dv _NARG No macro arguments, separated by commas Pq Only in the body of a macro
-.It Ql \[rs]@ Ta Label name suffix (Only in the body of a macro or a Ic REPT No block)
+.It Ql \e@ Ta Label name suffix Pq Only in the body of a macro or a Ic REPT No block
 .El
 (Note that some of those can be used outside of strings, when noted further in this document.)
 .Pp
 Multi-line strings are contained in triple quotes
 .Pq Ql \&"\&"\&"for instance\&"\&"\&" .
-Escape sequences work the same way in multi-line strings; however, literal newline
+Escape sequences work the same way in multi-line strings; however, literal newline characters will be included as-is, without needing to escape them with
-characters will be included as-is, without needing to escape them with
+.Ql \er
-.Ql \[rs]r
 or
-.Ql \[rs]n .
+.Ql \en .
+.Pp
+Raw strings are prefixed by a hash
+.Sq # .
+Inside them, backslashes and braces are treated like regular characters, so they will not be expanded as macro arguments, interpolated symbols, or escape sequences.
+For example, the raw string
+.Ql #"\et\e1{s}\e"
+is equivalent to the regular string
+.Ql "\e\et\e\e1\e{s}\e\e" .
+(Note that this prevents raw strings from including the double quote character.)
+Raw strings also may be contained in triple quotes for them to be multi-line, so they can include literal newline or quote characters (although still not three quotes in a row).
 .Pp
 The following functions operate on string expressions.
 Most of them return a string, however some of these functions actually return an integer and can be used as part of an integer expression!
@@ -407,8 +439,12 @@ Most of them return a string, however some of these functions actually return an
 .It Fn STRIN str1 str2 Ta Returns the first position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
 .It Fn STRRIN str1 str2 Ta Returns the last position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
 .It Fn STRSUB str pos len Ta Returns a substring from Ar str No starting at Ar pos No (first character is position 1, last is position -1) and Ar len No characters long. If Ar len No is not specified the substring continues to the end of Ar str .
-.It Fn STRUPR str Ta Returns Ar str No with all letters in uppercase.
+.It Fn STRUPR str Ta Returns Ar str No with all ASCII letters
-.It Fn STRLWR str Ta Returns Ar str No with all letters in lowercase.
+.Pq Ql a-z
+in uppercase.
+.It Fn STRLWR str Ta Returns Ar str No with all ASCII letters
+.Pq Ql A-Z
+in lowercase.
 .It Fn STRRPL str old new Ta Returns Ar str No with each non-overlapping occurrence of the substring Ar old No replaced with Ar new .
 .It Fn STRFMT fmt args... Ta Returns the string Ar fmt No with each
 .Ql %spec
@@ -418,8 +454,9 @@ pattern replaced by interpolating the format
 with its corresponding argument in
 .Ar args
 .Pq So %% Sc is replaced by the So % Sc character .
-.It Fn CHARLEN str Ta Returns the number of charmap entries in Ar str No with the current charmap.
+.It Fn INCHARMAP str Ta Returns 1 if Ar str No has an entry in the current charmap, and 0 otherwise .
-.It Fn CHARSUB str pos Ta Returns the substring for the charmap entry at Ar pos No in Ar str No (first character is position 1, last is position -1) with the current charmap.
+.It Fn CHARLEN str Ta Returns the number of charmap entries in Ar str No with the current charmap .
+.It Fn CHARSUB str pos Ta Returns the substring for the charmap entry at Ar pos No in Ar str No (first character is position 1, last is position -1) with the current charmap .
 .El
 .Ss Character maps
 When writing text strings that are meant to be displayed on the Game Boy, the character encoding in the ROM may need to be different than the source file encoding.
@@ -431,6 +468,7 @@ CHARMAP "<LF>", 10
 CHARMAP "&iacute", 20
 CHARMAP "A", 128
 .Ed
+.Pp
 This would result in
 .Ql db \(dqAmen<LF>\(dq
 being equivalent to
@@ -446,14 +484,14 @@ and it is automatically selected as the current character map from the beginning
 There is also a character map stack that can be used to save and restore which character map is currently active.
 .Bl -column "NEWCHARMAP name, basename"
 .It Sy Command Ta Sy Meaning
-.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name No and switches to it.
+.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name No and switches to it .
-.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it.
+.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it .
 .It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
 .It Ic PUSHC Ta Push the current character map onto the stack.
 .It Ic POPC Ta Pop a character map off the stack and switch to it.
 .El
 .Pp
-.Sy Note:
+.Sy Note :
 Modifications to a character map take effect immediately from that point onward.
 .Ss Other functions
 There are a few other functions that do various useful things:
@@ -474,17 +512,32 @@ is a label, it returns the bank number the label is in.
 The result may be constant if
 .Nm
 is able to compute it.
-.It Fn SIZEOF arg Ta Returns the size of the section named
+.It Fn SECTION symbol Ta Returns the name of the section that
+.Ar symbol
+is in.
+.Ar symbol
+must have been defined already.
+.It Fn SIZEOF arg Ta If
+.Ar arg
+is a string, this function returns the size of the section named
 .Ar arg .
+If
+.Ar arg
+is a section type keyword, it returns the size of that section type.
 The result is not constant, since only RGBLINK can compute its value.
-.It Fn STARTOF arg Ta Returns the starting address of the section named
+.It Fn STARTOF arg Ta If
+.Ar arg
+is a string, this function returns the starting address of the section named
 .Ar arg .
+If
+.Ar arg
+is a section type keyword, it returns the starting address of that section type.
 The result is not constant, since only RGBLINK can compute its value.
 .It Fn DEF symbol Ta Returns TRUE (1) if
 .Ar symbol
 has been defined, FALSE (0) otherwise.
 String constants are not expanded within the parentheses.
-.It Fn HIGH arg Ta Returns the top 8 bits of the operand if Ar arg No is a label or constant, or the top 8-bit register if it is a 16-bit register.
+.It Fn HIGH arg Ta Returns the top 8 bits of the operand if Ar arg No is a label or constant, or the top 8-bit register if it is a 16-bit register .
 .It Fn LOW arg Ta Returns the bottom 8 bits of the operand if Ar arg No is a label or constant, or the bottom 8-bit register if it is a 16-bit register Pq Cm AF No isn't a valid register for this function .
 .It Fn ISCONST arg Ta Returns 1 if Ar arg Ap s value is known by RGBASM (e.g. if it can be an argument to
 .Ic IF ) ,
@@ -629,14 +682,14 @@ Place the section at an address whose
 .Ar align
 least-significant bits are equal to
 .Ar offset .
-(Note that
+Note that
 .Ic ALIGN Ns Bq Ar align
 is a shorthand for
-.Ic ALIGN Ns Bq Ar align , No 0 ) .
+.Ic ALIGN Ns Bq Ar align , No 0 .
 This option can be used with
 .Bq Ar addr ,
-as long as they don't contradict eachother.
+as long as they don't contradict each other.
-It's also possible to request alignment in the middle of a section, see
+It's also possible to request alignment in the middle of a section; see
 .Sx Requesting alignment
 below.
 .El
@@ -691,6 +744,11 @@ SECTION "OAM Data",WRAM0,ALIGN[8] ;\ align to 256 bytes
 SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ;\ align to 16 bytes
 .Ed
 .El
+.Pp
+The current section can be ended without starting a new section by using
+.Ic ENDSECTION .
+This directive will clear the section context, so you can no longer write code until you start another section.
+It can be useful to avoid accidentally defining code or data in the wrong section.
 .Ss Section stack
 .Ic POPS
 and
@@ -762,7 +820,7 @@ The former is situated in ROM, where the code is stored, the latter in RAM, wher
 .Pp
 You cannot nest
 .Ic LOAD
-blocks, nor can you change the current section within them.
+blocks, nor can you change or stop the current section within them.
 .Pp
 .Ic LOAD
 blocks can use the
@@ -812,7 +870,7 @@ or
 .Ic ROMX .
 .El
 .Pp
-Different declarations of the same unionized section are not appended, but instead overlaid on top of eachother, just like
+Different declarations of the same unionized section are not appended, but instead overlaid on top of each other, just like
 .Sx Unions .
 Similarly, the size of an unionized section is the largest of all its declarations.
 .Ss Section fragments
@@ -1013,7 +1071,7 @@ DEF ARRAY_SIZE EQU 4
 DEF COUNT = 2
 DEF COUNT = 3
 DEF COUNT = ARRAY_SIZE + COUNT
-COUNT = COUNT*2
+DEF COUNT *= 2
 ;\ COUNT now has the value 14
 .Ed
 .Pp
@@ -1066,7 +1124,7 @@ This can be used, for example, to update a constant using a macro, without makin
     def NUM_ITEMS equ 0
 MACRO add_item
     redef NUM_ITEMS equ NUM_ITEMS + 1
-    def ITEM_{02x:NUM_ITEMS} equ \[rs]1
+    def ITEM_{02x:NUM_ITEMS} equ \e1
 ENDM
     add_item 1
     add_item 4
@@ -1131,7 +1189,7 @@ will not expand string constants in their names.
 DEF COUNTREG EQUS "[hl+]"
     ld a,COUNTREG
 
-DEF PLAYER_NAME EQUS "\[rs]"John\[rs]""
+DEF PLAYER_NAME EQUS "\e"John\e""
     db PLAYER_NAME
 .Ed
 .Pp
@@ -1143,7 +1201,7 @@ This will be interpreted as:
 .Pp
 String constants can also be used to define small one-line macros:
 .Bd -literal -offset indent
-DEF pusha EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
+DEF pusha EQUS "push af\enpush bc\enpush de\enpush hl\en"
 .Ed
 .Pp
 Note that colons
@@ -1161,7 +1219,7 @@ For example:
 DEF s EQUS "Hello, "
 REDEF s EQUS "{s}world!"
 ; prints "Hello, world!"
-PRINTLN "{s}\n"
+PRINTLN "{s}\en"
 .Ed
 .Pp
 .Sy Important note :
@@ -1226,16 +1284,6 @@ The example above defines
 as a new macro.
 String constants are not expanded within the name of the macro.
 .Pp
-(Using the
-.Em deprecated
-older syntax
-.Ql MyMacro: MACRO
-instead of
-.Ql MACRO MyMacro ,
-with a single colon
-.Ql \&:
-following the macro's name, string constants may be expanded for the name.)
-.Pp
 Macros can't be exported or imported.
 .Pp
 Plainly nesting macro definitions is not allowed, but this can be worked around using
@@ -1252,18 +1300,18 @@ ENDM
 But this will:
 .Bd -literal -offset indent
 MACRO outer
-DEF definition EQUS "MACRO inner\[rs]nPRINTLN \[rs]"Hello!\[rs]"\[rs]nENDM"
+DEF definition EQUS "MACRO inner\enPRINTLN \e"Hello!\e"\enENDM"
     definition
     PURGE definition
 ENDM
 .Ed
 .Pp
 Macro arguments support all the escape sequences of strings, as well as
-.Ql \[rs],
+.Ql \e,
 to escape commas, as well as
-.Ql \[rs](
+.Ql \e(
 and
-.Ql \[rs])
+.Ql \e)
 to escape parentheses, since those otherwise separate and enclose arguments, respectively.
 .Ss Exporting and importing symbols
 Importing and exporting of symbols is a feature that is very useful when your project spans many source files and, for example, you need to jump to a routine defined in another file.
@@ -1280,13 +1328,13 @@ and so on to be accessible to other files during the link process:
 For example, if you have the following three files:
 .Pp
 .Ql a.asm :
-.Bd -literal -compact
+.Bd -literal -offset indent -compact
 SECTION "a", WRAM0
 LabelA:
 .Ed
 .Pp
 .Ql b.asm :
-.Bd -literal -compact
+.Bd -literal -offset indent -compact
 SECTION "b", WRAM0
 ExportedLabelB1::
 ExportedLabelB2:
@@ -1294,7 +1342,7 @@ ExportedLabelB2:
 .Ed
 .Pp
 .Ql c.asm :
-.Bd -literal -compact
+.Bd -literal -offset indent -compact
 SECTION "C", ROM0[0]
 	dw LabelA
 	dw ExportedLabelB1
@@ -1310,7 +1358,7 @@ and
 but not
 .Ql LabelA ,
 so linking them together will fail:
-.Bd -literal
+.Bd -literal -offset indent
 $ rgbasm -o a.o a.asm
 $ rgbasm -o b.o b.asm
 $ rgbasm -o c.o c.asm
@@ -1324,7 +1372,7 @@ Note also that only exported symbols will appear in symbol and map files produce
 .Ss Purging symbols
 .Ic PURGE
 allows you to completely remove a symbol from the symbol table as if it had never existed.
-.Em USE WITH EXTREME CAUTION!!!
+.Em USE WITH EXTREME CAUTION !
 I can't stress this enough,
 .Sy you seriously need to know what you are doing .
 DON'T purge a symbol that you use in expressions the linker needs to calculate.
@@ -1343,8 +1391,6 @@ The following symbols are defined by the assembler:
 .It Dv @ Ta Ic EQU Ta PC value (essentially, the current memory address)
 .It Dv _RS Ta Ic = Ta _RS Counter
 .It Dv _NARG Ta Ic EQU Ta Number of arguments passed to macro, updated by Ic SHIFT
-.It Dv __LINE__ Ta Ic EQU Ta The current line number
-.It Dv __FILE__ Ta Ic EQUS Ta The current filename
 .It Dv __DATE__ Ta Ic EQUS Ta Today's date
 .It Dv __TIME__ Ta Ic EQUS Ta The current time
 .It Dv __ISO_8601_LOCAL__ Ta Ic EQUS Ta ISO 8601 timestamp (local)
@@ -1388,6 +1434,27 @@ In ROM sections, it will be filled with the value passed to the
 .Fl p
 command-line option, except when using overlays with
 .Fl O .
+.Pp
+Instead of an exact number of bytes, you can specify
+.Ic ALIGN Ns Bq Ar align , offset
+to allocate however many bytes are required to align the subsequent data.
+Thus,
+.Sq Ic DS ALIGN Ns Bo Ar align , offset Bc , No ...
+is equivalent to
+.Sq Ic DS Ar n , No ...
+followed by
+.Sq Ic ALIGN Ns Bq Ar align , offset ,
+where
+.Ar n
+is the minimum value needed to satisfy the
+.Ic ALIGN
+constraint (see
+.Sx Requesting alignment
+below).
+Note that
+.Ic ALIGN Ns Bq Ar align
+is a shorthand for
+.Ic ALIGN Ns Bq Ar align , No 0 .
 .Ss Defining constant data in ROM
 .Ic DB
 defines a list of bytes that will be stored in the final image.
@@ -1561,19 +1628,19 @@ ENDM
 .Pp
 This is fine, but only if you use the macro no more than once per scope.
 To get around this problem, there is the escape sequence
-.Ic \[rs]@
+.Ic \e@
 that expands to a unique string.
 .Pp
-.Ic \[rs]@
+.Ic \e@
 also works in
 .Ic REPT
 blocks.
 .Bd -literal -offset indent
 MACRO LoopyMacro
             xor  a,a
-\&.loop\[rs]@     ld   [hl+],a
+\&.loop\e@     ld   [hl+],a
             dec  c
-            jr   nz,.loop\[rs]@
+            jr   nz,.loop\e@
 ENDM
 .Ed
 .Pp
@@ -1593,18 +1660,18 @@ which references the same macro, which has the same problem.
 .Pp
 It's possible to pass arguments to macros as well!
 You retrieve the arguments by using the escape sequences
-.Ic \[rs]1
+.Ic \e1
 through
-.Ic \[rs]9 , \[rs]1
+.Ic \e9 , \e1
 being the first argument specified on the macro invocation.
 .Bd -literal -offset indent
 MACRO LoopyMacro
-            ld   hl,\[rs]1
+            ld   hl,\e1
-            ld   c,\[rs]2
+            ld   c,\e2
             xor  a,a
-\&.loop\[rs]@     ld   [hl+],a
+\&.loop\e@     ld   [hl+],a
             dec  c
-            jr   nz,.loop\[rs]@
+            jr   nz,.loop\e@
             ENDM
 .Ed
 .Pp
@@ -1617,14 +1684,14 @@ LoopyMacro MyVars,54
 Arguments are passed as string constants, although there's no need to enclose them in quotes.
 Thus, an expression will not be evaluated first but kind of copy-pasted.
 This means that it's probably a very good idea to use brackets around
-.Ic \[rs]1
+.Ic \e1
 to
-.Ic \[rs]9
+.Ic \e9
 if you perform further calculations on them.
 For instance, consider the following:
 .Bd -literal -offset indent
 MACRO print_double
-    PRINTLN \[rs]1 * 2
+    PRINTLN \e1 * 2
 ENDM
     print_double 1 + 2
 .Ed
@@ -1639,15 +1706,15 @@ Line continuations work as usual inside macros or lists of macro arguments.
 However, some characters need to be escaped, as in the following example:
 .Bd -literal -offset indent
 MACRO PrintMacro1
-    PRINTLN STRCAT(\[rs]1)
+    PRINTLN STRCAT(\e1)
 ENDM
-    PrintMacro1 "Hello "\[rs], \[rs]
+    PrintMacro1 "Hello "\e, \e
                        "world"
 MACRO PrintMacro2
-    PRINT \[rs]1
+    PRINT \e1
 ENDM
-    PrintMacro2 STRCAT("Hello ", \[rs]
+    PrintMacro2 STRCAT("Hello ", \e
-                       "world\[rs]n")
+                       "world\en")
 .Ed
 .Pp
 The comma in
@@ -1657,34 +1724,34 @@ The comma in
 .Ql PrintMacro2
 does not need escaping because it is inside parentheses, similar to macro arguments in C.
 The backslash in
-.Ql \[rs]n
+.Ql \en
 also does not need escaping because string literals work as usual inside macro arguments.
 .Pp
 Since there are only nine digits, you can only access the first nine macro arguments like this.
 To use the rest, you need to put the multi-digit argument number in angle brackets, like
-.Ql \[rs]<10> .
+.Ql \e<10> .
 This bracketed syntax supports decimal numbers and numeric constant symbols.
 For example,
-.Ql \[rs]<_NARG>
+.Ql \e<_NARG>
 will get the last argument.
 .Pp
 Other macro arguments and symbol interpolations will be expanded inside the angle brackets.
 For example, if
-.Ql \[rs]1
+.Ql \e1
 is
 .Ql 13 ,
 then
-.Ql \[rs]<\[rs]1>
+.Ql \e<\e1>
 will expand to
-.Ql \[rs]<13> .
+.Ql \e<13> .
 Or if
 .Ql v10 = 42
 and
 .Ql x = 10 ,
 then
-.Ql \[rs]<v{d:x}>
+.Ql \e<v{d:x}>
 will expand to
-.Ql \[rs]<42> .
+.Ql \e<42> .
 .Pp
 Another way to access more than nine macro arguments is the
 .Ic SHIFT
@@ -1692,11 +1759,11 @@ command, a special command only available in macros.
 It will shift the arguments by one to the left, and decrease
 .Dv _NARG
 by 1.
-.Ic \[rs]1
+.Ic \e1
 will get the value of
-.Ic \[rs]2 , \[rs]2
+.Ic \e2 , \e2
 will get the value of
-.Ic \[rs]3 ,
+.Ic \e3 ,
 and so forth.
 .Pp
 .Ic SHIFT
@@ -1715,9 +1782,9 @@ and
 commands print text and values to the standard output.
 Useful for debugging macros, or wherever you may feel the need to tell yourself some important information.
 .Bd -literal -offset indent
-PRINT "Hello world!\[rs]n"
+PRINT "Hello world!\en"
 PRINTLN "Hello world!"
-PRINT _NARG, " arguments\[rs]n"
+PRINT _NARG, " arguments\en"
 PRINTLN "sum: ", 2+3, " product: ", 2*3
 PRINTLN "Line #", __LINE__
 PRINTLN STRFMT("E = %f", 2.718)
@@ -1731,7 +1798,7 @@ For different formats, use
 .Ic STRFMT .
 .It Ic PRINTLN
 prints out each of its comma-separated arguments, if any, followed by a line feed
-.Pq Ql \[rs]n .
+.Pq Ql \en .
 .El
 .Ss Automatically repeating blocks of code
 Suppose you want to unroll a time consuming loop without copy-pasting it.
@@ -1755,17 +1822,16 @@ You can also use
 .Ic REPT
 to generate tables on the fly:
 .Bd -literal -offset indent
-; Generate a 256-byte sine table with values in the range [0, 128]
+; Generate a table of square values from 0**2 = 0 to 100**2 = 10000
-; (shifted and scaled from the range [-1.0, 1.0])
+DEF x = 0
-ANGLE = 0.0
+REPT 101
-    REPT 256
+    dw x * x
-        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+    DEF x += 1
-ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
+ENDR
-    ENDR
 .Ed
 .Pp
 As in macros, you can also use the escape sequence
-.Ic \[rs]@ .
+.Ic \e@ .
 .Ic REPT
 blocks can be nested.
 .Pp
@@ -1853,7 +1919,7 @@ This will print:
 Just like with
 .Ic REPT
 blocks, you can use the escape sequence
-.Ic \[rs]@
+.Ic \e@
 inside of
 .Ic FOR
 blocks, and they can be nested.
@@ -1974,6 +2040,13 @@ calls infinitely (or until you run out of memory, whichever comes first).
 .Bd -literal -offset indent
     INCLUDE "irq.inc"
 .Ed
+.Pp
+You may also implicitly
+.Ic INCLUDE
+a file before the source file with the
+.Fl P
+option of
+.Xr rgbasm 1 .
 .Ss Conditional assembling
 The four commands
 .Ic IF , ELIF , ELSE ,
@@ -2086,16 +2159,31 @@ Note that
 .Ic ALIGN Ar align
 is a shorthand for
 .Ic ALIGN Ar align , No 0 .
+.Pp
+There may be times when you don't just want to specify an alignment constraint at the current location, but also skip ahead until the constraint can be satisfied.
+In that case, you can use
+.Ic DS ALIGN Ns Bq Ar align , offset
+to allocate however many bytes are required to align the subsequent data.
+.Pp
+If the constraint cannot be met by skipping any amount of space, an error is produced.
+Note that
+.Ic ALIGN Ns Bq Ar align
+is a shorthand for
+.Ic ALIGN Ns Bq Ar align , No 0 .
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
 .Xr rgblink 1 ,
 .Xr rgblink 5 ,
+.Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
 .Xr rgbds 5 ,
-.Xr rgbds 7 ,
+.Xr rgbds 7
-.Xr gbz80 7
 .Sh HISTORY
-.Nm
+.Xr rgbasm 1
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
+was originally written by
-and was later packaged in RGBDS by Justin Lloyd.
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgbds.5

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBDS 5
 .Os
 .Sh NAME
@@ -121,9 +116,9 @@ Local symbols are stored as their full name
 .It Cm BYTE Ar Type
 .Bl -column "Value" -compact
 .It Sy Value Ta Sy Meaning
-.It 0 Ta Sy Local No symbol only used in this file.
+.It 0 Ta Sy Local No symbol only used in this file .
-.It 1 Ta Sy Import No of an exported symbol (by name) from another object file.
+.It 1 Ta Sy Import No of an exported symbol (by name) from another object file .
-.It 2 Ta Sy Exported No symbol visible from other object files.
+.It 2 Ta Sy Exported No symbol visible from other object files .
 .El
 .It Cm IF Ar Type No \(!= 1
 If the symbol is defined in this object file...
@@ -323,8 +318,8 @@ RGBDS encodes RPN expressions as an array of
 .Cm BYTE Ns s .
 The first byte encodes either an operator, or a literal, which consumes more
 .Cm BYTE Ns s
-after it.
+after it:
-.Bl -column -offset Ds "Value"
+.Bl -column "Value"
 .It Sy Value Ta Sy Meaning
 .It Li $00 Ta Addition operator Pq Ql +
 .It Li $01 Ta Subtraction operator Pq Ql -
@@ -349,23 +344,33 @@ after it.
 .It Li $40 Ta Left shift operator Pq Ql <<
 .It Li $41 Ta Arithmetic/signed right shift operator Pq Ql >>
 .It Li $42 Ta Logical/unsigned right shift operator Pq Ql >>>
-.It Li $50 Ta Fn BANK symbol ,
+.It Li $50 Ta Fn BANK symbol ;
 followed by the
 .Ar symbol Ap s Cm LONG
 ID.
-.It Li $51 Ta Fn BANK section ,
+.It Li $51 Ta Fn BANK section ;
 followed by the
 .Ar section Ap s Cm STRING
 name.
 .It Li $52 Ta PC's Fn BANK Pq i.e. Ql BANK(@) .
-.It Li $53 Ta Fn SIZEOF section ,
+.It Li $53 Ta Fn SIZEOF section ;
 followed by the
 .Ar section Ap s Cm STRING
 name.
-.It Li $54 Ta Fn STARTOF section ,
+.It Li $54 Ta Fn STARTOF section ;
 followed by the
 .Ar section Ap s Cm STRING
 name.
+.It Li $55 Ta Fn SIZEOF sectiontype ;
+followed by the
+.Ar sectiontype Ap s Cm BYTE
+value
+.Pq see the Ar Type No values in Sx Sections .
+.It Li $56 Ta Fn STARTOF sectiontype ;
+followed by the
+.Ar sectiontype Ap s Cm BYTE
+value
+.Pq see the Ar Type No values in Sx Sections .
 .It Li $60 Ta Ql ldh
 check.
 Checks if the value is a valid
@@ -383,23 +388,29 @@ Checks if the value is a valid
 vector, that is one of $00, $08, $10, $18, $20, $28, $30, or $38.
 The value is then ORed with $C7
 .Pq Ql \&| $C7 .
-.It Li $80 Ta Integer literal.
+.It Li $80 Ta Integer literal; followed by the
-Followed by the
 .Cm LONG
 integer.
-.It Li $81 Ta A symbol's value.
+.It Li $81 Ta A symbol's value; followed by the symbol's
-Followed by the symbol's
 .Cm LONG
 ID.
 .El
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
+.Xr rgbasm 5 ,
 .Xr rgblink 1 ,
-.Xr rgbds 7 ,
+.Xr rgblink 5 ,
-.Xr gbz80 7
+.Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
+.Xr rgbds 7
 .Sh HISTORY
-.Nm
+.Xr rgbasm 1
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
+and
-and was later packaged in RGBDS by Justin Lloyd.
+.Xr rgblink 1
+were originally written by
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgbds.7

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBDS 7
 .Os
 .Sh NAME
@@ -14,44 +9,65 @@
 .Sh EXAMPLES
 To get a working ROM image from a single assembly source file:
 .Bd -literal -offset indent
-$ rgbasm \-o bar.o foo.asm
+$ rgbasm \-o game.o game.asm
-$ rgblink \-o baz.gb bar.o
+$ rgblink \-o game.gb game.o
-$ rgbfix \-v \-p 0 baz.gb
+$ rgbfix \-v \-p 0 game.gb
 .Ed
-Or in a single command line:
+.Pp
+Or in a single command line, without creating an intermediate object file:
 .Bd -literal -offset indent
-$ rgbasm \-o - foo.asm | rgblink \-o - - | rgbfix \-v \-p 0 - > baz.gb
+$ (rgbasm -o - - | rgblink -o - - | rgbfix -v -p 0) < game.asm > game.gb
 .Ed
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
-.Xr rgbfix 1 ,
+.Xr rgbasm 5 ,
 .Xr rgblink 1 ,
-.Xr rgbds 5 ,
+.Xr rgblink 5 ,
-.Xr gbz80 7
+.Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
+.Xr rgbds 5
 .Sh HISTORY
 .Bl -item
 .It
-1997, Carsten S\(/orensen (AKA SurfSmurf) writes ASMotor as a general-purpose
+1996-10-01:
-assembler/linker system for DOS/Win32.
+.An Carsten S\(/orensen
+.Pq a.k.a. SurfSmurf
+releases xAsm, xLink, and RGBFix, a Game Boy SM83 (GBZ80) assembler/linker system for DOS/Win32.
 .It
-1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and produce GBZ80
+1997-07-03: S\(/orensen releases ASMotor, packaging the three programs together and moving towards making them a general-purpose target-independent system.
-assembly/machine code, and releases this version as RGBDS.
 .It
-2009, Vegard Nossum adapts the code to be more UNIX-like and releases this
+1999-08-01:
-version as rgbds-linux on GitHub.
+.An Justin Lloyd
+.Pq a.k.a. Otaku no Zoku
+adapts ASMotor to re-focus on SM83 assembly/machine code, and releases this version as RGBDS.
 .It
-2010, Anthony J. Bentley forks that repository.
+2009-06-11:
-The fork becomes the reference implementation of rgbds.
+.An Vegard Nossum
+adapts the code to be more UNIX-like and releases this version as rgbds-linux.
 .It
-2017, Bentley's repository is moved to a neutral name.
+2010-01-12:
-It is now maintained by a number of contributors at
+.An Anthony J. Bentley
-.Lk https://github.com/rednex/rgbds .
+forks Nossum's repository.
+The fork becomes the reference implementation of RGBDS.
 .It
-2018, codebase relicensed under the MIT license.
+2015-01-18:
+.An stag019
+begins implementing rgbgfx, a PNG‐to‐Game Boy graphics converter, for eventual integration into RGBDS.
 .It
-2020, repository is moved to the gbdev organisation, at
+2016-09-05: rgbgfx is integrated into Bentley's repository.
-.Lk https://github.com/gbdev/rgbds .
+.It
-The
+2017-02-23: Bentley's repository is moved to the
+.Lk https://github.com/rednex/rgbds rednex
+organization.
+.It
+2018-01-26: The codebase is relicensed under the MIT license.
+.It
+2020-09-15: The repository is moved to the
+.Lk https://github.com/gbdev/rgbds gbdev
+organization.
+.It
+2022-05-17: The
 .Lk https://rgbds.gbdev.io
-website serving documentation and downloads is created.
+website for RGBDS documentation and downloads is published.
 .El

man/rgbfix.1

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBFIX 1
 .Os
 .Sh NAME
@@ -41,32 +36,38 @@ Developers are advised to fill those fields with 0x00 bytes in their source code
 and to have already populated whichever fields they don't specify using
 .Nm .
 .Pp
+The input
+.Ar asmfile
+can be a path to a file, or
+.Cm \-
+to read from standard input.
+.Pp
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl color-o
+.Fl \-color-o
 is
-.Fl Fl color-only ,
+.Fl \-color-only ,
 but
-.Fl Fl color
+.Fl \-color
 is invalid because it could also be
-.Fl Fl color-compatible .
+.Fl \-color-compatible .
 Options later in the command line override those set earlier.
 Accepted options are as follows:
 .Bl -tag -width Ds
-.It Fl C , Fl Fl color-only
+.It Fl C , Fl \-color-only
 Set the Game Boy Color\(enonly flag
 .Pq Ad 0x143
 to 0xC0.
 This overrides
 .Fl c
 if it was set prior.
-.It Fl c , Fl Fl color-compatible
+.It Fl c , Fl \-color-compatible
 Set the Game Boy Color\(encompatible flag:
 .Pq Ad 0x143
 to 0x80.
 This overrides
 .Fl c
 if it was set prior.
-.It Fl f Ar fix_spec , Fl Fl fix-spec Ar fix_spec
+.It Fl f Ar fix_spec , Fl \-fix-spec Ar fix_spec
 Fix certain header values that the Game Boy checks for correctness.
 Alternatively, intentionally trash these values by writing their binary inverse instead.
 .Ar fix_spec
@@ -89,26 +90,26 @@ Fix the global checksum
 .It Cm G
 Trash the global checksum.
 .El
-.It Fl i Ar game_id , Fl Fl game-id Ar game_id
+.It Fl i Ar game_id , Fl \-game-id Ar game_id
 Set the game ID string
 .Pq Ad 0x13F Ns \(en Ns Ad 0x142
 to a given string.
 If it's longer than 4 chars, it will be truncated, and a warning emitted.
-.It Fl j , Fl Fl non-japanese
+.It Fl j , Fl \-non-japanese
 Set the non-Japanese region flag
 .Pq Ad 0x14A
 to 0x01.
-.It Fl k Ar licensee_str , Fl Fl new-licensee Ar licensee_str
+.It Fl k Ar licensee_str , Fl \-new-licensee Ar licensee_str
 Set the new licensee string
 .Pq Ad 0x144 Ns \(en Ns Ad 0x145
 to a given string.
 If it's longer than 2 chars, it will be truncated, and a warning emitted.
-.It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
+.It Fl l Ar licensee_id , Fl \-old-licensee Ar licensee_id
 Set the old licensee code
 .Pq Ad 0x14B
 to a given value from 0 to 0xFF.
 This value is deprecated and should be set to 0x33 in all new software.
-.It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
+.It Fl m Ar mbc_type , Fl \-mbc-type Ar mbc_type
 Set the MBC type
 .Pq Ad 0x147
 to a given value from 0 to 0xFF.
@@ -121,13 +122,13 @@ Any amount of whitespace (space and tabs) is allowed around plus signs, and the
 There are special considerations to take for the TPP1 mapper; see the
 .Sx TPP1
 section below.
-.It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
+.It Fl n Ar rom_version , Fl \-rom-version Ar rom_version
 Set the ROM version
 .Pq Ad 0x14C
 to a given value from 0 to 0xFF.
-.It Fl O , Fl Fl overwrite
+.It Fl O , Fl \-overwrite
 Allow overwriting different non-zero bytes in the header without a warning being emitted.
-.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
+.It Fl p Ar pad_value , Fl \-pad-value Ar pad_value
 Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
 .Nm
 will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
@@ -135,11 +136,11 @@ The cartridge size byte
 .Pq Ad 0x148
 will be changed to reflect this new size.
 The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
-.It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
+.It Fl r Ar ram_size , Fl \-ram-size Ar ram_size
 Set the RAM size
 .Pq Ad 0x149
 to a given value from 0 to 0xFF.
-.It Fl s , Fl Fl sgb-compatible
+.It Fl s , Fl \-sgb-compatible
 Set the SGB flag
 .Pq Ad 0x146
 to 0x03.
@@ -147,7 +148,7 @@ This flag will be ignored by the SGB unless the old licensee code is 0x33!
 If this is given as well as
 .Fl l ,
 but is not set to 0x33, a warning will be printed.
-.It Fl t Ar title , Fl Fl title Ar title
+.It Fl t Ar title , Fl \-title Ar title
 Set the title string
 .Pq Ad 0x134 Ns \(en Ns Ad 0x143
 to a given string.
@@ -159,9 +160,9 @@ is specified, 15 characters if the CGB flag
 or
 .Fl C )
 is specified but the game ID is not, and 16 characters otherwise.
-.It Fl V , Fl Fl version
+.It Fl V , Fl \-version
 Print the version of the program and exit.
-.It Fl v , Fl Fl validate
+.It Fl v , Fl \-validate
 Equivalent to
 .Fl f Cm lhg .
 .El
@@ -235,9 +236,14 @@ Please report bugs on
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
 .Xr rgblink 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
 .Xr rgbds 7
 .Sh HISTORY
 .Nm
-was originally released by Carsten S\(/orensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd.
+was originally written by
+.An Carsten S\(/orensen
+as a standalone program called GBFix, which was then packaged in ASMotor, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgbgfx.1

@@ -1,12 +1,8 @@
 '\" e
 .\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBGFX 1
 .Os
 .Sh NAME
@@ -14,8 +10,7 @@
 .Nd Game Boy graphics converter
 .Sh SYNOPSIS
 .Nm
-.Op Fl r Ar stride
+.Op Fl CmOuVZ
-.Op Fl CmuVZ
 .Op Fl v Op Fl v No ...
 .Op Fl a Ar attrmap | Fl A
 .Op Fl b Ar base_ids
@@ -27,6 +22,7 @@
 .Op Fl o Ar out_file
 .Op Fl p Ar pal_file | Fl P
 .Op Fl q Ar pal_map | Fl Q
+.Op Fl r Ar stride
 .Op Fl s Ar nb_colors
 .Op Fl t Ar tilemap | Fl T
 .Op Fl x Ar quantity
@@ -44,13 +40,13 @@ convert each of those squares into 1bpp or 2bpp tile data, and save all of the t
 It also has options to generate a tile map, attribute map, and/or palette set as well; more on that and how the conversion process can be tweaked below.
 .Sh ARGUMENTS
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
+.Fl \-verb
 is
-.Fl Fl verbose ,
+.Fl \-verbose ,
 but
-.Fl Fl ver
+.Fl \-ver
 is invalid because it could also be
-.Fl Fl version .
+.Fl \-version .
 .Pp
 .Nm
 accepts decimal, binary, and hexadecimal numbers in option arguments.
@@ -72,9 +68,21 @@ All of these are equivalent:
 .Ql 0X2A ,
 .Ql 0x2a .
 .Pp
+Unless otherwise noted, passing
+.Ql -
+(a single dash) as a file name makes
+.Nm
+use standard input (for input files) or standard output (for output files).
+To suppress this behavior, and open a file in the current directory actually called
+.Ql - ,
+pass
+.Ql ./-
+instead.
+Using standard input or output more than once in a single command will likely produce unexpected results.
+.Pp
 The following options are accepted:
 .Bl -tag -width Ds
-.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap
+.It Fl a Ar attrmap , Fl \-attr-map Ar attrmap
 Generate an attribute map, which is a file containing tile
 .Dq attributes .
 For each square of the input image, its corresponding attribute map byte contains the mirroring bits (if
@@ -90,23 +98,20 @@ The output is written just like the tile map (see
 follows the same order
 .Pq Fl Z ,
 and has the same size.
-.It Fl A , Fl Fl output-attr-map
+.It Fl A , Fl \-auto-attr-map
 Same as
-.Fl a Ar path ,
+.Fl a Ar base_path Ns .attrmap
-where
+.Pq see Sx Automatic output paths .
-.Ar path
+.It Fl b Ar base_ids , Fl \-base-tiles Ar base_ids
-is the input image's path with the extension set to
-.Pa .attrmap .
-.It Fl b Ar base_ids , Fl Fl base-tiles Ar base_ids
 Set the base IDs for tile map output.
 .Ar base_ids
 should be one or two numbers between 0 and 255, separated by a comma; they are for bank 0 and bank 1 respectively.
 Both default to 0.
-.It Fl C , Fl Fl color-curve
+.It Fl C , Fl \-color-curve
 When generating palettes, use a color curve mimicking the Game Boy Color's screen.
 The resulting colors may look closer to the input image's
 .Sy on hardware and accurate emulators .
-.It Fl c Ar color_spec , Fl Fl colors Ar color_spec
+.It Fl c Ar color_spec , Fl \-colors Ar color_spec
 Use the specified color palettes instead of having
 .Nm
 automatically determine some.
@@ -145,16 +150,18 @@ The expected format is
 .Ql format:path ,
 where
 .Ar path
-is a path to a file, which will be processed according to the
+is a path to a file
+.Ql ( -
+is not treated specially), which will be processed according to the
 .Ar format .
 See
 .Sx PALETTE SPECIFICATION FORMATS
 for a list of formats and their descriptions.
 .El
-.It Fl d Ar depth , Fl Fl depth Ar depth
+.It Fl d Ar depth , Fl \-depth Ar depth
 Set the bit depth of the output tile data, in bits per pixel (bpp), either 1 or 2 (the default).
 This changes how tile data is output, and the maximum number of colors per palette (2 and 4 respectively).
-.It Fl L Ar slice , Fl Fl slice Ar slice
+.It Fl L Ar slice , Fl \-slice Ar slice
 Only process a given rectangle of the image.
 This is useful for example if the input image is a sheet of some sort, and you want to convert each cel individually.
 The default is to process the whole image as-is.
@@ -165,14 +172,19 @@ The numbers must be separated by commas; space is allowed around all punctuation
 The first number pair specifies the X and Y coordinates of the top-left pixel that will be processed (anything above it or to its left will be ignored).
 The second number pair specifies how many tiles to process horizontally and vertically, respectively.
 .Pp
-.Sy Fl L Sy is ignored in reverse mode , No no padding is inserted .
+.Fl L Sy is ignored in reverse mode , No no padding is inserted .
-.It Fl m , Fl Fl mirror-tiles
+.It Fl m , Fl \-mirror-tiles
-Deduplicate tiles that are mirrors of each other.
+Deduplicate tiles that are symmetrical mirror images of each other.
+Only one of each unique tile will be saved in the tile data file, with mirror images counting as duplicates.
 Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
-Useful with a tile map and attribute map together to keep track of the duplicated tiles and the dimension(s) mirrored.
+Useful with a tile map and attribute map together (see
+.Fl a
+and
+.Fl t )
+to keep track of the duplicated tiles and the dimension(s) mirrored.
 Implies
 .Fl u .
-.It Fl N Ar nb_tiles , Fl Fl nb-tiles Ar nb_tiles
+.It Fl N Ar nb_tiles , Fl \-nb-tiles Ar nb_tiles
 Set a maximum number of tiles that can be placed in each VRAM bank.
 .Ar nb_tiles
 should be one or two numbers between 0 and 256, separated by a comma; if the latter is omitted, it defaults to 0.
@@ -184,7 +196,7 @@ will abort.
 If
 .Fl N
 is not specified, no limit will be set on the amount of tiles placed in bank 0, and tiles will not be placed in bank 1.
-.It Fl n Ar nb_pals , Fl Fl nb-palettes Ar nb_pals
+.It Fl n Ar nb_pals , Fl \-nb-palettes Ar nb_pals
 Abort if more than
 .Ar nb_pals
 palettes are generated.
@@ -192,30 +204,31 @@ This may not be more than 256.
 .Pp
 Note that attribute map output only has 3 bits for the palette ID, so a limit higher than 8 may yield incomplete data unless relying on a palette map
 .Pq see Fl q .
-.It Fl o Ar out_file , Fl Fl output Ar out_file
+.It Fl O , Fl \-group-outputs
+Sets the
+.Sq base path
+to be the output tile data path from
+.Fl o
+instead of the input image path
+.Pq see Sx Automatic output paths .
+.It Fl o Ar out_file , Fl \-output Ar out_file
 Output the tile data in native 2bpp format or in 1bpp
 .Pq depending on Fl d
 to this file.
-.It Fl p Ar pal_file , Fl Fl palette Ar pal_file
+.It Fl p Ar pal_file , Fl \-palette Ar pal_file
 Output the image's palette set to this file.
-.It Fl P , Fl Fl output-palette
+.It Fl P , Fl \-auto-palette
 Same as
-.Fl p Ar path ,
+.Fl p Ar base_path Ns .pal
-where
+.Pq see Sx Automatic output paths .
-.Ar path
+.It Fl q Ar pal_file , Fl \-palette-map Ar pal_file
-is the input image's path with the extension set to
-.Pa .pal .
-.It Fl q Ar pal_file , Fl Fl palette-map Ar pal_file
 Output the image's palette map to this file.
 This is useful if the input image contains more than 8 palettes, as the attribute map only contains the lower 3 bits of the palette indices.
-.It Fl Q , Fl Fl output-palette-map
+.It Fl Q , Fl \-auto-palette-map
 Same as
-.Fl q Ar path ,
+.Fl q Ar base_path Ns .palmap
-where
+.Pq see Sx Automatic output paths .
-.Ar path
+.It Fl r Ar width , Fl \-reverse Ar width
-is the input image's path with the extension set to
-.Pa .palmap .
-.It Fl r Ar width , Fl Fl reverse Ar width
 Switches
 .Nm
 into
@@ -229,15 +242,14 @@ See
 below for details.
 .Pp
 .Ar width
-is the image's width, in tiles
+is the width of the image to generate, in tiles.
-.Pq including any margins specified by Fl L .
+.It Fl s Ar nb_colors , Fl \-palette-size Ar nb_colors
-.It Fl s Ar nb_colors , Fl Fl palette-size Ar nb_colors
 Specify how many colors each palette contains, including the transparent one if any.
 .Ar nb_colors
 cannot be more than
 .Ql 1 << Ar depth
 .Pq see Fl d .
-.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap
+.It Fl t Ar tilemap , Fl \-tilemap Ar tilemap
 Generate a file of tile indices.
 For each square of the input image, its corresponding tile map byte contains the index of the associated tile in the tile data file.
 The IDs wrap around from 255 back to 0, and do not include the bank bit; use
@@ -248,15 +260,13 @@ Useful in combination with
 and/or
 .Fl m
 to keep track of duplicate tiles.
-.It Fl T , Fl Fl output-tilemap
+.It Fl T , Fl \-auto-tilemap
 Same as
-.Fl t Ar path ,
+.Fl t Ar base_path Ns .tilemap
-where
+.Pq see Sx Automatic output paths .
-.Ar path
+.It Fl u , Fl \-unique-tiles
-is the input image's path with the extension set to
+Deduplicate identical tiles.
-.Pa .tilemap .
+Only one of each unique tile will be saved in the tile data file.
-.It Fl u , Fl Fl unique-tiles
-Deduplicate identical tiles, and omit the duplicates from the tile data file.
 Useful with a tile map
 .Pq see Fl t
 to keep track of the duplicated tiles.
@@ -266,12 +276,12 @@ Note that if this option is enabled, no guarantee is made on the order in which
 be consistent across identical runs of a given
 .Nm
 release, the same is not true for different releases.
-.It Fl V , Fl Fl version
+.It Fl V , Fl \-version
 Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
+.It Fl v , Fl \-verbose
 Be verbose.
 The verbosity level is increased by one each time the flag is specified, with each level including the previous:
-.Bl -enum -width 2n -compact
+.Bl -enum -compact
 .It
 .Nm
 prints out its configuration before doing anything.
@@ -285,7 +295,7 @@ Some internal debug printing is enabled.
 The verbosity level does not go past 6.
 .Pp
 Note that verbose output is only intended to be consumed by humans, and may change without notice between RGBDS releases; relying on those for scripts is not advised.
-.It Fl x Ar quantity , Fl Fl trim-end Ar quantity
+.It Fl x Ar quantity , Fl \-trim-end Ar quantity
 Do not output the last
 .Ar quantity
 tiles to the tile data file; no other output is affected.
@@ -305,7 +315,7 @@ was enabled, so you probably don't want to use this option in combination with
 Note also that the tiles that don't get output will not count towards
 .Fl N Ap s
 limit.
-.It Fl Z , Fl Fl columns
+.It Fl Z , Fl \-columns
 Read squares from the PNG in column-major order (column by column), instead of the default row-major order (line by line).
 This primarily affects tile map and attribute map output, although it may also change generated tile data and palettes.
 .El
@@ -321,7 +331,22 @@ any command-line argument that begins with an at sign
 .Pq Ql @
 is interpreted as one.
 The rest of the argument (without the @, that is) is interpreted as the path to a file, whose contents are interpreted as if given on the command line.
-At-files can be stored right next to the corresponding image, for example.
+At-files can be stored right next to the corresponding image, for example:
+.Pp
+.Dl $ rgbgfx -o image.2bpp -t image.tilemap @image.flags image.png
+.Pp
+This will read additional flags from file
+.Ql image.flags ,
+which could contains for example
+.Ql -b 128
+to specify a base offset for the image's tiles.
+The above command could be generated from the following
+.Xr make 1
+rule, for example:
+.Bd -literal -offset indent
+%.2bpp %.tilemap: %.flags %.png
+	rgbgfx -o $*.2bpp -t $*.tilemap @$*.flags $*.png
+.Ed
 .Pp
 Since the contents of at-files are interpreted by
 .Nm ,
@@ -336,17 +361,19 @@ optionally preceded by whitespace, are considered comments and also ignored.
 Each line can contain any number of arguments, which are separated by whitespace.
 .Pq \&No quoting feature to prevent this is provided.
 .Pp
-Note that this special meaning given to arguments has less precedence than option arguments, and that the standard
+Note that a leading
+.Ql @
+has no special meaning on option arguments, and that the standard
 .Ql --
 to stop option processing also disables at-file processing.
-For example, the following command line processes
+For example, the following command line reads command-line options from
-.Ql @tilesets/town.png ,
-outputs tile data to
-.Ql @tilesets/town.2bpp ,
-and reads command-line options from
 .Ql tilesets/town.flags
 then
-.Ql tilesets.flags :
+.Ql tilesets.flags ,
+but processes
+.Ql @tilesets/town.png
+as the input image and outputs tile data to
+.Ql @tilesets/town.2bpp :
 .Pp
 .Dl $ rgbgfx -o @tilesets/town.2bpp @tilesets/town.flags @tilesets.flags -- @tilesets/town.png
 .Pp
@@ -357,11 +384,21 @@ can be used in an at-file (with identical semantics), it is only effective insid
 .Sh PALETTE SPECIFICATION FORMATS
 The following formats are supported:
 .Bl -tag -width Ds
-.It Sy act
+.It Cm act
 .Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1070626 Adobe Photoshop color table .
-.It Sy aco
+.It Cm aco
 .Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1055819 Adobe Photoshop color swatch .
-.It Sy psp
+.It Cm gbc
+A GBC palette memory dump, as emitted by
+.Nm Fl p .
+Useful to force several images to share the same palette.
+.It Cm gpl
+.Lk https://docs.gimp.org/2.10/en/gimp-concepts-palettes.html GIMP palette .
+.It Cm hex
+Plaintext lines of hexadecimal colors in
+.Ql rrggbb
+format.
+.It Cm psp
 .Lk https://www.selapa.net/swatches/colors/fileformats.php#psp_pal Paint Shop Pro palette .
 .El
 .Pp
@@ -447,7 +484,7 @@ What follows is succinct descriptions of those formats, including
 .Nm Ns -specific
 details.
 For more complete, beginner-friendly descriptions of the native formats with illustrations, please check out
-.Lk https://gbdev.io/pandocs/Rendering Pan Docs .
+.Lk https://gbdev.io/pandocs/Graphics Pan Docs .
 .Ss Tile data
 Tile data is output like a binary dump of VRAM, with no padding between tiles.
 Each tile is 16 bytes, 2 per row of 8 pixels; the bits of color IDs are split into each byte
@@ -492,6 +529,29 @@ The contents of individual bytes follows the GBC's native format:
 .El
 .Pp
 Note that if more than 8 palettes are used, only the lowest 3 bits of the palette ID are output.
+.Ss Automatic output paths
+For convenience,
+.Nm
+provides shortcuts to generate all files in the same directory.
+This is done by using the uppercase version of a flag
+.Pq for example, Fl A No instead of Fl a .
+The
+.Ar base_path
+is the input image path
+.Pq or the output tile data path from Fl o , No if Fl O No was given
+with its extension, if any, removed.
+.Pp
+For example, these two commands are equivalent:
+.Bd -literal -offset indent
+$ rgbgfx img/player.png -o build/player.2bpp -P
+$ rgbgfx img/player.png -o build/player.2bpp -p img/player.pal
+.Ed
+.Pp
+And so are these two:
+.Bd -literal -offset indent
+$ rgbgfx img/player.png -o build/player.2bpp -O -P
+$ rgbgfx img/player.png -o build/player.2bpp -p build/player.pal
+.Ed
 .Sh REVERSE MODE
 .Nm
 can produce a PNG image from valid data.
@@ -554,37 +614,53 @@ It is possible to compute the optimal solution externally (using a solver, for e
 via
 .Fl c .
 .Sh EXAMPLES
-The following will only validate the PNG (check its size, that all tiles have a suitable amount of colors, etc.), but output nothing:
+The following will only validate the
+.Ql tileset.png
+image (check its size, that all tiles have a suitable amount of colors, etc.), but output nothing:
 .Pp
 .Dl $ rgbgfx src/res/maps/overworld/tileset.png
 .Pp
-The following will convert the image using the two given palettes (and only those), and store the generated 2bpp tile data in
+The following will convert the
+.Ql tileset.png
+image using the two given palettes (and only those), and store the generated 2bpp tile data in
 .Ql tileset.2bpp ,
 and the attribute map in
 .Ql tileset.attrmap .
 .Pp
 .Dl $ rgbgfx -c '#ffffff,#8d05de, #dc7905,#000000 ; #fff,#8d05de, #7e0000 \&, #000' -A -o tileset.2bpp tileset.png
 .Pp
+The following will deduplicate the tiles in the
+.Ql title_screen.png
+image, keeping only one of each unique tile, and store the generated 2bpp tile data in
+.Ql title_screen.2bpp ,
+and the tile map in
+.Ql title_screen.tilemap .
+.Pp
+.Dl $ rgbgfx -u title_screen.png -o title_screen.2bpp -t title_screen.tilemap
+.Pp
+The following will convert the given inline palette specification to a palette set, and store the palette set in
+.Ql colors.pal ,
+without needing an input image.
+.Pp
+.Dl $ rgbgfx -c '#fff,#ff0,#f80,#000' -p colors.pal
+.Pp
 TODO: more examples.
 .Sh BUGS
 Please report bugs and mistakes in this man page on
 .Lk https://github.com/gbdev/rgbds/issues GitHub .
 Bug reports and feature requests about RGBDS are also welcome!
 .Sh SEE ALSO
-.Xr rgbds 7 ,
 .Xr rgbasm 1 ,
 .Xr rgblink 1 ,
 .Xr rgbfix 1 ,
-.Xr gbz80 7
+.Xr rgbds 7
 .Pp
 The Game Boy hardware reference
-.Lk https://gbdev.io/pandocs/Rendering.html Pan Docs ,
+.Lk https://gbdev.io/pandocs/Graphics Pan Docs ,
 particularly the section about graphics.
 .Sh HISTORY
 .Nm
-was originally created by
+was originally written by stag019 as a program to be packaged in RGBDS.
-.An stag019
-to be included in RGBDS.
 It was later rewritten by
 .An ISSOtm ,
 and is now maintained by a number of contributors at

man/rgblink.1

@@ -1,11 +1,6 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBLINK 1
 .Os
 .Sh NAME
@@ -29,7 +24,7 @@ The
 program links RGB object files, typically created by
 .Xr rgbasm 1 ,
 into a single Game Boy ROM file.
-The format is documented in
+The object file format is documented in
 .Xr rgbds 5 .
 .Pp
 ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB
@@ -52,47 +47,58 @@ option, which implies
 .Fl w
 but also prohibits the use of banked VRAM.
 .Pp
+The input
+.Ar asmfile
+can be a path to a file, or
+.Cm \-
+to read from standard input.
+.Pp
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
+.Fl \-verb
 is
-.Fl Fl verbose ,
+.Fl \-verbose ,
 but
-.Fl Fl ver
+.Fl \-ver
 is invalid because it could also be
-.Fl Fl version .
+.Fl \-version .
 The arguments are as follows:
 .Bl -tag -width Ds
-.It Fl d , Fl Fl dmg
+.It Fl d , Fl \-dmg
 Enable DMG mode.
 Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1.
 This option automatically enables
 .Fl w .
-.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script
+.It Fl l Ar linker_script , Fl \-linkerscript Ar linker_script
 Specify a linker script file that tells the linker how sections must be placed in the ROM.
 The attributes assigned in the linker script must be consistent with any assigned in the code.
 See
 .Xr rgblink 5
 for more information about the linker script format.
-.It Fl M , Fl Fl no-sym-in-map
+.It Fl M , Fl \-no-sym-in-map
 If specified, the map file will not list symbols, only sections.
-.It Fl m Ar map_file , Fl Fl map Ar map_file
+.It Fl m Ar map_file , Fl \-map Ar map_file
 Write a map file to the given filename, listing how sections and symbols were assigned.
-.It Fl n Ar sym_file , Fl Fl sym Ar sym_file
+.It Fl n Ar sym_file , Fl \-sym Ar sym_file
 Write a symbol file to the given filename, listing the address of all exported symbols.
 Several external programs can use this information, for example to help debugging ROMs.
-.It Fl O Ar overlay_file , Fl Fl overlay Ar overlay_file
+.It Fl O Ar overlay_file , Fl \-overlay Ar overlay_file
-If specified, sections will be overlaid "on top" of the provided ROM image.
+If specified, sections will be overlaid "on top" of the ROM image
-In that case, all sections must be fixed.
+.Ar overlay_file :
-This may be used to patch an existing binary.
+empty space between sections will be filled by the corresponding bytes from
-.It Fl o Ar out_file , Fl Fl output Ar out_file
+.Ar overlay_file .
+This is useful to patch an existing ROM.
+Note that all sections must be fixed (forced bank
+.Sy and
+address)!
+.It Fl o Ar out_file , Fl \-output Ar out_file
 Write the ROM image to the given file.
-.It Fl p Ar pad_value , Fl Fl pad Ar pad_value
+.It Fl p Ar pad_value , Fl \-pad Ar pad_value
 When inserting padding between sections, pad with this value.
 Has no effect if
 .Fl O
 is specified.
 The default is 0.
-.It Fl S Ar spec , Fl Fl scramble Ar spec
+.It Fl S Ar spec , Fl \-scramble Ar spec
 Enables a different
 .Dq scrambling
 algorithm for placing sections.
@@ -100,22 +106,22 @@ See
 .Sx Scrambling algorithm
 below for an explanation and a description of
 .Ar spec .
-.It Fl s Ar symbol , Fl Fl smart Ar symbol
+.It Fl s Ar symbol , Fl \-smart Ar symbol
 This option is ignored.
 It was supposed to perform smart linking but fell into disrepair, and so has been removed.
 It will be reimplemented at some point.
-.It Fl t , Fl Fl tiny
+.It Fl t , Fl \-tiny
 Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM.
 ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0.
 Useful for ROMs that fit in 32 KiB.
-.It Fl V , Fl Fl version
+.It Fl V , Fl \-version
 Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
+.It Fl v , Fl \-verbose
 Verbose: enable printing more information to standard error.
-.It Fl w , Fl Fl wramx
+.It Fl w , Fl \-wramx
 Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM.
 WRAMX sections that are fixed to a bank other than 1 become errors, other WRAMX sections are treated as WRAM0.
-.It Fl x , Fl Fl nopad
+.It Fl x , Fl \-nopad
 Disables padding the end of the final file.
 This option automatically enables
 .Fl t .
@@ -198,10 +204,15 @@ Please report bugs on
 .Xr rgbasm 1 ,
 .Xr rgblink 5 ,
 .Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
 .Xr rgbds 5 ,
 .Xr rgbds 7
 .Sh HISTORY
 .Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
+was originally written by
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

man/rgblink.5

@@ -1,107 +1,175 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 28, 2021
+.Dd December 22, 2023
 .Dt RGBLINK 5
 .Os
 .Sh NAME
 .Nm rgblink
 .Nd linker script file format
 .Sh DESCRIPTION
-The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
+The linker script is a file that allows specifying attributes for sections at link time, and in a centralized manner.
+There can only be one linker script per invocation of
+.Nm ,
+but it can be split into several files
+.Pq using the Ic INCLUDE No directive .
+.Ss Basic syntax
+The linker script syntax is line-based.
+Each line may have a directive or section name, a comment, both, or neither.
+Whitespace (space and tab characters) is used to separate syntax elements, but is otherwise ignored.
 .Pp
-A linker script consists of a series of bank declarations, each optionally followed by a list of section names (in double quotes) or commands.
+Comments begin with a semicolon
-All reserved keywords (bank types and command names) are case-insensitive; all section names are case-sensitive.
-.Pp
-Any line can contain a comment starting with
 .Ql \&;
-that ends at the end of the line.
+character, until the end of the line.
+They are simply ignored.
 .Pp
-.Bd -literal -offset indent
+Keywords are composed of letters and digits (but they can't start with a digit); they are all case-insensitive.
-; This line is a comment
-ROMX $F            ; start a bank
-  "Some functions" ; a section name
-  ALIGN 8          ; a command
-  "Some array"
-
-WRAMX 2            ; start another bank
-  org $d123        ; another command
-  "Some variables"
-.Ed
 .Pp
-Numbers can be in decimal or hexadecimal format
+Numbers can be written in decimal format, or in binary using the
-.Pq the prefix is Ql $ .
+.Ql %
-It is an error if any section name or command is found before setting a bank.
+prefix, or in hexadecimal using the
-.Pp
+.Ql $
-Files can be included by using the
+prefix (hexadecimal digits are case-insensitive).
-.Ic INCLUDE
+Note that unlike
-keyword, followed by a string with the path of the file that has to be included.
-.Pp
-The possible bank types are:
-.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
-and
-.Cm HRAM .
-Unless there is a single bank, which can occur with types
-.Cm ROMX , VRAM , SRAM
-and
-.Cm WRAMX ,
-it is needed to specify a bank number after the type.
-.Pp
-Section names in double quotes support the same character escape sequences as strings in
 .Xr rgbasm 5 ,
-specifically
+an octal
-.Ql \[rs]\[rs] ,
+.Ql &
-.Ql \[rs]" ,
+prefix is not supported, nor are
-.Ql \[rs]n ,
+.Ql _
-.Ql \[rs]r ,
+digit separators.
+.Pp
+Strings begin with a double quote, and end at the next (non-escaped) double quote.
+Strings must not contain literal newline characters.
+Most of the same character escapes as
+.Xr rgbasm 5
+are supported, specifically
+.Ql \e\e ,
+.Ql \e" ,
+.Ql \en ,
+.Ql \er ,
 and
-.Ql \[rs]t .
+.Ql \et .
 Other backslash escape sequences in
 .Xr rgbasm 5
-are only relevant to assembly code and do not apply in section names.
+are only relevant to assembly code and do not apply in linker scripts.
-.Pp
+.Ss Directives
-When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
+.Bl -tag -width Ds
-If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
+.It Including other files
-.Pp
+.Ql Ic INCLUDE Ar path
-The only two commands are
+acts as if the contents of the file at
-.Ic ORG
+.Ar path
+were copy-pasted in place of the
+.Ic INCLUDE
+directive.
+.Ar path
+must be a string.
+.It Specifying the active bank
+The active bank can be set by specifying its type (memory region) and number.
+The possible types are:
+.Ic ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM ,
 and
-.Ic ALIGN :
+.Ic HRAM .
-.Bl -bullet
+The bank number can be omitted from the types that only contain a single bank, which are:
-.It
+.Ic ROM0 ,
-.Ic ORG
+.Ic ROMX No if Fl t No is passed to Xr rgblink 1 ,
-sets the address in which new sections will be placed.
+.Ic VRAM No if Fl d No is passed to Xr rgblink 1 ,
-It can not be lower than the current address.
+.Ic WRAM0 ,
-.It
+.Ic WRAMX No if Fl w No is passed to Xr rgblink 1 ,
-.Ic ALIGN
+.Ic OAM ,
-will increase the address until it is aligned to the specified boundary
+and
-.Po it tries to set to 0 the number of bits specified after the command:
+.Ic HRAM .
-.Ql ALIGN 8
+.Pq Ic SRAM No is the only type that can never have its bank number omitted.
-will align to $100
-.Pc .
-.El
 .Pp
-.Sy Note:
+After a bank specification, the
-The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
+.Dq current address
-For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
+is set to the last value it had for that bank.
-For example,
+If the bank has never been active thus far, the
-.Ql ALIGN[8]
+.Dq current address
-in the source code is compatible with
+defaults to the beginning of the bank
-.Ql ORG $F00
+.Pq e.g. Ad $4000 No for Ic ROMX No sections .
-in the linker script.
+.It Changing the current address
+A bank must be active for any of these directives to be used.
+.Pp
+.Ql Ic ORG Ar addr
+sets the
+.Dq current address
+to
+.Ar addr .
+This directive cannot be used to move the address backwards:
+.Ar addr
+must be greater than or equal to the
+.Dq current address .
+.Pp
+.Ql Ic FLOATING
+causes all sections between it and the next
+.Ic ORG
+or bank specification to be placed at addresses automatically determined by
+.Nm .
+.Pp
+.Ql Ic ALIGN Ar addr , Ar offset
+increases the
+.Dq current address
+until it is aligned to the specified boundary (i.e. the
+.Ar align
+lowest bits of the address are equal to
+.Ar offset ) .
+If
+.Ar offset
+is omitted, it is implied to be 0.
+For example, if the
+.Dq current address
+is $0007,
+.Ql ALIGN 8
+would set it to $0100, and
+.Ql ALIGN 8 , 10
+would set it to $000A.
+.Pp
+.Ql Ic DS Ar size
+increases the
+.Dq current address
+by
+.Ar size .
+The gap is not allocated, so smaller floating sections can later be placed there.
+.El
+.Ss Section placement
+A section can be placed simply by naming it (with a string).
+Its bank is set to the active bank, and its address to the
+.Dq current address .
+Any constraints the section already possesses (whether from earlier in the linker script, or from the object files being linked) must be consistent with what the linker script specifies: the section's type must match, the section's bank number (if set) must match the active bank, etc.
+In particular, if the section has an alignment constraint, the address at which it is placed by the linker script must obey that constraint; otherwise, an error will occur.
+.Pp
+After a section is placed, the
+.Dq current address
+is increased by the section's size.
+This must not increase it past the end of the active memory region.
+.Pp
+The section must have been defined in the object files being linked, unless the section name is followed by the keyword
+.Ic OPTIONAL .
+.Sh EXAMPLES
+.Bd -literal -offset indent
+; This line contains only a comment
+ROMX $F            ; start a bank
+  "Some functions" ; a section name
+  ALIGN 8          ; a directive
+  "Some \e"array\e""
+
+WRAMX 2            ; start another bank
+  org $d123        ; another directive
+  "Some variables"
+.Ed
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
+.Xr rgbasm 5 ,
 .Xr rgblink 1 ,
 .Xr rgbfix 1 ,
+.Xr rgbgfx 1 ,
+.Xr gbz80 7 ,
 .Xr rgbds 5 ,
 .Xr rgbds 7
 .Sh HISTORY
-.Nm
+.Xr rgblink 1
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
+was originally written by
-and was later packaged in RGBDS by Justin Lloyd.
+.An Carsten S\(/orensen
+as part of the ASMotor package, and was later repackaged in RGBDS by
+.An Justin Lloyd .
 It is now maintained by a number of contributors at
 .Lk https://github.com/gbdev/rgbds .

src/.gitignore

@@ -1,2 +1,2 @@
 # Generated by CMake
-/.version.c
+/.version.cpp

src/CMakeLists.txt

@@ -1,64 +1,63 @@
-#
-# This file is part of RGBDS.
-#
-# Copyright (c) 2020 RGBDS contributors.
-#
 # SPDX-License-Identifier: MIT
-#
 
-configure_file(version.c _version.c ESCAPE_QUOTES)
+configure_file(version.cpp _version.cpp ESCAPE_QUOTES)
 
 set(common_src
-    "error.c"
+    "error.cpp"
-    "extern/getopt.c"
+    "extern/getopt.cpp"
-    "_version.c"
+    "_version.cpp"
     )
 
-find_package(BISON REQUIRED)
+find_package(BISON 3.0.0 REQUIRED)
 set(BISON_FLAGS "-Wall")
-# Set sompe optimization flags on versions that support them
+# Set some optimization flags on versions that support them
 if(BISON_VERSION VERSION_GREATER_EQUAL "3.5")
   set(BISON_FLAGS "${BISON_FLAGS} -Dapi.token.raw=true")
 endif()
 if(BISON_VERSION VERSION_GREATER_EQUAL "3.6")
   set(BISON_FLAGS "${BISON_FLAGS} -Dparse.error=detailed")
-elseif(BISON_VERSION VERSION_GREATER_EQUAL "3.0")
+else()
   set(BISON_FLAGS "${BISON_FLAGS} -Dparse.error=verbose")
 endif()
-if(BISON_VERSION VERSION_GREATER_EQUAL "3.0")
+set(BISON_FLAGS "${BISON_FLAGS} -Dparse.lac=full")
-  set(BISON_FLAGS "${BISON_FLAGS} -Dparse.lac=full")
+set(BISON_FLAGS "${BISON_FLAGS} -Dlr.type=ielr")
-  set(BISON_FLAGS "${BISON_FLAGS} -Dlr.type=ielr")
+
-endif()
+BISON_TARGET(ASM_PARSER "asm/parser.y"
-BISON_TARGET(PARSER "asm/parser.y"
+             "${PROJECT_SOURCE_DIR}/src/asm/parser.cpp"
-             "${PROJECT_SOURCE_DIR}/src/asm/parser.c"
              COMPILE_FLAGS "${BISON_FLAGS}"
-             DEFINES_FILE "${PROJECT_SOURCE_DIR}/src/asm/parser.h"
+             DEFINES_FILE "${PROJECT_SOURCE_DIR}/src/asm/parser.hpp"
+             )
+
+BISON_TARGET(LINKER_SCRIPT_PARSER "link/script.y"
+             "${PROJECT_SOURCE_DIR}/src/link/script.cpp"
+             COMPILE_FLAGS "${BISON_FLAGS}"
+             DEFINES_FILE "${PROJECT_SOURCE_DIR}/src/link/script.hpp"
              )
 
 set(rgbasm_src
-    "${BISON_PARSER_OUTPUT_SOURCE}"
+    "${BISON_ASM_PARSER_OUTPUT_SOURCE}"
-    "asm/charmap.c"
+    "asm/charmap.cpp"
-    "asm/fixpoint.c"
+    "asm/fixpoint.cpp"
-    "asm/format.c"
+    "asm/format.cpp"
-    "asm/fstack.c"
+    "asm/fstack.cpp"
-    "asm/lexer.c"
+    "asm/lexer.cpp"
-    "asm/macro.c"
+    "asm/macro.cpp"
-    "asm/main.c"
+    "asm/main.cpp"
-    "asm/opt.c"
+    "asm/opt.cpp"
-    "asm/output.c"
+    "asm/output.cpp"
-    "asm/rpn.c"
+    "asm/rpn.cpp"
-    "asm/section.c"
+    "asm/section.cpp"
-    "asm/symbol.c"
+    "asm/symbol.cpp"
-    "asm/util.c"
+    "asm/warning.cpp"
-    "asm/warning.c"
+    "extern/utf8decoder.cpp"
-    "extern/utf8decoder.c"
+    "hashmap.cpp"
-    "hashmap.c"
+    "linkdefs.cpp"
-    "linkdefs.c"
+    "opmath.cpp"
-    "opmath.c"
+    "util.cpp"
     )
 
 set(rgbfix_src
-    "fix/main.c"
+    "fix/main.cpp"
     )
 
 set(rgbgfx_src
@@ -70,23 +69,25 @@ set(rgbgfx_src
     "gfx/proto_palette.cpp"
     "gfx/reverse.cpp"
     "gfx/rgba.cpp"
-    "extern/getopt.c"
+    "extern/getopt.cpp"
-    "error.c"
+    "error.cpp"
     )
 
 set(rgblink_src
-    "link/assign.c"
+    "${BISON_LINKER_SCRIPT_PARSER_OUTPUT_SOURCE}"
-    "link/main.c"
+    "link/assign.cpp"
-    "link/object.c"
+    "link/main.cpp"
-    "link/output.c"
+    "link/object.cpp"
-    "link/patch.c"
+    "link/output.cpp"
-    "link/script.c"
+    "link/patch.cpp"
-    "link/sdas_obj.c"
+    "link/sdas_obj.cpp"
-    "link/section.c"
+    "link/section.cpp"
-    "link/symbol.c"
+    "link/symbol.cpp"
-    "hashmap.c"
+    "extern/utf8decoder.cpp"
-    "linkdefs.c"
+    "hashmap.cpp"
-    "opmath.c"
+    "linkdefs.cpp"
+    "opmath.cpp"
+    "util.cpp"
     )
 
 foreach(PROG "asm" "fix" "gfx" "link")

src/asm/.gitignore

@@ -1,2 +1,2 @@
-/parser.c
+/parser.cpp
-/parser.h
+/parser.hpp

src/asm/charmap.cpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #include <errno.h>
 #include <stdbool.h>
@@ -13,13 +7,13 @@
 #include <stdio.h>
 #include <string.h>
 
-#include "asm/charmap.h"
+#include "asm/charmap.hpp"
-#include "asm/main.h"
+#include "asm/main.hpp"
-#include "asm/output.h"
+#include "asm/output.hpp"
-#include "asm/util.h"
+#include "asm/warning.hpp"
-#include "asm/warning.h"
 
-#include "hashmap.h"
+#include "hashmap.hpp"
+#include "util.hpp"
 
 // Charmaps are stored using a structure known as "trie".
 // Essentially a tree, where each nodes stores a single character's worth of info:
@@ -27,7 +21,7 @@
 struct Charnode {
 	bool isTerminal; // Whether there exists a mapping that ends here
 	uint8_t value; // If the above is true, its corresponding value
-	// This MUST be indexes and not pointers, because pointers get invalidated by `realloc`!!
+	// This MUST be indexes and not pointers, because pointers get invalidated by `realloc`!
 	size_t next[255]; // Indexes of where to go next, 0 = nowhere
 };
 
@@ -55,12 +49,12 @@ struct CharmapStackEntry *charmapStack;
 
 static struct Charmap *charmap_Get(char const *name)
 {
-	return hash_GetElement(charmaps, name);
+	return (struct Charmap *)hash_GetElement(charmaps, name);
 }
 
 static void resizeCharmap(struct Charmap **map, size_t capacity)
 {
-	*map = realloc(*map, sizeof(**map) + sizeof(*(*map)->nodes) * capacity);
+	*map = (struct Charmap *)realloc(*map, sizeof(**map) + sizeof(*(*map)->nodes) * capacity);
 
 	if (!*map)
 		fatalerror("Failed to %s charmap: %s\n",
@@ -110,12 +104,6 @@ struct Charmap *charmap_New(char const *name, char const *baseName)
 	return charmap;
 }
 
-void charmap_Delete(struct Charmap *charmap)
-{
-	free(charmap->name);
-	free(charmap);
-}
-
 void charmap_Set(char const *name)
 {
 	struct Charmap **charmap = (struct Charmap **)hash_GetNode(charmaps, name);
@@ -128,9 +116,8 @@ void charmap_Set(char const *name)
 
 void charmap_Push(void)
 {
-	struct CharmapStackEntry *stackEntry;
+	struct CharmapStackEntry *stackEntry = (struct CharmapStackEntry *)malloc(sizeof(*stackEntry));
 
-	stackEntry = malloc(sizeof(*stackEntry));
 	if (stackEntry == NULL)
 		fatalerror("Failed to alloc charmap stack entry: %s\n", strerror(errno));
 
@@ -187,6 +174,22 @@ void charmap_Add(char *mapping, uint8_t value)
 	node->value = value;
 }
 
+bool charmap_HasChar(char const *input)
+{
+	struct Charmap const *charmap = *currentCharmap;
+	struct Charnode const *node = &charmap->nodes[0];
+
+	for (; *input; input++) {
+		size_t next = node->next[*input - 1];
+
+		if (!next)
+			return false;
+		node = &charmap->nodes[next];
+	}
+
+	return node->isTerminal;
+}
+
 size_t charmap_Convert(char const *input, uint8_t *output)
 {
 	uint8_t *start = output;
@@ -242,18 +245,21 @@ size_t charmap_ConvertNext(char const **input, uint8_t **output)
 								   *input);
 
 				if (codepointLen == 0)
-					error("Input string is not valid UTF-8!\n");
+					error("Input string is not valid UTF-8\n");
 
 				// OK because UTF-8 has no NUL in multi-byte chars
 				*input += codepointLen;
 				if (output)
 					*output += codepointLen;
 
-				// Check if the character map is not the default "main" one, or if
+				// Warn if this character is not mapped but any others are
-				// it has any mappings defined
+				if (charmap->usedNodes > 1)
-				if (strcmp(charmap->name, "main") || charmap->usedNodes > 1)
+					warning(WARNING_UNMAPPED_CHAR_1,
-					warning(WARNING_UNMAPPED_CHAR,
 						"Unmapped character %s\n", printChar(firstChar));
+				else if (strcmp(charmap->name, DEFAULT_CHARMAP_NAME))
+					warning(WARNING_UNMAPPED_CHAR_2,
+						"Unmapped character %s not in " DEFAULT_CHARMAP_NAME
+						" charmap\n", printChar(firstChar));
 
 				return codepointLen;
 

src/asm/fixpoint.c

@@ -1,125 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2021, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-// Fixed-point math routines
-
-#include <inttypes.h>
-#include <math.h>
-#include <stdint.h>
-#include <stdio.h>
-
-#include "asm/fixpoint.h"
-#include "asm/symbol.h"
-#include "asm/warning.h"
-
-#ifndef M_PI
-#define M_PI 3.14159265358979323846
-#endif
-
-#define fix2double(i)	((double)((i) / fix_PrecisionFactor()))
-#define double2fix(d)	((int32_t)round((d) * fix_PrecisionFactor()))
-
-// pi*2 radians == 2**fixPrecision fixed-point "degrees"
-#define fdeg2rad(f)	((f) * (M_PI * 2) / fix_PrecisionFactor())
-#define rad2fdeg(r)	((r) * fix_PrecisionFactor() / (M_PI * 2))
-
-uint8_t fixPrecision;
-
-double fix_PrecisionFactor(void)
-{
-	return pow(2.0, fixPrecision);
-}
-
-void fix_Print(int32_t i)
-{
-	uint32_t u = i;
-	char const *sign = "";
-
-	if (i < 0) {
-		u = -u;
-		sign = "-";
-	}
-
-	printf("%s%" PRIu32 ".%05" PRIu32, sign, u >> fixPrecision,
-	       ((uint32_t)(fix2double(u) * 100000 + 0.5)) % 100000);
-}
-
-int32_t fix_Sin(int32_t i)
-{
-	return double2fix(sin(fdeg2rad(fix2double(i))));
-}
-
-int32_t fix_Cos(int32_t i)
-{
-	return double2fix(cos(fdeg2rad(fix2double(i))));
-}
-
-int32_t fix_Tan(int32_t i)
-{
-	return double2fix(tan(fdeg2rad(fix2double(i))));
-}
-
-int32_t fix_ASin(int32_t i)
-{
-	return double2fix(rad2fdeg(asin(fix2double(i))));
-}
-
-int32_t fix_ACos(int32_t i)
-{
-	return double2fix(rad2fdeg(acos(fix2double(i))));
-}
-
-int32_t fix_ATan(int32_t i)
-{
-	return double2fix(rad2fdeg(atan(fix2double(i))));
-}
-
-int32_t fix_ATan2(int32_t i, int32_t j)
-{
-	return double2fix(rad2fdeg(atan2(fix2double(i), fix2double(j))));
-}
-
-int32_t fix_Mul(int32_t i, int32_t j)
-{
-	return double2fix(fix2double(i) * fix2double(j));
-}
-
-int32_t fix_Div(int32_t i, int32_t j)
-{
-	return double2fix(fix2double(i) / fix2double(j));
-}
-
-int32_t fix_Mod(int32_t i, int32_t j)
-{
-	return double2fix(fmod(fix2double(i), fix2double(j)));
-}
-
-int32_t fix_Pow(int32_t i, int32_t j)
-{
-	return double2fix(pow(fix2double(i), fix2double(j)));
-}
-
-int32_t fix_Log(int32_t i, int32_t j)
-{
-	return double2fix(log(fix2double(i)) / log(fix2double(j)));
-}
-
-int32_t fix_Round(int32_t i)
-{
-	return double2fix(round(fix2double(i)));
-}
-
-int32_t fix_Ceil(int32_t i)
-{
-	return double2fix(ceil(fix2double(i)));
-}
-
-int32_t fix_Floor(int32_t i)
-{
-	return double2fix(floor(fix2double(i)));
-}

src/asm/fixpoint.cpp

@@ -0,0 +1,109 @@
+/* SPDX-License-Identifier: MIT */
+
+// Fixed-point math routines
+
+#include <inttypes.h>
+#include <math.h>
+#include <stdint.h>
+
+#include "asm/fixpoint.hpp"
+#include "asm/symbol.hpp"
+#include "asm/warning.hpp"
+
+#ifndef M_PI
+#define M_PI 3.14159265358979323846
+#endif
+
+#define fix2double(i, q)	((double)((i) / pow(2.0, q)))
+#define double2fix(d, q)	((int32_t)round((d) * pow(2.0, q)))
+
+// 2*pi radians == 1 turn
+#define turn2rad(f)	((f) * (M_PI * 2))
+#define rad2turn(r)	((r) / (M_PI * 2))
+
+uint8_t fixPrecision;
+
+uint8_t fix_Precision(void)
+{
+	return fixPrecision;
+}
+
+double fix_PrecisionFactor(void)
+{
+	return pow(2.0, fixPrecision);
+}
+
+int32_t fix_Sin(int32_t i, int32_t q)
+{
+	return double2fix(sin(turn2rad(fix2double(i, q))), q);
+}
+
+int32_t fix_Cos(int32_t i, int32_t q)
+{
+	return double2fix(cos(turn2rad(fix2double(i, q))), q);
+}
+
+int32_t fix_Tan(int32_t i, int32_t q)
+{
+	return double2fix(tan(turn2rad(fix2double(i, q))), q);
+}
+
+int32_t fix_ASin(int32_t i, int32_t q)
+{
+	return double2fix(rad2turn(asin(fix2double(i, q))), q);
+}
+
+int32_t fix_ACos(int32_t i, int32_t q)
+{
+	return double2fix(rad2turn(acos(fix2double(i, q))), q);
+}
+
+int32_t fix_ATan(int32_t i, int32_t q)
+{
+	return double2fix(rad2turn(atan(fix2double(i, q))), q);
+}
+
+int32_t fix_ATan2(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(rad2turn(atan2(fix2double(i, q), fix2double(j, q))), q);
+}
+
+int32_t fix_Mul(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(fix2double(i, q) * fix2double(j, q), q);
+}
+
+int32_t fix_Div(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(fix2double(i, q) / fix2double(j, q), q);
+}
+
+int32_t fix_Mod(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(fmod(fix2double(i, q), fix2double(j, q)), q);
+}
+
+int32_t fix_Pow(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(pow(fix2double(i, q), fix2double(j, q)), q);
+}
+
+int32_t fix_Log(int32_t i, int32_t j, int32_t q)
+{
+	return double2fix(log(fix2double(i, q)) / log(fix2double(j, q)), q);
+}
+
+int32_t fix_Round(int32_t i, int32_t q)
+{
+	return double2fix(round(fix2double(i, q)), q);
+}
+
+int32_t fix_Ceil(int32_t i, int32_t q)
+{
+	return double2fix(ceil(fix2double(i, q)), q);
+}
+
+int32_t fix_Floor(int32_t i, int32_t q)
+{
+	return double2fix(floor(fix2double(i, q)), q);
+}

src/asm/format.cpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020, RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #include <assert.h>
 #include <inttypes.h>
@@ -15,13 +9,13 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include "asm/fixpoint.h"
+#include "asm/fixpoint.hpp"
-#include "asm/format.h"
+#include "asm/format.hpp"
-#include "asm/warning.h"
+#include "asm/warning.hpp"
 
 struct FormatSpec fmt_NewSpec(void)
 {
-	struct FormatSpec fmt = {0};
+	struct FormatSpec fmt = {};
 
 	return fmt;
 }
@@ -249,7 +243,7 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 	}
 
 	size_t len = strlen(valueBuf);
-	size_t numLen = !!sign + !!prefix + len;
+	size_t numLen = (sign != 0) + (prefix != 0) + len;
 	size_t totalLen = fmt->width > numLen ? fmt->width : numLen;
 
 	if (totalLen > bufLen - 1) { // bufLen includes terminator

src/asm/fstack.cpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 1997-2018, Carsten Sorensen and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #include <sys/stat.h>
 #include <assert.h>
@@ -14,12 +8,13 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-#include "asm/fstack.h"
+#include "asm/fstack.hpp"
-#include "asm/macro.h"
+#include "asm/macro.hpp"
-#include "asm/main.h"
+#include "asm/main.hpp"
-#include "asm/symbol.h"
+#include "asm/symbol.hpp"
-#include "asm/warning.h"
+#include "asm/warning.hpp"
-#include "platform.h" // S_ISDIR (stat macro)
+#include "error.hpp"
+#include "platform.hpp" // S_ISDIR (stat macro)
 
 #define MAXINCPATHS 128
 
@@ -42,6 +37,8 @@ size_t maxRecursionDepth;
 static unsigned int nbIncPaths = 0;
 static char const *includePaths[MAXINCPATHS];
 
+static const char *preIncludeName;
+
 static const char *dumpNodeAndParents(struct FileStackNode const *node)
 {
 	char const *name;
@@ -117,7 +114,7 @@ void fstk_AddIncludePath(char const *path)
 	}
 	size_t len = strlen(path);
 	size_t allocSize = len + (path[len - 1] != '/') + 1;
-	char *str = malloc(allocSize);
+	char *str = (char *)malloc(allocSize);
 
 	if (!str) {
 		// Attempt to continue without that path
@@ -133,6 +130,15 @@ void fstk_AddIncludePath(char const *path)
 	includePaths[nbIncPaths++] = str;
 }
 
+void fstk_SetPreIncludeFile(char const *path)
+{
+	if (preIncludeName)
+		warnx("Overriding pre-included filename %s", preIncludeName);
+	preIncludeName = path;
+	if (verbose)
+		printf("Pre-included filename %s\n", preIncludeName);
+}
+
 static void printDep(char const *path)
 {
 	if (dependfile) {
@@ -157,7 +163,7 @@ bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 {
 	if (!*size) {
 		*size = 64; // This is arbitrary, really
-		*fullPath = realloc(*fullPath, *size);
+		*fullPath = (char *)realloc(*fullPath, *size);
 		if (!*fullPath)
 			error("realloc error during include path search: %s\n",
 			      strerror(errno));
@@ -177,7 +183,7 @@ bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 			// Oh how I wish `asnprintf` was standard...
 			if ((size_t)len >= *size) { // `size` includes the terminator, `len` doesn't
 				*size = len + 1;
-				*fullPath = realloc(*fullPath, *size);
+				*fullPath = (char *)realloc(*fullPath, *size);
 				if (!*fullPath) {
 					error("realloc error during include path search: %s\n",
 					      strerror(errno));
@@ -219,7 +225,7 @@ bool yywrap(void)
 		// If the node is referenced, we can't edit it; duplicate it
 		if (contextStack->fileInfo->referenced) {
 			size_t size = sizeof(*fileInfo) + sizeof(fileInfo->iters[0]) * fileInfo->reptDepth;
-			struct FileStackReptNode *copy = malloc(size);
+			struct FileStackReptNode *copy = (struct FileStackReptNode *)malloc(size);
 
 			if (!copy)
 				fatalerror("Failed to duplicate REPT file node: %s\n", strerror(errno));
@@ -234,7 +240,11 @@ bool yywrap(void)
 
 		// If this is a FOR, update the symbol value
 		if (contextStack->forName && fileInfo->iters[0] <= contextStack->nbReptIters) {
-			contextStack->forValue += contextStack->forStep;
+			// Avoid arithmetic overflow runtime error
+			uint32_t forValue = (uint32_t)contextStack->forValue +
+				(uint32_t)contextStack->forStep;
+			contextStack->forValue = forValue >= 0 ? (int32_t)forValue
+				: -(int32_t)~forValue - 1;
 			struct Symbol *sym = sym_AddVar(contextStack->forName,
 				contextStack->forValue);
 
@@ -262,8 +272,10 @@ bool yywrap(void)
 
 	lexer_DeleteState(context->lexerState);
 	// Restore args if a macro (not REPT) saved them
-	if (context->fileInfo->type == NODE_MACRO)
+	if (context->fileInfo->type == NODE_MACRO) {
+		macro_FreeArgs(macro_GetCurrentArgs());
 		macro_UseNewArgs(contextStack->macroArgs);
+	}
 	// Free the file stack node
 	if (!context->fileInfo->referenced)
 		free(context->fileInfo);
@@ -274,11 +286,12 @@ bool yywrap(void)
 
 	lexer_SetState(contextStack->lexerState);
 	macro_SetUniqueID(contextStack->uniqueID);
+
 	return false;
 }
 
 // Make sure not to switch the lexer state before calling this, so the saved line no is correct.
-// BE CAREFUL!! This modifies the file stack directly, you should have set up the file info first.
+// BE CAREFUL! This modifies the file stack directly, you should have set up the file info first.
 // Callers should set contextStack->lexerState after this so it is not NULL.
 static void newContext(struct FileStackNode *fileInfo)
 {
@@ -288,7 +301,7 @@ static void newContext(struct FileStackNode *fileInfo)
 	// Save the current `\@` value, to be restored when this context ends
 	contextStack->uniqueID = macro_GetUniqueID();
 
-	struct Context *context = malloc(sizeof(*context));
+	struct Context *context = (struct Context *)malloc(sizeof(*context));
 
 	if (!context)
 		fatalerror("Failed to allocate memory for new context: %s\n", strerror(errno));
@@ -300,7 +313,7 @@ static void newContext(struct FileStackNode *fileInfo)
 	context->forName = NULL;
 
 	// Link new entry to its parent so it's reachable later
-	// ERRORS SHOULD NOT OCCUR AFTER THIS!!
+	// ERRORS SHOULD NOT OCCUR AFTER THIS!
 	context->parent = contextStack;
 	contextStack = context;
 }
@@ -323,7 +336,8 @@ void fstk_RunInclude(char const *path)
 		return;
 	}
 
-	struct FileStackNamedNode *fileInfo = malloc(sizeof(*fileInfo) + size);
+	struct FileStackNamedNode *fileInfo =
+		(struct FileStackNamedNode *)malloc(sizeof(*fileInfo) + size);
 
 	if (!fileInfo) {
 		error("Failed to alloc file info for INCLUDE: %s\n", strerror(errno));
@@ -338,6 +352,44 @@ void fstk_RunInclude(char const *path)
 	if (!contextStack->lexerState)
 		fatalerror("Failed to set up lexer for file include\n");
 	lexer_SetStateAtEOL(contextStack->lexerState);
+	// We're back at top-level, so most things are reset,
+	// but not the unique ID, since INCLUDE may be inside a
+	// MACRO or REPT/FOR loop
+	contextStack->uniqueID = contextStack->parent->uniqueID;
+}
+
+// Similar to `fstk_RunInclude`, but not subject to `-MG`, and
+// calling `lexer_SetState` instead of `lexer_SetStateAtEOL`.
+static void runPreIncludeFile(void)
+{
+	if (!preIncludeName)
+		return;
+
+	char *fullPath = NULL;
+	size_t size = 0;
+
+	if (!fstk_FindFile(preIncludeName, &fullPath, &size)) {
+		free(fullPath);
+		error("Unable to open included file '%s': %s\n", preIncludeName, strerror(errno));
+		return;
+	}
+
+	struct FileStackNamedNode *fileInfo =
+		(struct FileStackNamedNode *)malloc(sizeof(*fileInfo) + size);
+
+	if (!fileInfo) {
+		error("Failed to alloc file info for pre-include: %s\n", strerror(errno));
+		return;
+	}
+	fileInfo->node.type = NODE_FILE;
+	strcpy(fileInfo->name, fullPath);
+	free(fullPath);
+
+	newContext((struct FileStackNode *)fileInfo);
+	contextStack->lexerState = lexer_OpenFile(fileInfo->name);
+	if (!contextStack->lexerState)
+		fatalerror("Failed to set up lexer for file include\n");
+	lexer_SetState(contextStack->lexerState);
 	// We're back at top-level, so most things are reset
 	contextStack->uniqueID = macro_UndefUniqueID();
 }
@@ -373,8 +425,8 @@ void fstk_RunMacro(char const *macroName, struct MacroArgs *args)
 	struct FileStackNamedNode const *baseNode = (struct FileStackNamedNode const *)node;
 	size_t baseLen = strlen(baseNode->name);
 	size_t macroNameLen = strlen(macro->name);
-	struct FileStackNamedNode *fileInfo = malloc(sizeof(*fileInfo) + baseLen
+	struct FileStackNamedNode *fileInfo = (struct FileStackNamedNode *)malloc(sizeof(*fileInfo) +
-						     + reptNameLen + 2 + macroNameLen + 1);
+			baseLen + reptNameLen + 2 + macroNameLen + 1);
 
 	if (!fileInfo) {
 		error("Failed to alloc file info for \"%s\": %s\n", macro->name, strerror(errno));
@@ -417,8 +469,8 @@ static bool newReptContext(int32_t reptLineNo, char *body, size_t size)
 	uint32_t reptDepth = contextStack->fileInfo->type == NODE_REPT
 				? ((struct FileStackReptNode *)contextStack->fileInfo)->reptDepth
 				: 0;
-	struct FileStackReptNode *fileInfo = malloc(sizeof(*fileInfo)
+	struct FileStackReptNode *fileInfo = (struct FileStackReptNode *)malloc(sizeof(*fileInfo)
-						    + (reptDepth + 1) * sizeof(fileInfo->iters[0]));
+			+ (reptDepth + 1) * sizeof(fileInfo->iters[0]));
 
 	if (!fileInfo) {
 		error("Failed to alloc file info for REPT: %s\n", strerror(errno));
@@ -467,9 +519,9 @@ void fstk_RunFor(char const *symName, int32_t start, int32_t stop, int32_t step,
 	uint32_t count = 0;
 
 	if (step > 0 && start < stop)
-		count = (stop - start - 1) / step + 1;
+		count = ((int64_t)stop - start - 1) / step + 1;
 	else if (step < 0 && stop < start)
-		count = (start - stop - 1) / -step + 1;
+		count = ((int64_t)start - stop - 1) / -(int64_t)step + 1;
 	else if (step == 0)
 		error("FOR cannot have a step value of 0\n");
 
@@ -519,12 +571,13 @@ void fstk_Init(char const *mainPath, size_t maxDepth)
 	struct LexerState *state = lexer_OpenFile(mainPath);
 
 	if (!state)
-		fatalerror("Failed to open main file!\n");
+		fatalerror("Failed to open main file\n");
 	lexer_SetState(state);
 	char const *fileName = lexer_GetFileName();
 	size_t len = strlen(fileName);
-	struct Context *context = malloc(sizeof(*contextStack));
+	struct Context *context = (struct Context *)malloc(sizeof(*contextStack));
-	struct FileStackNamedNode *fileInfo = malloc(sizeof(*fileInfo) + len + 1);
+	struct FileStackNamedNode *fileInfo =
+		(struct FileStackNamedNode *)malloc(sizeof(*fileInfo) + len + 1);
 
 	if (!context)
 		fatalerror("Failed to allocate memory for main context: %s\n", strerror(errno));
@@ -563,4 +616,6 @@ void fstk_Init(char const *mainPath, size_t maxDepth)
 	// Make sure that the default of 64 is OK, though
 	assert(DEPTH_LIMIT >= DEFAULT_MAX_DEPTH);
 #undef DEPTH_LIMIT
+
+	runPreIncludeFile();
 }

src/asm/lexer.cpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2020, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #include <sys/types.h>
 #include <sys/stat.h>
@@ -24,20 +18,20 @@
 #include <unistd.h>
 #endif
 
-#include "platform.h" // For `ssize_t`
+#include "platform.hpp" // For `ssize_t` and `AT`
+#include "util.hpp"
 
-#include "asm/lexer.h"
+#include "asm/lexer.hpp"
-#include "asm/fixpoint.h"
+#include "asm/fixpoint.hpp"
-#include "asm/format.h"
+#include "asm/format.hpp"
-#include "asm/fstack.h"
+#include "asm/fstack.hpp"
-#include "asm/macro.h"
+#include "asm/macro.hpp"
-#include "asm/main.h"
+#include "asm/main.hpp"
-#include "asm/rpn.h"
+#include "asm/rpn.hpp"
-#include "asm/symbol.h"
+#include "asm/symbol.hpp"
-#include "asm/util.h"
+#include "asm/warning.hpp"
-#include "asm/warning.h"
 // Include this last so it gets all type & constant definitions
-#include "parser.h" // For token definitions, generated from parser.y
+#include "parser.hpp" // For token definitions, generated from parser.y
 
 // Neither MSVC nor MinGW provide `mmap`
 #if defined(_MSC_VER) || defined(__MINGW32__)
@@ -206,6 +200,7 @@ static struct KeywordMapping {
 
 	{"CHARLEN", T_OP_CHARLEN},
 	{"CHARSUB", T_OP_CHARSUB},
+	{"INCHARMAP", T_OP_INCHARMAP},
 
 	{"INCLUDE", T_POP_INCLUDE},
 	{"PRINT", T_POP_PRINT},
@@ -216,6 +211,7 @@ static struct KeywordMapping {
 	{"DW", T_POP_DW},
 	{"DL", T_POP_DL},
 	{"SECTION", T_POP_SECTION},
+	{"ENDSECTION", T_POP_ENDSECTION},
 	{"PURGE", T_POP_PURGE},
 
 	{"RSRESET", T_POP_RSRESET},
@@ -394,7 +390,7 @@ uint32_t lexer_GetIFDepth(void)
 
 void lexer_IncIFDepth(void)
 {
-	struct IfStack *ifStack = malloc(sizeof(*ifStack));
+	struct IfStack *ifStack = (struct IfStack *)malloc(sizeof(*ifStack));
 
 	if (!ifStack)
 		fatalerror("Unable to allocate new IF depth: %s\n", strerror(errno));
@@ -441,7 +437,7 @@ void lexer_ReachELSEBlock(void)
 struct LexerState *lexer_OpenFile(char const *path)
 {
 	bool isStdin = !strcmp(path, "-");
-	struct LexerState *state = malloc(sizeof(*state));
+	struct LexerState *state = (struct LexerState *)malloc(sizeof(*state));
 	struct stat fileInfo;
 
 	// Give stdin a nicer file name
@@ -483,7 +479,7 @@ struct LexerState *lexer_OpenFile(char const *path)
 
 			state->isMmapped = true;
 			state->isReferenced = false; // By default, a state isn't referenced
-			state->ptr = mappingAddr;
+			state->ptr = (char *)mappingAddr;
 			assert(fileInfo.st_size >= 0);
 			state->size = (size_t)fileInfo.st_size;
 			state->offset = 0;
@@ -514,7 +510,7 @@ struct LexerState *lexer_OpenFile(char const *path)
 
 struct LexerState *lexer_OpenFileView(char const *path, char *buf, size_t size, uint32_t lineNo)
 {
-	struct LexerState *state = malloc(sizeof(*state));
+	struct LexerState *state = (struct LexerState *)malloc(sizeof(*state));
 
 	if (!state) {
 		error("Failed to allocate memory for lexer state: %s\n", strerror(errno));
@@ -571,7 +567,7 @@ struct KeywordDictNode {
 	uint16_t children[0x60 - ' '];
 	struct KeywordMapping const *keyword;
 // Since the keyword structure is invariant, the min number of nodes is known at compile time
-} keywordDict[365] = {0}; // Make sure to keep this correct when adding keywords!
+} keywordDict[377] = {}; // Make sure to keep this correct when adding keywords!
 
 // Convert a char into its index into the dict
 static uint8_t dictIndex(char c)
@@ -641,7 +637,7 @@ static void reallocCaptureBuf(void)
 		lexerState->captureCapacity = SIZE_MAX;
 	else
 		lexerState->captureCapacity *= 2;
-	lexerState->captureBuf = realloc(lexerState->captureBuf, lexerState->captureCapacity);
+	lexerState->captureBuf = (char *)realloc(lexerState->captureBuf, lexerState->captureCapacity);
 	if (!lexerState->captureBuf)
 		fatalerror("realloc error while resizing capture buffer: %s\n", strerror(errno));
 }
@@ -657,7 +653,7 @@ static void beginExpansion(char const *str, bool owned, char const *name)
 	if (name)
 		lexer_CheckRecursionDepth();
 
-	struct Expansion *exp = malloc(sizeof(*exp));
+	struct Expansion *exp = (struct Expansion *)malloc(sizeof(*exp));
 
 	if (!exp)
 		fatalerror("Unable to allocate new expansion: %s\n", strerror(errno));
@@ -733,7 +729,7 @@ static uint32_t readBracketedMacroArgNum(void)
 		}
 		symName[i] = '\0';
 
-		struct Symbol const *sym = sym_FindScopedSymbol(symName);
+		struct Symbol const *sym = sym_FindScopedValidSymbol(symName);
 
 		if (!sym) {
 			error("Bracketed symbol \"%s\" does not exist\n", symName);
@@ -1179,7 +1175,7 @@ static uint32_t readFractionalPart(uint32_t integer)
 		precision = fixPrecision;
 	}
 
-	if (integer >= ((uint32_t)1 << (precision - 1)))
+	if (integer >= ((uint64_t)1 << (32 - precision)))
 		warning(WARNING_LARGE_CONSTANT, "Magnitude of fixed-point constant is too large\n");
 
 	// Cast to unsigned avoids undefined overflow behavior
@@ -1400,7 +1396,7 @@ static char const *readInterpolation(size_t depth)
 
 	static char buf[MAXSTRLEN + 1];
 
-	struct Symbol const *sym = sym_FindScopedSymbol(symName);
+	struct Symbol const *sym = sym_FindScopedValidSymbol(symName);
 
 	if (!sym) {
 		error("Interpolated symbol \"%s\" does not exist\n", symName);
@@ -1463,7 +1459,7 @@ static size_t appendEscapedSubstring(char const *str, size_t i)
 	return i;
 }
 
-static void readString(void)
+static void readString(bool raw)
 {
 	lexerState->disableMacroArgs = true;
 	lexerState->disableInterpolation = true;
@@ -1521,6 +1517,8 @@ static void readString(void)
 			goto finish;
 
 		case '\\': // Character escape or macro arg
+			if (raw)
+				break;
 			c = peek();
 			switch (c) {
 			case '\\':
@@ -1585,6 +1583,8 @@ static void readString(void)
 			break;
 
 		case '{': // Symbol interpolation
+			if (raw)
+				break;
 			// We'll be exiting the string scope, so re-enable expansions
 			// (Not interpolations, since they're handled by the function itself...)
 			lexerState->disableMacroArgs = false;
@@ -1613,7 +1613,7 @@ finish:
 	lexerState->disableInterpolation = false;
 }
 
-static size_t appendStringLiteral(size_t i)
+static size_t appendStringLiteral(size_t i, bool raw)
 {
 	lexerState->disableMacroArgs = true;
 	lexerState->disableInterpolation = true;
@@ -1674,6 +1674,8 @@ static size_t appendStringLiteral(size_t i)
 			goto finish;
 
 		case '\\': // Character escape or macro arg
+			if (raw)
+				break;
 			c = peek();
 			switch (c) {
 			// Character escape
@@ -1721,12 +1723,6 @@ static size_t appendStringLiteral(size_t i)
 				c = '\\';
 				break;
 
-			case ',': // `\,` inside a macro arg string literal
-				warning(WARNING_OBSOLETE,
-					"`\\,` is deprecated inside strings\n");
-				shiftChar();
-				break;
-
 			default:
 				error("Illegal character escape %s\n", printChar(c));
 				shiftChar();
@@ -1735,6 +1731,8 @@ static size_t appendStringLiteral(size_t i)
 			break;
 
 		case '{': // Symbol interpolation
+			if (raw)
+				break;
 			// We'll be exiting the string scope, so re-enable expansions
 			// (Not interpolations, since they're handled by the function itself...)
 			lexerState->disableMacroArgs = false;
@@ -1769,11 +1767,8 @@ static int yylex_SKIP_TO_ENDC(void); // forward declaration for yylex_NORMAL
 
 static int yylex_NORMAL(void)
 {
-	uint32_t num = 0;
-
 	for (;;) {
 		int c = nextChar();
-		char secondChar;
 
 		switch (c) {
 		// Ignore whitespace and comments
@@ -1920,15 +1915,19 @@ static int yylex_NORMAL(void)
 				return T_OP_LOGICGT;
 			}
 
-		// Handle colon, which may begin an anonymous label ref
+		case ':': // Either :, ::, or an anonymous label ref
-
-		case ':':
 			c = peek();
-			if (c != '+' && c != '-')
+			switch (c) {
+			case ':':
+				shiftChar();
+				return T_DOUBLE_COLON;
+			case '+':
+			case '-':
+				readAnonLabelRef(c);
+				return T_ANON;
+			default:
 				return T_COLON;
-
+			}
-			readAnonLabelRef(c);
-			return T_ANON;
 
 		// Handle numbers
 
@@ -1941,36 +1940,37 @@ static int yylex_NORMAL(void)
 		case '6':
 		case '7':
 		case '8':
-		case '9':
+		case '9': {
-			num = readNumber(10, c - '0');
+			uint32_t n = readNumber(10, c - '0');
+
 			if (peek() == '.') {
 				shiftChar();
-				yylval.constValue = readFractionalPart(num);
+				n = readFractionalPart(n);
-			} else {
-				yylval.constValue = num;
 			}
+			yylval.constValue = n;
 			return T_NUMBER;
+		}
 
 		case '&': // Either &=, binary AND, logical AND, or an octal constant
-			secondChar = peek();
+			c = peek();
-			if (secondChar == '=') {
+			if (c == '=') {
 				shiftChar();
 				return T_POP_ANDEQ;
-			} else if (secondChar == '&') {
+			} else if (c == '&') {
 				shiftChar();
 				return T_OP_LOGICAND;
-			} else if (secondChar >= '0' && secondChar <= '7') {
+			} else if (c >= '0' && c <= '7') {
 				yylval.constValue = readNumber(8, 0);
 				return T_NUMBER;
 			}
 			return T_OP_AND;
 
 		case '%': // Either %=, MOD, or a binary constant
-			secondChar = peek();
+			c = peek();
-			if (secondChar == '=') {
+			if (c == '=') {
 				shiftChar();
 				return T_POP_MODEQ;
-			} else if (secondChar == binDigits[0] || secondChar == binDigits[1]) {
+			} else if (c == binDigits[0] || c == binDigits[1]) {
 				yylval.constValue = readBinaryNumber();
 				return T_NUMBER;
 			}
@@ -1987,7 +1987,7 @@ static int yylex_NORMAL(void)
 		// Handle strings
 
 		case '"':
-			readString();
+			readString(false);
 			return T_STRING;
 
 		// Handle newlines and EOF
@@ -2009,6 +2009,16 @@ static int yylex_NORMAL(void)
 			readLineContinuation();
 			break;
 
+		// Handle raw strings... or fall through if '#' is not followed by '"'
+
+		case '#':
+			if (peek() == '"') {
+				shiftChar();
+				readString(true);
+				return T_STRING;
+			}
+			// fallthrough
+
 		// Handle identifiers... or report garbage characters
 
 		default:
@@ -2087,7 +2097,16 @@ static int yylex_RAW(void)
 		switch (c) {
 		case '"': // String literals inside macro args
 			shiftChar();
-			i = appendStringLiteral(i);
+			i = appendStringLiteral(i, false);
+			break;
+
+		case '#': // Raw string literals inside macro args
+			append_yylval_string(c);
+			shiftChar();
+			if (peek() == '"') {
+				shiftChar();
+				i = appendStringLiteral(i, true);
+			}
 			break;
 
 		case ';': // Comments inside macro args
@@ -2407,11 +2426,11 @@ int yylex(void)
 		nextLine();
 
 	static int (* const lexerModeFuncs[])(void) = {
-		[LEXER_NORMAL]       = yylex_NORMAL,
+		AT(LEXER_NORMAL)       yylex_NORMAL,
-		[LEXER_RAW]          = yylex_RAW,
+		AT(LEXER_RAW)          yylex_RAW,
-		[LEXER_SKIP_TO_ELIF] = yylex_SKIP_TO_ELIF,
+		AT(LEXER_SKIP_TO_ELIF) yylex_SKIP_TO_ELIF,
-		[LEXER_SKIP_TO_ENDC] = yylex_SKIP_TO_ENDC,
+		AT(LEXER_SKIP_TO_ENDC) yylex_SKIP_TO_ENDC,
-		[LEXER_SKIP_TO_ENDR] = yylex_SKIP_TO_ENDR,
+		AT(LEXER_SKIP_TO_ENDR) yylex_SKIP_TO_ENDR,
 	};
 	int token = lexerModeFuncs[lexerState->mode]();
 

src/asm/macro.cpp

@@ -1,10 +1,4 @@
-/*
+/* SPDX-License-Identifier: MIT */
- * This file is part of RGBDS.
- *
- * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
 
 #include <errno.h>
 #include <inttypes.h>
@@ -13,8 +7,8 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include "asm/macro.h"
+#include "asm/macro.hpp"
-#include "asm/warning.h"
+#include "asm/warning.hpp"
 
 #define MAXMACROARGS 99999
 
@@ -32,7 +26,7 @@ struct MacroArgs {
 };
 
 #define SIZEOF_ARGS(nbArgs) (sizeof(struct MacroArgs) + \
-			    sizeof(((struct MacroArgs){0}).args[0]) * (nbArgs))
+			    sizeof(((struct MacroArgs *)0)->args[0]) * (nbArgs))
 
 static struct MacroArgs *macroArgs = NULL;
 static uint32_t uniqueID = 0;
@@ -50,7 +44,7 @@ struct MacroArgs *macro_GetCurrentArgs(void)
 
 struct MacroArgs *macro_NewArgs(void)
 {
-	struct MacroArgs *args = malloc(SIZEOF_ARGS(INITIAL_ARG_SIZE));
+	struct MacroArgs *args = (struct MacroArgs *)malloc(SIZEOF_ARGS(INITIAL_ARG_SIZE));
 
 	if (!args)
 		fatalerror("Unable to register macro arguments: %s\n", strerror(errno));
@@ -73,7 +67,7 @@ void macro_AppendArg(struct MacroArgs **argPtr, char *s)
 		// Check that overflow didn't roll us back
 		if (macArgs->capacity <= macArgs->nbArgs)
 			fatalerror("Failed to add new macro argument: capacity overflow\n");
-		macArgs = realloc(macArgs, SIZEOF_ARGS(macArgs->capacity));
+		macArgs = (struct MacroArgs *)realloc(macArgs, SIZEOF_ARGS(macArgs->capacity));
 		if (!macArgs)
 			fatalerror("Error adding new macro argument: %s\n", strerror(errno));
 	}
@@ -116,7 +110,7 @@ char const *macro_GetAllArgs(void)
 	for (uint32_t i = macroArgs->shift; i < macroArgs->nbArgs; i++)
 		len += strlen(macroArgs->args[i]) + 1; // 1 for comma
 
-	char *str = malloc(len + 1); // 1 for '\0'
+	char *str = (char *)malloc(len + 1); // 1 for '\0'
 	char *ptr = str;
 
 	if (!str)