Version 0.6.0

Doing it right this time.
Also bundling the newly required DLLs.

.clang-format

@@ -0,0 +1,99 @@
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignArrayOfStructures: Left
+AlignConsecutiveAssignments: None
+AlignConsecutiveBitFields: Consecutive
+AlignConsecutiveDeclarations: None
+AlignConsecutiveMacros: Consecutive
+AlignEscapedNewlines: Left
+AlignOperands: Align
+AlignTrailingComments: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortEnumsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: InlineOnly
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLambdasOnASingleLine: All
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: Yes
+AttributeMacros:
+  - format_
+  - attr_
+BinPackArguments: true
+BinPackParameters: true
+BitFieldColonSpacing: Both
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeBraces: Attach
+BreakBeforeConceptDeclarations: true
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeColon
+BreakInheritanceList: AfterComma
+BreakStringLiterals: true
+ColumnLimit: 100
+CompactNamespaces: false
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DeriveLineEnding: true
+DerivePointerAlignment: false
+EmptyLineBeforeAccessModifier: Leave
+FixNamespaceComments: false
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^<sys/'
+    Priority: 0
+  - Regex: '^<'
+    Priority: 1
+  - Regex: '^"extern/'
+    Priority: 2
+  - Regex: '^"(asm|link|fix|gfx)/'
+    Priority: 3
+  - Regex: '^"'
+    Priority: 2
+IndentAccessModifiers: false
+IndentCaseBlocks: false
+IndentCaseLabels: false
+IndentExternBlock: NoIndent
+IndentGotoLabels: false
+IndentPPDirectives: BeforeHash
+IndentRequires: true
+IndentWidth: 4
+IndentWrappedFunctionNames: true
+# Only support for Javascript as of clang-format 13...
+# InsertTrailingCommas: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+LambdaBodyIndentation: Signature
+Language: Cpp
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+PPIndentWidth: -1
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: CaseSensitive
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: false
+SpaceAroundPointerQualifiers: Both
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCaseColon: false
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceBeforeSquareBrackets: false
+SpaceInEmptyBlock: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInConditionalStatement: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: c++17
+TabWidth: 4
+UseCRLF: false
+UseTab: ForIndentation

.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,3 +1 @@
-github: avivace
-patreon: gbdev01
 open_collective: gbdev

.github/actions/doc_postproc.awk

@@ -1,56 +0,0 @@
-#!/usr/bin/awk -f
-
-/^\s+<td><b class="Sy">.+<\/b><\/td>$/ {
-	# Assuming that all cells whose contents are bold are heading cells,
-	# use the HTML tag for those
-	sub(/td><b class="Sy"/, "th");
-	sub(/b><\/td/, "th");
-}
-
-# The whole page is being generated, so it's not meant to contain any Liquid
-BEGIN {
-	print "{% raw %}"
-}
-END {
-	print "{% endraw %}"
-}
-
-BEGIN {
-	in_synopsis = 0
-}
-/<table class="Nm">/ {
-	in_synopsis = 1
-}
-/<\/table>/ {
-	# Resets synopsis state even when already reset, but whatever
-	in_synopsis = 0
-}
-/<code class="Fl">-[a-zA-Z]/ {
-	# Add links to arg descr in synopsis section
-	if (in_synopsis) {
-		while (match($0, /<code class="Fl">-[a-zA-Z]+/)) {
-			#         123456789012345678 -> 18 chars
-			optchars = substr($0, RSTART + 18, RLENGTH - 18)
-			i = length(optchars)
-			while (i) {
-				end = RSTART + 18 + i
-				i -= 1
-				len = i ? 1 : 2
-				$0 = sprintf("%s<a href=\"#%s\">%s</a>%s",
-				             substr($0, 0, end - len - 1),
-				             substr($0, end - 1, 1),
-				             substr($0, end - len, len),
-				             substr($0, end))
-			}
-		}
-	}
-}
-
-{
-	# Make long opts (defined using `Fl Fl`) into a single tag
-	gsub(/<code class="Fl">-<\/code>\s*<code class="Fl">/, "<code class=\"Fl\">-")
-}
-
-{
-	print
-}

.github/actions/get-pages.sh

@@ -1,113 +0,0 @@
-#!/bin/bash
-
-usage() {
-	cat <<EOF
-Usage: $0 [-h] [-r] <rgbds-www> <version>
-Copy renders from RGBDS repository to rgbds-www documentation
-Execute from the root folder of the RGBDS repo, checked out at the desired tag
-<rgbds-www> : Path to the rgbds-www repository
-<version>   : Version to be copied, such as 'v0.4.1' or 'master'
-
-    -h  Display this help message
-    -r  Update "latest stable" redirection pages and add a new entry to the index
-        (use for releases, not master)
-EOF
-}
-
-is_release=0
-bad_usage=0
-while getopts ":hr" opt; do
-	case $opt in
-		r)
-			is_release=1
-			;;
-		h)
-			usage
-			exit 0
-			;;
-		\?)
-			echo "Unknown option '$OPTARG'"
-			bad_usage=1
-			;;
-	esac
-done
-if [ $bad_usage -ne 0 ]; then
-	usage
-	exit 1
-fi
-shift $(($OPTIND - 1))
-
-
-declare -A PAGES
-PAGES=(
-	[rgbasm.1.html]=src/asm/rgbasm.1
-	[rgbasm.5.html]=src/asm/rgbasm.5
-	[rgblink.1.html]=src/link/rgblink.1
-	[rgblink.5.html]=src/link/rgblink.5
-	[rgbfix.1.html]=src/fix/rgbfix.1
-	[rgbgfx.1.html]=src/gfx/rgbgfx.1
-	[rgbds.5.html]=src/rgbds.5
-	[rgbds.7.html]=src/rgbds.7
-	[gbz80.7.html]=src/gbz80.7
-)
-WWWPATH="/docs"
-mkdir -p "$1/_documentation/$2"
-
-# `mandoc` uses a different format for referring to man pages present in the **current** directory.
-# We want that format for RGBDS man pages, and the other one for the rest;
-# we thus need to copy all pages to a temporary directory, and process them there.
-
-# Copy all pages to current dir
-cp "${PAGES[@]}" .
-
-for page in "${!PAGES[@]}"; do
-stem="${page%.html}"
-manpage="${stem%.?}(${stem#*.})"
-descr="$(awk -v 'FS=.Nd ' '/.Nd/ { print $2; }' "${PAGES[$page]}")"
-
-	cat >"$1/_documentation/$2/$page" <<EOF
----
-layout: doc
-title: $manpage [$2]
-description: RGBDS $2 — $descr
----
-EOF
-	options=fragment,man='%N.%S;https://linux.die.net/man/%S/%N'
-	if [ $stem = rgbasm.5 ]; then
-		options+=,toc
-	fi
-	mandoc -Thtml -I os=Linux -O$options "${PAGES[$page]##*/}" | .github/actions/doc_postproc.awk >> "$1/_documentation/$2/$page"
-	groff -Tpdf -mdoc -wall "${PAGES[$page]##*/}" >"$1/_documentation/$2/$stem.pdf"
-	if [ $is_release -ne 0 ]; then
-		cat - >"$1/_documentation/$page" <<EOF
----
-redirect_to: $WWWPATH/$2/${page%.html}
-permalink: $WWWPATH/${page%.html}/
-title: $manpage [latest stable]
-description: RGBDS latest stable — $descr
----
-EOF
-	fi
-done
-
-cat - >"$1/_documentation/$2/index.html" <<EOF
----
-layout: doc_index
-permalink: /docs/$2/
-title: RGBDS online manual [$2]
-description: RGBDS $2 - Online manual
----
-EOF
-
-
-# If making a release, add a new entry right after `master`
-if [ $is_release -ne 0 ]; then
-	awk '{ print }
-/"name": "master"/ { print "\t\t{\"name\": \"'$2'\",  \"text\": \"'$2'\" }," }
-' "$1/_data/doc.json" >"$1/_data/doc.json.tmp"
-	mv "$1/_data/doc.json"{.tmp,}
-fi
-
-
-# Clean up
-rm "${PAGES[@]##*/}"

.github/actions/install_deps.sh

@@ -1,4 +1,7 @@
-case `echo $1 | cut -d '-' -f 1` in
+#!/bin/bash
+set -e
+
+case "${1%-*}" in
 	ubuntu)
 		sudo apt-get -qq update
 		sudo apt-get install -yq bison libpng-dev pkg-config

.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 +1,34 @@
 #!/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"
-_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/libpng/libpng16/$pngver/libpng-$pngver.tar.xz
-wget http://downloads.sourceforge.net/project/apng/libpng/libpng16/libpng-$_apngver-apng.patch.gz
+wget http://downloads.sourceforge.net/project/apng/libpng/libpng16/libpng-$pngver-apng.patch.gz
 sha256sum -c .github/actions/mingw-w64-libpng-dev.sha256sums
 
-## Extract sources
+## Extract sources and patch them
 
 tar -xf libpng-$pngver.tar.xz
-gunzip libpng-$_apngver-apng.patch.gz
+gunzip libpng-$pngver-apng.patch.gz
 
+# Patch in apng support
+env -C libpng-$pngver patch -p0 ../libpng-$pngver-apng.patch
 
 ## Start building!
 
-cd libpng-$pngver
+mkdir -p build
-# Patch in apng support
+cd build
-patch -p0 ../libpng-$_apngver-apng.patch
+../libpng-$pngver/configure \
-
+	--host="$arch" --target="$arch" \
-mkdir -p build-${_arch}
+	--prefix="/usr/$arch" \
-cd build-${_arch}
+	--enable-shared --disable-static \
-${_arch}-configure LDFLAGS=-static-libgcc
+	CPPFLAGS="-D_FORTIFY_SOURCE=2" \
-make
+	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/create-release-artifacts.yaml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   windows:
-    runs-on: windows-2019
+    runs-on: windows-2022
     steps:
       - uses: actions/checkout@v2
       - name: Get version from tag
@@ -17,9 +17,9 @@ jobs:
       - name: Get zlib, libpng and bison
         run: | # TODO: use an array
           $wc = New-Object System.Net.WebClient
-          $wc.DownloadFile('https://www.zlib.net/zlib1211.zip', 'zlib.zip')
+          $wc.DownloadFile('https://www.zlib.net/zlib1212.zip', 'zlib.zip')
           $hash = (Get-FileHash "zlib.zip" -Algorithm SHA256).Hash
-          if ($hash -ne 'd7510a8ee1918b7d0cad197a089c0a2cd4d6df05fee22389f67f115e738b178d') {
+          if ($hash -ne '173e89893dcb8b4a150d7731cd72f0602f1d6b45e60e2a54efdf7f3fc3325fd7') {
             Write-Host "zlib SHA256 mismatch! ($hash)"
             exit 1
           }
@@ -37,7 +37,7 @@ jobs:
           Expand-Archive -DestinationPath .           "zlib.zip"
           Expand-Archive -DestinationPath .           "libpng.zip"
           Expand-Archive -DestinationPath install_dir "winflexbison.zip"
-          Move-Item zlib-1.2.11 zlib
+          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`

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

@@ -7,7 +7,7 @@ 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
@@ -18,21 +18,14 @@ jobs:
         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.5.tar.gz'
-          tar xf mandoc-1.14.5.tar.gz
-          cd mandoc-1.14.5
-          ./configure
-          make
-          sudo make install
       - name: Update pages
-        working-directory: rgbds
+        working-directory: rgbds/man
         run: | # The ref appears to be in the format "refs/tags/<version>", so strip that
-          ./.github/actions/get-pages.sh -r ../rgbds-www ${GITHUB_REF##*/}
+          ../../rgbds-www/.github/actions/get-pages.sh ${GITHUB_REF##*/} *
       - name: Push new pages
         working-directory: rgbds-www
         run: |

.github/workflows/testing.yml

@@ -7,28 +7,20 @@ jobs:
   unix-testing:
     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]
         buildsys: [make, cmake]
         exclude:
           # `gcc` is just an alias to `clang` on macOS, don't bother
-          - os: macos-10.15
+          - os: macos-11
             cc: gcc
-          - os: macos-11.0
+          - os: macos-12
             cc: gcc
         include:
-          - os: ubuntu-18.04
+          - cc: gcc
-            target: develop
+            cxx: g++
-            cmakevars: -DSANITIZERS=ON -DMORE_WARNINGS=ON -DCMAKE_BUILD_TYPE=Debug
+          - cc: clang
-          - os: ubuntu-20.04
+            cxx: clang++
-            target: develop
-            cmakevars: -DSANITIZERS=ON -DMORE_WARNINGS=ON -DCMAKE_BUILD_TYPE=Debug
-          - os: macos-11.0
-            target: develop
-            cmakevars: -DSANITIZERS=ON -DMORE_WARNINGS=ON -DCMAKE_BUILD_TYPE=Debug
-          - os: macos-10.15
-            target: develop
-            cmakevars: -DSANITIZERS=ON -DMORE_WARNINGS=ON -DCMAKE_BUILD_TYPE=Debug
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -41,25 +33,25 @@ jobs:
       # Apple's base version is severely outdated, not even supporting -Wall,
       # but it overrides Homebrew's version nonetheless...
       - name: Build & install using Make
-        run: |
-          export PATH="/usr/local/opt/bison/bin:$PATH"
-          make ${{ matrix.target }} -j Q= CC=${{ matrix.cc }}
-          sudo make install -j Q=
         if: matrix.buildsys == 'make'
-      - name: Build & install using CMake
         run: |
           export PATH="/usr/local/opt/bison/bin:$PATH"
-          cmake -S . -B build -DCMAKE_VERBOSE_MAKEFILE=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=${{ matrix.cc }} ${{ matrix.cmakevars }}
+          make develop -j Q= CC=${{ matrix.cc }} CXX=${{ matrix.cxx }}
-          cmake --build build -j
+          sudo make install -j Q=
-          cp build/src/rgb{asm,link,fix,gfx} .
+      - name: Build & install using CMake
-          sudo cmake --install build
         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 --build build -j --verbose
+          cp build/src/rgb{asm,link,fix,gfx} .
+          sudo cmake --install build --verbose
       - name: Package binaries
         run: |
           mkdir bins
           cp rgb{asm,link,fix,gfx} bins
       - name: Upload binaries
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v3
         with:
           name: rgbds-canary-${{ matrix.os }}-${{ matrix.cc }}-${{ matrix.buildsys }}
           path: bins
@@ -72,6 +64,7 @@ jobs:
     strategy:
       matrix:
         bits: [32, 64]
+        os: [windows-2019, windows-2022]
         include:
           - bits: 32
             arch: x86
@@ -80,15 +73,15 @@ jobs:
             arch: x86_x64
             platform: x64
       fail-fast: false
-    runs-on: windows-2019
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
       - name: Get zlib, libpng and bison
-        run: | # TODO: use an array
+        run: | # TODO: use an array; remember to update the versions being downloaded, *and* the paths being extracted! (`Move-Item`)
           $wc = New-Object System.Net.WebClient
-          $wc.DownloadFile('https://www.zlib.net/zlib1211.zip', 'zlib.zip')
+          $wc.DownloadFile('https://www.zlib.net/zlib1212.zip', 'zlib.zip')
           $hash = (Get-FileHash "zlib.zip" -Algorithm SHA256).Hash
-          if ($hash -ne 'd7510a8ee1918b7d0cad197a089c0a2cd4d6df05fee22389f67f115e738b178d') {
+          if ($hash -ne '173e89893dcb8b4a150d7731cd72f0602f1d6b45e60e2a54efdf7f3fc3325fd7') {
             Write-Host "zlib SHA256 mismatch! ($hash)"
             exit 1
           }
@@ -106,30 +99,43 @@ jobs:
           Expand-Archive -DestinationPath .           "zlib.zip"
           Expand-Archive -DestinationPath .           "libpng.zip"
           Expand-Archive -DestinationPath install_dir "winflexbison.zip"
-          Move-Item zlib-1.2.11 zlib
+          Move-Item zlib-1.2.12 zlib
           Move-Item lpng1637 libpng
+      - 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 }} -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
         run: |
           cmake -S libpng -B pngbuild -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DPNG_SHARED=ON -DPNG_STATIC=ON -DPNG_TESTS=OFF
           cmake --build pngbuild --config Release -j
+        if: steps.cache.outputs.cache-hit != 'true'
+      - name: Install libpng
+        run: |
           cmake --install pngbuild
       - name: Build Windows binaries
         run: |
           cmake -S . -B build -A ${{ matrix.platform }} -DCMAKE_INSTALL_PREFIX=install_dir -DCMAKE_BUILD_TYPE=Release
-          cmake --build build --config Release -j
+          cmake --build build --config Release -j --verbose
-          cmake --install build
+          cmake --install build --verbose --prefix install_dir
       - name: Package binaries
         shell: bash
         run: |
           mkdir bins
           cp install_dir/bin/{rgbasm.exe,rgblink.exe,rgbfix.exe,rgbgfx.exe,zlib1.dll,libpng16.dll} bins
       - name: Upload Windows binaries
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v3
         with:
           name: rgbds-canary-win${{ matrix.bits }}
           path: bins
@@ -137,13 +143,13 @@ jobs:
         shell: bash
         run: |
           cp bins/* .
+          cp bins/*.dll test/gfx
           test/run-tests.sh
 
   windows-xbuild:
     strategy:
       matrix:
         bits: [32, 64]
-        os: [ubuntu-18.04]
         include:
           - bits: 32
             arch: i686
@@ -152,7 +158,7 @@ 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:
@@ -162,8 +168,8 @@ jobs:
         run: |
           ./.github/actions/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-mingw-w64-${{ matrix.arch }} mingw-w64-tools libz-mingw-w64-dev
+          sudo apt-get install {gcc,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 }}
@@ -171,39 +177,50 @@ jobs:
         run: |
           make mingw${{ matrix.bits }} -j Q=
       - name: Package binaries
-        run: |
+        run: | # DLL dependencies can be figured out using e.g. Dependency Walker
           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
+          [ "${{ matrix.bits }}" -ne 32 ] || cp -v /usr/lib/gcc/${{ matrix.triplet }}/10-win32/lib{gcc_s_dw2-1,ssp-0,stdc++-6}.dll bins
-          cp /usr/${{ matrix.triplet }}/lib/zlib1.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/libgcc_s_sjlj-1.dll bins; fi
       - name: Upload Windows binaries
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v3
         with:
           name: rgbds-canary-mingw-win${{ matrix.bits }}
           path: bins
+      - name: Upload Windows test binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: testing-programs-mingw-win${{ matrix.bits }}
+          path: |
+            test/gfx/randtilegen.exe
+            test/gfx/rgbgfx_test.exe
 
   windows-xtesting:
     needs: windows-xbuild
     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
       - name: Retrieve binaries
-        uses: actions/download-artifact@v1
+        uses: actions/download-artifact@v3
         with:
           name: rgbds-canary-mingw-win${{ matrix.bits }}
           path: bins
+      - name: Retrieve test binaries
+        uses: actions/download-artifact@v3
+        with:
+          name: testing-programs-mingw-win${{ matrix.bits }}
+          path: test/gfx
       - name: Extract binaries
         shell: bash
         run: |
           cp bins/* .
+          cp bins/*.dll test/gfx
       - name: Run tests
         shell: bash
         run: |

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

@@ -4,21 +4,20 @@ on:
     branches:
       - master
     paths:
-      - .github/actions/get-pages.sh
+      - man/gbz80.7
-      - src/gbz80.7
+      - man/rgbds.5
-      - src/rgbds.5
+      - man/rgbds.7
-      - src/rgbds.7
+      - man/rgbasm.1
-      - src/asm/rgbasm.1
+      - man/rgbasm.5
-      - src/asm/rgbasm.5
+      - man/rgblink.1
-      - src/link/rgblink.1
+      - man/rgblink.5
-      - src/link/rgblink.5
+      - man/rgbfix.1
-      - src/fix/rgbfix.1
+      - man/rgbgfx.1
-      - src/gfx/rgbgfx.1
 
 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
@@ -32,20 +31,14 @@ jobs:
           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.5.tar.gz'
-          tar xf mandoc-1.14.5.tar.gz
-          cd mandoc-1.14.5
-          ./configure
-          make
-          sudo make install
       - name: Update pages
-        working-directory: rgbds
+        working-directory: rgbds/man
         run: |
-          ./.github/actions/get-pages.sh ../rgbds-www master
+          ../../rgbds-www/maintainer/man_to_html.sh master *
       - name: Push new pages
         working-directory: rgbds-www
         run: |
@@ -56,7 +49,7 @@ jobs:
           ssh-add ~/.ssh/id_ed25519
           git config --global user.name "GitHub Action"
           git config --global user.email "community@gbdev.io"
-          git add .
+          git add -A
           git commit -m "Update RGBDS master documentation"
           if git remote | grep -q origin; then
             git remote set-url origin git@github.com:gbdev/rgbds-www.git

CMakeLists.txt

@@ -10,7 +10,7 @@
 cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
 
 project(rgbds
-        LANGUAGES C)
+        LANGUAGES C CXX)
 
 # get real path of source and binary directories
 get_filename_component(srcdir "${CMAKE_SOURCE_DIR}" REALPATH)
@@ -29,8 +29,18 @@ 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(/std:c11 /W1 /MP /wd5105)
+  add_compile_options(/MP /wd5105)
   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)
+    add_compile_options(${SAN_FLAGS})
+    add_link_options(${SAN_FLAGS})
+  endif()
 else()
   add_compile_options(-Wall -pedantic)
   add_definitions(-D_POSIX_C_SOURCE=200809L -D_ISOC11_SOURCE)
@@ -41,38 +51,59 @@ else()
                   -fsanitize=object-size -fsanitize=bool -fsanitize=enum
                   -fsanitize=alignment -fsanitize=null -fsanitize=address)
     add_compile_options(${SAN_FLAGS})
-    link_libraries(${SAN_FLAGS})
+    add_link_options(${SAN_FLAGS})
+    # 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()
 
   if(MORE_WARNINGS)
-    add_compile_options(-Werror -Wextra -Wno-type-limits
+    add_compile_options(-Werror -Wextra
-                        -Wno-sign-compare -Wvla -Wformat -Wformat-security -Wformat-overflow=2
+                        -Walloc-zero -Wcast-align -Wcast-qual -Wduplicated-branches -Wduplicated-cond
-                        -Wformat-truncation=1 -Wformat-y2k -Wswitch-enum -Wunused
+                        -Wfloat-equal -Wlogical-op -Wnull-dereference -Wshift-overflow=2
-                        -Wuninitialized -Wunknown-pragmas -Wstrict-overflow=5
+                        -Wstringop-overflow=4 -Wstrict-overflow=5 -Wundef -Wuninitialized -Wunused
-                        -Wstringop-overflow=4 -Walloc-zero -Wduplicated-cond
+                        -Wshadow # TODO: -Wshadow=compatible-local ?
-                        -Wfloat-equal -Wshadow -Wcast-qual -Wcast-align -Wlogical-op
+                        -Wformat=2 -Wformat-overflow=2 -Wformat-truncation=1
-                        -Wnested-externs -Wno-aggressive-loop-optimizations -Winline
+                        -Wno-format-nonliteral # We have a couple of "dynamic" prints
-                        -Wundef -Wstrict-prototypes -Wold-style-definition
+                        # We do some range checks that are always false on some platforms (GCC, Clang)
-                        -Wno-unknown-warning-option -Wno-tautological-constant-out-of-range-compare)
+                        -Wno-type-limits -Wno-tautological-constant-out-of-range-compare
+                        -Wvla # MSVC does not support VLAs
+                        -Wno-unknown-warning-option) # Clang shouldn't diagnose unknown warnings
   endif()
 endif()
 
 # Use versioning consistent with Makefile
 # the git revision is used but uses the fallback in an archive
 
-execute_process(COMMAND git describe --tags --dirty --always
+find_program(GIT git)
-                OUTPUT_VARIABLE GIT_REV
+if(GIT)
-                ERROR_QUIET)
+  execute_process(COMMAND ${GIT} describe --tags --dirty --always
-string(STRIP "${GIT_REV}" GIT_REV)
+                  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+                  OUTPUT_VARIABLE GIT_REV OUTPUT_STRIP_TRAILING_WHITESPACE
+                  ERROR_QUIET)
+  message(STATUS "RGBDS version: ${GIT_REV}")
+else(GIT)
+  message(STATUS "Cannot determine RGBDS version (Git not installed), falling back")
+endif(GIT)
+
+find_package(PkgConfig)
+if(MSVC OR NOT PKG_CONFIG_FOUND)
+  # fallback to find_package
+  find_package(PNG REQUIRED)
+else()
+  pkg_check_modules(LIBPNG REQUIRED libpng)
+endif()
 
 include_directories("${PROJECT_SOURCE_DIR}/include")
 
-add_definitions(-DBUILD_VERSION_STRING="${GIT_REV}")
-
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED True)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 add_subdirectory(src)
+add_subdirectory(test)
 
 # By default, build in Release mode; Debug mode must be explicitly requested
 # (You may want to augment it with the options above)
@@ -87,3 +118,19 @@ if(CMAKE_BUILD_TYPE STREQUAL "Release")
     message(CHECK_FAIL "no")
   endif()
 endif()
+
+set(MANDIR "share/man")
+set(man1 "man/rgbasm.1"
+         "man/rgbfix.1"
+         "man/rgbgfx.1"
+         "man/rgblink.1")
+set(man5 "man/rgbasm.5"
+         "man/rgblink.5"
+         "man/rgbds.5")
+set(man7 "man/gbz80.7"
+         "man/rgbds.7")
+
+foreach(SECTION "man1" "man5" "man7")
+  set(DEST "${MANDIR}/${SECTION}")
+  install(FILES ${${SECTION}} DESTINATION ${DEST})
+endforeach()

Makefile

@@ -7,7 +7,9 @@
 #
 
 .SUFFIXES:
-.SUFFIXES: .h .y .c .o
+.SUFFIXES: .h .y .c .cpp .o
+
+.PHONY: all clean install checkcodebase checkpatch checkdiff develop debug mingw32 mingw64 wine-shim dist
 
 # User-defined variables
 
@@ -30,14 +32,17 @@ PNGLDLIBS	:= `${PKG_CONFIG} --libs-only-l libpng`
 # Note: if this comes up empty, `version.c` will automatically fall back to last release number
 VERSION_STRING	:= `git describe --tags --dirty --always 2>/dev/null`
 
-WARNFLAGS	:= -Wall
+WARNFLAGS	:= -Wall -pedantic
 
 # Overridable CFLAGS
-CFLAGS		?= -O3 -flto -DNDEBUG
+CFLAGS		?= -O3 -flto=auto -DNDEBUG
+CXXFLAGS	?= -O3 -flto=auto -DNDEBUG
 # Non-overridable CFLAGS
 # _ISOC11_SOURCE is required on certain platforms to get C11 on top of the C99-based POSIX 2008
 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		?=
 # Non-overridable LDFLAGS
@@ -88,9 +93,11 @@ rgblink_obj := \
 	src/link/output.o \
 	src/link/patch.o \
 	src/link/script.o \
+	src/link/sdas_obj.o \
 	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 \
@@ -102,9 +109,14 @@ rgbfix_obj := \
 	src/error.o
 
 rgbgfx_obj := \
-	src/gfx/gb.o \
 	src/gfx/main.o \
-	src/gfx/makepng.o \
+	src/gfx/pal_packing.o \
+	src/gfx/pal_sorting.o \
+	src/gfx/pal_spec.o \
+	src/gfx/process.o \
+	src/gfx/proto_palette.o \
+	src/gfx/reverse.o \
+	src/gfx/rgba.o \
 	src/extern/getopt.o \
 	src/error.o
 
@@ -118,7 +130,13 @@ rgbfix: ${rgbfix_obj}
 	$Q${CC} ${REALLDFLAGS} -o $@ ${rgbfix_obj} ${REALCFLAGS} src/version.c
 
 rgbgfx: ${rgbgfx_obj}
-	$Q${CC} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ ${rgbgfx_obj} ${REALCFLAGS} src/version.c ${PNGLDLIBS}
+	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ ${rgbgfx_obj} ${REALCXXFLAGS} -x c++ src/version.c ${PNGLDLIBS}
+
+test/gfx/randtilegen: test/gfx/randtilegen.c
+	$Q${CC} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ $^ ${REALCFLAGS} ${PNGCFLAGS} ${PNGLDLIBS}
+
+test/gfx/rgbgfx_test: test/gfx/rgbgfx_test.cpp
+	$Q${CXX} ${REALLDFLAGS} ${PNGLDFLAGS} -o $@ $^ ${REALCXXFLAGS} ${PNGLDLIBS}
 
 # Rules to process files
 
@@ -145,7 +163,10 @@ src/asm/parser.c: src/asm/parser.y
 	${BISON} $$DEFS -d ${YFLAGS} -o $@ $<
 
 .c.o:
-	$Q${CC} ${REALCFLAGS} ${PNGCFLAGS} -c -o $@ $<
+	$Q${CC} ${REALCFLAGS} -c -o $@ $<
+
+.cpp.o:
+	$Q${CXX} ${REALCXXFLAGS} ${PNGCFLAGS} -c -o $@ $<
 
 # Target used to remove all files generated by other Makefile targets
 
@@ -157,6 +178,7 @@ clean:
 	$Qfind src/ -name "*.o" -exec rm {} \;
 	$Q${RM} rgbshim.sh
 	$Q${RM} src/asm/parser.c src/asm/parser.h
+	$Q${RM} test/gfx/randtilegen test/gfx/rgbgfx_test
 
 # Target used to install the binaries and man pages.
 
@@ -167,15 +189,15 @@ install: all
 	$Qinstall ${STRIP} -m ${BINMODE} rgblink ${DESTDIR}${bindir}/rgblink
 	$Qinstall ${STRIP} -m ${BINMODE} rgbgfx ${DESTDIR}${bindir}/rgbgfx
 	$Qmkdir -p ${DESTDIR}${mandir}/man1 ${DESTDIR}${mandir}/man5 ${DESTDIR}${mandir}/man7
-	$Qinstall -m ${MANMODE} src/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
+	$Qinstall -m ${MANMODE} man/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
-	$Qinstall -m ${MANMODE} src/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
+	$Qinstall -m ${MANMODE} man/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
-	$Qinstall -m ${MANMODE} src/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5
+	$Qinstall -m ${MANMODE} man/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5
-	$Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
+	$Qinstall -m ${MANMODE} man/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
-	$Qinstall -m ${MANMODE} src/asm/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5
+	$Qinstall -m ${MANMODE} man/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5
-	$Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
+	$Qinstall -m ${MANMODE} man/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
-	$Qinstall -m ${MANMODE} src/link/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
+	$Qinstall -m ${MANMODE} man/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
-	$Qinstall -m ${MANMODE} src/link/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
+	$Qinstall -m ${MANMODE} man/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
-	$Qinstall -m ${MANMODE} src/gfx/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1
+	$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
@@ -209,23 +231,33 @@ checkdiff:
 # This target is used during development in order to prevent adding new issues
 # to the source code. All warnings are treated as errors in order to block the
 # compilation and make the continous integration infrastructure return failure.
+# The rationale for some of the flags is documented in the CMakeLists.
 
 develop:
-	$Qenv $(MAKE) WARNFLAGS="-Werror -Wall -Wextra -Wpedantic -Wno-type-limits \
+	$Qenv ${MAKE} WARNFLAGS="-Werror -Wextra \
-		-Wno-sign-compare -Wvla -Wformat -Wformat-security -Wformat-overflow=2 \
+		-Walloc-zero -Wcast-align -Wcast-qual -Wduplicated-branches -Wduplicated-cond \
-		-Wformat-truncation=1 -Wformat-y2k -Wswitch-enum -Wunused \
+		-Wfloat-equal -Wlogical-op -Wnull-dereference -Wshift-overflow=2 \
-		-Wuninitialized -Wunknown-pragmas -Wstrict-overflow=4 \
+		-Wstringop-overflow=4 -Wstrict-overflow=5 -Wundef -Wuninitialized -Wunused \
-		-Wstringop-overflow=4 -Walloc-zero -Wduplicated-cond \
+		-Wshadow \
-		-Wfloat-equal -Wshadow -Wcast-qual -Wcast-align -Wlogical-op \
+		-Wformat=2 -Wformat-overflow=2 -Wformat-truncation=1 \
-		-Wnested-externs -Wno-aggressive-loop-optimizations -Winline \
+		-Wno-format-nonliteral \
-		-Wundef -Wstrict-prototypes -Wold-style-definition \
+		-Wno-type-limits -Wno-tautological-constant-out-of-range-compare \
-		-Wno-unknown-warning-option -Wno-tautological-constant-out-of-range-compare \
+		-Wvla \
+		-Wno-unknown-warning-option \
 		-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 -O0"
+		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} \
+		CFLAGS="-ggdb3 -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls" \
+		CXXFLAGS="-ggdb3 -Og -fno-omit-frame-pointer -fno-optimize-sibling-calls"
 
 # Targets for the project maintainer to easily create Windows exes.
 # This is not for Windows users!
@@ -233,12 +265,14 @@ develop:
 # install instructions instead.
 
 mingw32:
-	$Qmake CC=i686-w64-mingw32-gcc BISON=bison \
+	$Q${MAKE} all test/gfx/randtilegen test/gfx/rgbgfx_test \
-		PKG_CONFIG=i686-w64-mingw32-pkg-config -j
+		CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ \
+		BISON=bison PKG_CONFIG="PKG_CONFIG_SYSROOT_DIR=/usr/i686-w64-mingw32 pkg-config"
 
 mingw64:
-	$Qmake CC=x86_64-w64-mingw32-gcc BISON=bison \
+	$Q${MAKE} all test/gfx/randtilegen test/gfx/rgbgfx_test \
-		PKG_CONFIG=x86_64-w64-mingw32-pkg-config -j
+		CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ \
+		BISON=bison PKG_CONFIG="PKG_CONFIG_SYSROOT_DIR=/usr/x86_64-w64-mingw32 pkg-config"
 
 wine-shim:
 	$Qecho '#!/bin/bash' > rgbshim.sh

README.rst

@@ -12,11 +12,10 @@ for the Game Boy and Game Boy Color. It consists of:
 This is a fork of the original RGBDS which aims to make the programs more like
 other UNIX tools.
 
-This toolchain is maintained on `GitHub <https://github.com/rednex/rgbds>`__.
+This toolchain is maintained `on GitHub <https://github.com/gbdev/rgbds>`__.
 
-The documentation of this toolchain can be viewed online
+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.
-`here <https://rgbds.gbdev.io/docs/>`__, it is generated from the man pages
+The source code of the website itself is on GitHub as well under the repo `rgbds-www <https://github.com/gbdev/rgbds-www>`__.
-found in this repository.
 
 If you want to contribute or maintain RGBDS, and have questions regarding the code, its organisation, etc. you can find me `on GBDev <https://gbdev.io/chat>`__ or via mail at ``rgbds at eldred dot fr``.
 
@@ -24,7 +23,7 @@ If you want to contribute or maintain RGBDS, and have questions regarding the co
 -------------------
 
 The `installation procedure <https://rgbds.gbdev.io/install>`__ is available
-online for various platforms. `Building from source <https://rgbds.gbdev.io/install/source>`__
+online for various platforms. `Building from source <https://rgbds.gbdev.io/install/#building-from-source>`__
 is possible using ``make`` or ``cmake``; follow the link for more detailed instructions.
 
 .. code:: sh
@@ -57,6 +56,8 @@ The RGBDS source code file structure somewhat resembles the following:
        │   └── ...
        ├── include/
        │   └── ...
+       ├── man/
+       │   └── ...
        ├── src/
        │   ├── asm/
        │   │   └── ...
@@ -73,10 +74,14 @@ The RGBDS source code file structure somewhat resembles the following:
        ├── test/
        │   ├── ...
        │   └── run-tests.sh
+       ├── .clang-format
        ├── CMakeLists.txt
        ├── Makefile
        └── README.rst
 
+.. |clang-format| replace:: ``clang-format``
+.. _clang-format: https://clang.llvm.org/docs/ClangFormat.html
+
 - ``.github/`` - files and scripts related to the integration of the RGBDS codebase with
   GitHub.
 
@@ -92,13 +97,17 @@ The RGBDS source code file structure somewhat resembles the following:
 
 - ``include/`` - header files for each respective C files in `src`.
 
-- ``src/`` - source code and manual pages for RGBDS.
+- ``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.
 
 - ``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.
+
 3. History
 ----------
 
@@ -120,3 +129,11 @@ The RGBDS source code file structure somewhat resembles the following:
 - 2018, codebase relicensed under the MIT license.
 
 - 2020, repository is moved to the `gbdev <https://github.com/gbdev>`__ organisation. The `rgbds.gbdev.io <https://rgbds.gbdev.io>`__ website serving documentation and downloads is created.
+
+4. Acknowledgements
+-------------------
+
+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.

contrib/bash_compl/_rgbasm.bash

@@ -1,4 +1,4 @@
-#/usr/bin/env bash
+#!/usr/bin/env bash
 
 # Known bugs:
 # - Newlines in file/directory names break this script
@@ -11,7 +11,7 @@
 # - Directories are not completed as such in "coalesced" short-opt arguments. For example,
 #   `rgbasm -M d<tab>` can autocomplete to `rgbasm -M dir/` (no space), but
 #   `rgbasm -Md<tab>` would autocomplete to `rgbasm -Mdir ` (trailing space) instead.
-#   This is because dircetory handling is performed by Readline, whom we can't tell about the short
+#   This is because directory handling is performed by Readline, whom we can't tell about the short
 #   opt kerfuffle. The user can work around by separating the argument, as shown above.
 #   (Also, there might be more possible bugs if `-Mdir` is actually a directory. Ugh.)
 
@@ -20,25 +20,27 @@
 # Thus, we don't need to do much to handle that form of argument passing: skip '=' after long opts.
 
 _rgbasm_completions() {
-	COMPREPLY=()
-
 	# Format: "long_opt:state_after"
 	# Empty long opt = it doesn't exit
 	# See the `state` variable below for info about `state_after`
 	declare -A opts=(
 		[V]="version:normal"
 		[E]="export-all:normal"
+		[H]="nop-after-halt:normal"
 		[h]="halt-without-nop:normal"
 		[L]="preserve-ld:normal"
+		[l]="auto-ldh:normal"
 		[v]="verbose:normal"
 		[w]=":normal"
 		[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"
 	)
@@ -58,6 +60,18 @@ _rgbasm_completions() {
 	# "normal" is not returned, `optlen` will be set to the length (dash included) of the "option"
 	# part of the argument.
 	parse_short_opt() {
+		# These options act like a long option (= takes up the entire word), but only use a single dash
+		# So, they need some special handling
+		if [[ "$1" = "-M"[GP] ]]; then
+			state=normal
+			optlen=${#1}
+			return;
+		elif [[ "$1" = "-M"[QT] ]]; then
+			state='glob-*.d *.mk *.o'
+			optlen=${#1}
+			return;
+		fi
+
 		for (( i = 1; i < "${#1}"; i++ )); do
 			# If the option is not known, assume it doesn't take an argument
 			local opt="${opts["${1:$i:1}"]:-":normal"}"
@@ -71,7 +85,7 @@ _rgbasm_completions() {
 		optlen=0
 	}
 
-	for (( i = 1; i < $COMP_CWORD; i++ )); do
+	for (( i = 1; i < COMP_CWORD; i++ )); do
 		local word="${COMP_WORDS[$i]}"
 
 		# If currently processing an argument, skip this word
@@ -87,7 +101,7 @@ _rgbasm_completions() {
 		fi
 
 		# Check if it's a long option
-		if [[ "${word:0:2}" = '--' ]]; then
+		if [[ "$word" = '--'* ]]; then
 			# If the option is unknown, assume it takes no arguments: keep the state at "normal"
 			for long_opt in "${opts[@]}"; do
 				if [[ "$word" = "--${long_opt%%:*}" ]]; then
@@ -103,25 +117,16 @@ _rgbasm_completions() {
 				fi
 			done
 		# Check if it's a short option
-		elif [[ "${word:0:1}" = '-' ]]; then
+		elif [[ "$word" = '-'* ]]; then
-			# The `-M?` ones are a mix of short and long, augh
+			parse_short_opt "$word"
-			# They must match the *full* word, but only take a single dash
+			# The last option takes an argument...
-			# So, handle them here
+			if [[ "$state" != 'normal' ]]; then
-			if [[ "$1" = "-M"[GP] ]]; then
+				if [[ "$optlen" -ne "${#word}" ]]; then
-				state=normal
+					# If it's contained within the word, we won't complete it, revert to "normal"
-			elif [[ "$1" = "-M"[TQ] ]]; then
+					state=normal
-				state='glob-*.d *.mk *.o'
+				else
-			else
+					# Otherwise, complete it, but start at the beginning of *that* word
-				parse_short_opt "$word"
+					optlen=0
-				# The last option takes an argument...
-				if [[ "$state" != 'normal' ]]; then
-					if [[ "$optlen" -ne "${#word}" ]]; then
-						# If it's contained within the word, we won't complete it, revert to "normal"
-						state=normal
-					else
-						# Otherwise, complete it, but start at the beginning of *that* word
-						optlen=0
-					fi
 				fi
 			fi
 		fi
@@ -129,48 +134,48 @@ _rgbasm_completions() {
 
 	# Parse current word
 	# Careful that it might look like an option, so use `--` aggressively!
-	local cur_word="${COMP_WORDS[$COMP_CWORD]}"
+	local cur_word="${COMP_WORDS[$i]}"
 
 	# Process options, as short ones may change the state
-	if $opt_ena && [[ "$state" = 'normal' && "${cur_word:0:1}" = '-' ]]; then
+	if $opt_ena && [[ "$state" = 'normal' && "$cur_word" = '-'* ]]; then
 		# We might want to complete to an option or an arg to that option
 		# Parse the option word to check
 		# There's no whitespace in the option names, so we can ride a little dirty...
 
 		# Is this a long option?
-		if [[ "${cur_word:1:1}" = '-' ]]; then
+		if [[ "$cur_word" = '--'* ]]; then
 			# It is, try to complete one
-			COMPREPLY+=( $(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}") )
+			mapfile -t COMPREPLY < <(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}")
+			return 0
+		elif [[ "$cur_word" = '-M'[GPQT] ]]; then
+			# These options act like long opts with no arguments, so return them and exactly them
+			COMPREPLY=( "$cur_word" )
 			return 0
 		else
 			# Short options may be grouped, parse them to determine what to complete
-			# The `-M?` ones may not be followed by anything
+			parse_short_opt "$cur_word"
-			if [[ "$1" != "-M"[GPTQ] ]]; then
-				parse_short_opt "$cur_word"
-				# We got some short options that behave like long ones
-				COMPREPLY+=( $(compgen -W '-MG -MP -MT -MQ' -- "$cur_word") )
 
-				if [[ "$state" = 'normal' ]]; then
+			if [[ "$state" = 'normal' ]]; then
-					COMPREPLY+=( $(compgen -W "${!opts[*]}" -P "$cur_word" '') )
+				mapfile -t COMPREPLY < <(compgen -W "${!opts[*]}" -P "$cur_word" ''; compgen -W '-MG -MP -MQ -MT' "$cur_word")
-					return 0
+				return 0
-				elif [[ "$optlen" = "${#cur_word}" && "$state" != "warning" ]]; then
+			elif [[ "$optlen" = "${#cur_word}" && "$state" != "warning" ]]; then
-					# This short option group only awaits its argument!
+				# This short option group only awaits its argument!
-					# Post the option group as-is as a reply so that Readline inserts a space,
+				# Post the option group as-is as a reply so that Readline inserts a space,
-					# so that the next completion request switches to the argument
+				# so that the next completion request switches to the argument
-					# An exception is made for warnings, since it's idiomatic to stick them to the
+				# An exception is made for warnings, since it's idiomatic to stick them to the
-					# `-W`, and it doesn't break anything.
+				# `-W`, and it doesn't break anything.
-					COMPREPLY+=( "$cur_word" )
+				COMPREPLY=( "$cur_word" )
-					return 0
+				return 0
-				fi
 			fi
 		fi
 	fi
 
+	COMPREPLY=()
 	case "$state" in
 		unk) # Return with no replies: no idea what to complete!
 			;;
 		warning)
-			COMPREPLY+=( $(compgen -W "
+			mapfile -t COMPREPLY < <(compgen -W "
 				assert
 				backwards-for
 				builtin-args
@@ -188,11 +193,12 @@ _rgbasm_completions() {
 				shift
 				shift-amount
 				truncation
+				unmapped-char
 				user
 				all
 				extra
 				everything
-				error" -P "${cur_word:0:$optlen}" -- "${cur_word:$optlen}") )
+				error" -P "${cur_word:0:$optlen}" -- "${cur_word:$optlen}")
 			;;
 		normal) # Acts like a glob...
 			state="glob-*.asm *.inc *.sm83"
@@ -209,6 +215,10 @@ _rgbasm_completions() {
 			done < <(compgen -A directory -- "${cur_word:$optlen}")
 			compopt -o filenames
 			;;
+		*)
+			echo >&2 "Internal completion error: invalid state \"$state\", please report this bug"
+			return 1
+			;;
 	esac
 }
 

contrib/bash_compl/_rgbfix.bash

@@ -1,10 +1,8 @@
-#/usr/bin/env bash
+#!/usr/bin/env bash
 
 # Same notes as RGBASM
 
 _rgbfix_completions() {
-	COMPREPLY=()
-
 	# Format: "long_opt:state_after"
 	# Empty long opt = it doesn't exit
 	# See the `state` variable below for info about `state_after`
@@ -54,7 +52,7 @@ _rgbfix_completions() {
 		optlen=0
 	}
 
-	for (( i = 1; i < $COMP_CWORD; i++ )); do
+	for (( i = 1; i < COMP_CWORD; i++ )); do
 		local word="${COMP_WORDS[$i]}"
 
 		# If currently processing an argument, skip this word
@@ -70,7 +68,7 @@ _rgbfix_completions() {
 		fi
 
 		# Check if it's a long option
-		if [[ "${word:0:2}" = '--' ]]; then
+		if [[ "$word" = '--'* ]]; then
 			# If the option is unknown, assume it takes no arguments: keep the state at "normal"
 			for long_opt in "${opts[@]}"; do
 				if [[ "$word" = "--${long_opt%%:*}" ]]; then
@@ -86,7 +84,7 @@ _rgbfix_completions() {
 				fi
 			done
 		# Check if it's a short option
-		elif [[ "${word:0:1}" = '-' ]]; then
+		elif [[ "$word" = '-'* ]]; then
 			parse_short_opt "$word"
 			# The last option takes an argument...
 			if [[ "$state" != 'normal' ]]; then
@@ -103,25 +101,25 @@ _rgbfix_completions() {
 
 	# Parse current word
 	# Careful that it might look like an option, so use `--` aggressively!
-	local cur_word="${COMP_WORDS[$COMP_CWORD]}"
+	local cur_word="${COMP_WORDS[$i]}"
 
 	# Process options, as short ones may change the state
-	if $opt_ena && [[ "$state" = 'normal' && "${cur_word:0:1}" = '-' ]]; then
+	if $opt_ena && [[ "$state" = 'normal' && "$cur_word" = '-'* ]]; then
 		# We might want to complete to an option or an arg to that option
 		# Parse the option word to check
 		# There's no whitespace in the option names, so we can ride a little dirty...
 
 		# Is this a long option?
-		if [[ "${cur_word:1:1}" = '-' ]]; then
+		if [[ "$cur_word" = '--'* ]]; then
 			# It is, try to complete one
-			COMPREPLY+=( $(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}") )
+			mapfile -t COMPREPLY < <(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}")
 			return 0
 		else
 			# Short options may be grouped, parse them to determine what to complete
 			parse_short_opt "$cur_word"
 
 			if [[ "$state" = 'normal' ]]; then
-				COMPREPLY+=( $(compgen -W "${!opts[*]}" -P "$cur_word" '') )
+				mapfile -t COMPREPLY < <(compgen -W "${!opts[*]}" -P "$cur_word" '')
 				return 0
 			elif [[ "$optlen" = "${#cur_word}" && "$state" != "warning" ]]; then
 				# This short option group only awaits its argument!
@@ -129,22 +127,25 @@ _rgbfix_completions() {
 				# so that the next completion request switches to the argument
 				# An exception is made for warnings, since it's idiomatic to stick them to the
 				# `-W`, and it doesn't break anything.
-				COMPREPLY+=( "$cur_word" )
+				COMPREPLY=( "$cur_word" )
 				return 0
 			fi
 		fi
 	fi
 
+	COMPREPLY=()
 	case "$state" in
 		unk) # Return with no replies: no idea what to complete!
 			;;
 		fix-spec)
-			COMPREPLY+=( "${cur_word}"{l,h,g,L,H,G} )
+			COMPREPLY=( "${cur_word}"{l,h,g,L,H,G} )
 			;;
 		mbc)
 			local cur_arg="${cur_word:$optlen}"
 			cur_arg="${cur_arg@U}"
-			COMPREPLY=( $(compgen -W "
+			compopt -o nosort # Keep `help` first in the list, mainly
+			mapfile -t COMPREPLY < <(compgen -W "help" -P "${cur_word:0:$optlen}" -- "${cur_word:$optlen}")
+			mapfile -t COMPREPLY -O ${#COMPREPLY} < <(compgen -W "
 				ROM_ONLY
 				MBC1{,+RAM,+RAM+BATTERY}
 				MBC2{,+BATTERY}
@@ -157,8 +158,7 @@ _rgbfix_completions() {
 				BANDAI_TAMA5
 				HUC3
 				HUC1+RAM+BATTERY
-				TPP1_1.0{,+BATTERY}{,+RTC}{,+RUMBLE,+MULTIRUMBLE}" -P "${cur_word:0:$optlen}" -- "`tr 'a-z ' 'A-Z_' <<<"${cur_word/ /_}"`") )
+				TPP1_1.0{,+BATTERY}{,+RTC}{,+RUMBLE,+MULTIRUMBLE}" -P "${cur_word:0:$optlen}" -- "${cur_word/ /_}")
-			COMPREPLY+=( $(compgen -W "help" -P "${cur_word:0:$optlen}" -- "${cur_word:$optlen}") )
 			;;
 		normal) # Acts like a glob...
 			state="glob-*.gb *.gbc *.sgb"
@@ -175,6 +175,10 @@ _rgbfix_completions() {
 			done < <(compgen -A directory -- "${cur_word:$optlen}")
 			compopt -o filenames
 			;;
+		*)
+			echo >&2 "Internal completion error: invalid state \"$state\", please report this bug"
+			return 1
+			;;
 	esac
 }
 

contrib/bash_compl/_rgbgfx.bash

@@ -1,30 +1,33 @@
-#/usr/bin/env bash
+#!/usr/bin/env bash
 
 # Same notes as RGBASM
 
 _rgbgfx_completions() {
-	COMPREPLY=()
-
 	# Format: "long_opt:state_after"
 	# Empty long opt = it doesn't exit
 	# See the `state` variable below for info about `state_after`
 	declare -A opts=(
 		[V]="version:normal"
 		[C]="color-curve:normal"
-		[D]="debug:normal"
-		[h]="horizontal:normal"
 		[m]="mirror-tiles:normal"
 		[u]="unique-tiles:normal"
 		[v]="verbose:normal"
-		[f]="fix:normal"
+		[Z]="columns:normal"
-		[F]="fix-and-save:normal"
+		[a]="attr-map:glob-*.attrmap"
-		[a]="attr-map:*.attrmap"
 		[A]="output-attr-map:normal"
+		[b]="base-tiles:unk"
 		[d]="depth:unk"
-		[o]="output:glob *.2bpp"
+		[L]="slice:unk"
-		[p]="palette:glob *.pal"
+		[N]="nb-tiles:unk"
+		[n]="nb-palettes:unk"
+		[o]="output:glob-*.2bpp"
+		[p]="palette:glob-*.pal"
 		[P]="output-palette:normal"
-		[t]="tilemap:glob *.tilemap"
+		[q]="palette-map:glob-*.palmap"
+		[Q]="output-palette-map:normal"
+		[r]="reverse:unk"
+		[s]="palette-size:unk"
+		[t]="tilemap:glob-*.tilemap"
 		[T]="output-tilemap:normal"
 		[x]="trim-end:unk"
 	)
@@ -57,7 +60,7 @@ _rgbgfx_completions() {
 		optlen=0
 	}
 
-	for (( i = 1; i < $COMP_CWORD; i++ )); do
+	for (( i = 1; i < COMP_CWORD; i++ )); do
 		local word="${COMP_WORDS[$i]}"
 
 		# If currently processing an argument, skip this word
@@ -73,7 +76,7 @@ _rgbgfx_completions() {
 		fi
 
 		# Check if it's a long option
-		if [[ "${word:0:2}" = '--' ]]; then
+		if [[ "$word" = '--'* ]]; then
 			# If the option is unknown, assume it takes no arguments: keep the state at "normal"
 			for long_opt in "${opts[@]}"; do
 				if [[ "$word" = "--${long_opt%%:*}" ]]; then
@@ -89,7 +92,7 @@ _rgbgfx_completions() {
 				fi
 			done
 		# Check if it's a short option
-		elif [[ "${word:0:1}" = '-' ]]; then
+		elif [[ "$word" = '-'* ]]; then
 			parse_short_opt "$word"
 			# The last option takes an argument...
 			if [[ "$state" != 'normal' ]]; then
@@ -106,25 +109,25 @@ _rgbgfx_completions() {
 
 	# Parse current word
 	# Careful that it might look like an option, so use `--` aggressively!
-	local cur_word="${COMP_WORDS[$COMP_CWORD]}"
+	local cur_word="${COMP_WORDS[$i]}"
 
 	# Process options, as short ones may change the state
-	if $opt_ena && [[ "$state" = 'normal' && "${cur_word:0:1}" = '-' ]]; then
+	if $opt_ena && [[ "$state" = 'normal' && "$cur_word" = '-'* ]]; then
 		# We might want to complete to an option or an arg to that option
 		# Parse the option word to check
 		# There's no whitespace in the option names, so we can ride a little dirty...
 
 		# Is this a long option?
-		if [[ "${cur_word:1:1}" = '-' ]]; then
+		if [[ "$cur_word" = '--'* ]]; then
 			# It is, try to complete one
-			COMPREPLY+=( $(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}") )
+			mapfile -t COMPREPLY < <(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}")
 			return 0
 		else
 			# Short options may be grouped, parse them to determine what to complete
 			parse_short_opt "$cur_word"
 
 			if [[ "$state" = 'normal' ]]; then
-				COMPREPLY+=( $(compgen -W "${!opts[*]}" -P "$cur_word" '') )
+				mapfile -t COMPREPLY < <(compgen -W "${!opts[*]}" -P "$cur_word" '')
 				return 0
 			elif [[ "$optlen" = "${#cur_word}" && "$state" != "warning" ]]; then
 				# This short option group only awaits its argument!
@@ -132,12 +135,13 @@ _rgbgfx_completions() {
 				# so that the next completion request switches to the argument
 				# An exception is made for warnings, since it's idiomatic to stick them to the
 				# `-W`, and it doesn't break anything.
-				COMPREPLY+=( "$cur_word" )
+				COMPREPLY=( "$cur_word" )
 				return 0
 			fi
 		fi
 	fi
 
+	COMPREPLY=()
 	case "$state" in
 		unk) # Return with no replies: no idea what to complete!
 			;;
@@ -156,6 +160,10 @@ _rgbgfx_completions() {
 			done < <(compgen -A directory -- "${cur_word:$optlen}")
 			compopt -o filenames
 			;;
+		*)
+			echo >&2 "Internal completion error: invalid state \"$state\", please report this bug"
+			return 1
+			;;
 	esac
 }
 

contrib/bash_compl/_rgblink.bash

@@ -1,10 +1,8 @@
-#/usr/bin/env bash
+#!/usr/bin/env bash
 
 # Same notes as RGBASM
 
 _rgblink_completions() {
-	COMPREPLY=()
-
 	# Format: "long_opt:state_after"
 	# Empty long opt = it doesn't exit
 	# See the `state` variable below for info about `state_after`
@@ -16,6 +14,7 @@ _rgblink_completions() {
 		[w]="wramx:normal"
 		[x]="nopad:normal"
 		[l]="linkerscript:glob-*"
+		[M]="no-sym-in-map:normal"
 		[m]="map:glob-*.map"
 		[n]="sym:glob-*.sym"
 		[O]="overlay:glob-*.gb *.gbc *.sgb"
@@ -52,7 +51,7 @@ _rgblink_completions() {
 		optlen=0
 	}
 
-	for (( i = 1; i < $COMP_CWORD; i++ )); do
+	for (( i = 1; i < COMP_CWORD; i++ )); do
 		local word="${COMP_WORDS[$i]}"
 
 		# If currently processing an argument, skip this word
@@ -68,7 +67,7 @@ _rgblink_completions() {
 		fi
 
 		# Check if it's a long option
-		if [[ "${word:0:2}" = '--' ]]; then
+		if [[ "$word" = '--'* ]]; then
 			# If the option is unknown, assume it takes no arguments: keep the state at "normal"
 			for long_opt in "${opts[@]}"; do
 				if [[ "$word" = "--${long_opt%%:*}" ]]; then
@@ -84,7 +83,7 @@ _rgblink_completions() {
 				fi
 			done
 		# Check if it's a short option
-		elif [[ "${word:0:1}" = '-' ]]; then
+		elif [[ "$word" = '-'* ]]; then
 			parse_short_opt "$word"
 			# The last option takes an argument...
 			if [[ "$state" != 'normal' ]]; then
@@ -101,25 +100,25 @@ _rgblink_completions() {
 
 	# Parse current word
 	# Careful that it might look like an option, so use `--` aggressively!
-	local cur_word="${COMP_WORDS[$COMP_CWORD]}"
+	local cur_word="${COMP_WORDS[$i]}"
 
 	# Process options, as short ones may change the state
-	if $opt_ena && [[ "$state" = 'normal' && "${cur_word:0:1}" = '-' ]]; then
+	if $opt_ena && [[ "$state" = 'normal' && "$cur_word" = '-'* ]]; then
 		# We might want to complete to an option or an arg to that option
 		# Parse the option word to check
 		# There's no whitespace in the option names, so we can ride a little dirty...
 
 		# Is this a long option?
-		if [[ "${cur_word:1:1}" = '-' ]]; then
+		if [[ "$cur_word" = '--'* ]]; then
 			# It is, try to complete one
-			COMPREPLY+=( $(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}") )
+			mapfile -t COMPREPLY < <(compgen -W "${opts[*]%%:*}" -P '--' -- "${cur_word#--}")
 			return 0
 		else
 			# Short options may be grouped, parse them to determine what to complete
 			parse_short_opt "$cur_word"
 
 			if [[ "$state" = 'normal' ]]; then
-				COMPREPLY+=( $(compgen -W "${!opts[*]}" -P "$cur_word" '') )
+				mapfile -t COMPREPLY < <(compgen -W "${!opts[*]}" -P "$cur_word" '')
 				return 0
 			elif [[ "$optlen" = "${#cur_word}" && "$state" != "warning" ]]; then
 				# This short option group only awaits its argument!
@@ -127,12 +126,13 @@ _rgblink_completions() {
 				# so that the next completion request switches to the argument
 				# An exception is made for warnings, since it's idiomatic to stick them to the
 				# `-W`, and it doesn't break anything.
-				COMPREPLY+=( "$cur_word" )
+				COMPREPLY=( "$cur_word" )
 				return 0
 			fi
 		fi
 	fi
 
+	COMPREPLY=()
 	case "$state" in
 		unk) # Return with no replies: no idea what to complete!
 			;;
@@ -151,6 +151,10 @@ _rgblink_completions() {
 			done < <(compgen -A directory -- "${cur_word:$optlen}")
 			compopt -o filenames
 			;;
+		*)
+			echo >&2 "Internal completion error: invalid state \"$state\", please report this bug"
+			return 1
+			;;
 	esac
 }
 

contrib/checkdiff.bash

@@ -25,7 +25,7 @@
 declare -A FILES
 while read -r -d '' file; do
 	FILES["$file"]="true"
-done < <(git diff --name-only -z $1 HEAD)
+done < <(git diff --name-only -z "$1" HEAD)
 
 edited () {
 	${FILES["$1"]:-"false"}
@@ -40,13 +40,13 @@ 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    src/rgbds.5 \
+dependency include/linkdefs.h    man/rgbds.5 \
            "Was the object file format changed?"
 
-dependency src/asm/parser.y      src/asm/rgbasm.5 \
+dependency src/asm/parser.y      man/rgbasm.5 \
            "Was the rgbasm grammar changed?"
 
-dependency include/asm/warning.h src/asm/rgbasm.1 \
+dependency include/asm/warning.h man/rgbasm.1 \
            "Were the rgbasm warnings changed?"
 
 dependency src/asm/object.c      include/linkdefs.h \
@@ -59,27 +59,27 @@ dependency Makefile              CMakeLists.txt \
 dependency Makefile              src/CMakeLists.txt \
            "Did the build process change?"
 
-dependency src/asm/main.c        src/asm/rgbasm.1 \
+dependency src/asm/main.c        man/rgbasm.1 \
            "Did the rgbasm CLI change?"
 dependency src/asm/main.c        contrib/zsh_compl/_rgbasm \
            "Did the rgbasm CLI change?"
 dependency src/asm/main.c        contrib/bash_compl/_rgbasm.bash \
            "Did the rgbasm CLI change?"
-dependency src/link/main.c       src/link/rgblink.1 \
+dependency src/link/main.c       man/rgblink.1 \
            "Did the rgblink CLI change?"
 dependency src/link/main.c       contrib/zsh_compl/_rgblink \
            "Did the rgblink CLI change?"
 dependency src/link/main.c        contrib/bash_compl/_rgblink.bash \
            "Did the rgblink CLI change?"
-dependency src/fix/main.c        src/fix/rgbfix.1 \
+dependency src/fix/main.c        man/rgbfix.1 \
            "Did the rgbfix CLI change?"
 dependency src/fix/main.c        contrib/zsh_compl/_rgbfix \
            "Did the rgbfix CLI change?"
 dependency src/fix/main.c        contrib/bash_compl/_rgbfix.bash \
            "Did the rgbfix CLI change?"
-dependency src/gfx/main.c        src/gfx/rgbgfx.1 \
+dependency src/gfx/main.cpp      man/rgbgfx.1 \
            "Did the rgbgfx CLI change?"
-dependency src/gfx/main.c        contrib/zsh_compl/_rgbgfx \
+dependency src/gfx/main.cpp      contrib/zsh_compl/_rgbgfx \
            "Did the rgbgfx CLI change?"
-dependency src/gfx/main.c        contrib/bash_compl/_rgbgfx.bash \
+dependency src/gfx/main.cpp      contrib/bash_compl/_rgbgfx.bash \
            "Did the rgbgfx CLI change?"

contrib/gbdiff.bash

@@ -23,51 +23,51 @@
 # SOFTWARE.
 
 STATE=0
-diff <(xxd $1) <(xxd $2) | while read -r LINE; do
+diff <(xxd "$1") <(xxd "$2") | while read -r LINE; do
-	if [ $STATE -eq 0 ]; then
+	if [[ $STATE -eq 0 ]]; then
 		# Discard first line (line info)
 		STATE=1
-	elif [ "$LINE" = '---' ]; then
+	elif [[ "$LINE" = '---' ]]; then
 		# Separator between files switches states
-		echo $LINE
+		echo "$LINE"
 		STATE=3
 	elif grep -Eq '^[0-9]+(,[0-9]+)?[cd][0-9]+(,[0-9]+)?' <<< "$LINE"; then
 		# Line info resets the whole thing
 		STATE=1
-	elif [ $STATE -eq 1  -o  $STATE -eq 3 ]; then
+	elif [[ $STATE -eq 1  ||  $STATE -eq 3 ]]; then
 		# Compute the GB address from the ROM offset
 		OFS=$(cut -d ' ' -f 2 <<< "$LINE" | tr -d ':')
 		BANK=$((0x$OFS / 0x4000))
-		ADDR=$((0x$OFS % 0x4000 + ($BANK != 0) * 0x4000))
+		ADDR=$((0x$OFS % 0x4000 + (BANK != 0) * 0x4000))
 		# Try finding the preceding symbol closest to the diff
-		if [ $STATE -eq 1 ]; then
+		if [[ $STATE -eq 1 ]]; then
 			STATE=2
 			SYMFILE=${1%.*}.sym
 		else
 			STATE=4
 			SYMFILE=${2%.*}.sym
 		fi
-		EXTRA=$(if [ -f "$SYMFILE" ]; then
+		EXTRA=$(if [[ -f "$SYMFILE" ]]; then
 			# Read the sym file for such a symbol
 			# Ignore comment lines, only pick matching bank
 			# (The bank regex ignores comments already, make `cut` and `tr` process less lines)
-			grep -Ei $(printf "^%02x:" $BANK) "$SYMFILE" |
+			grep -Ei "$(printf "^%02x:" $BANK)" "$SYMFILE" |
 			 cut -d ';' -f 1 |
 			 tr -d "\r" |
 			 while read -r SYMADDR SYM; do
 				SYMADDR=$((0x${SYMADDR#*:}))
-				if [ $SYMADDR -le $ADDR ]; then
+				if [[ $SYMADDR -le $ADDR ]]; then
-					printf " (%s+%#x)\n" "$SYM" $(($ADDR - $SYMADDR))
+					printf " (%s+%#x)\n" "$SYM" $((ADDR - SYMADDR))
 				fi
 			# TODO: assumes sorted sym files
 			done | tail -n 1
 		fi)
-		printf "%02x:%04x %s\n" $BANK $ADDR $EXTRA
+		printf "%02x:%04x %s\n" $BANK $ADDR "$EXTRA"
 	fi
-	if [ $STATE -eq 2  -o  $STATE -eq 4 ]; then
+	if [[ $STATE -eq 2  ||  $STATE -eq 4 ]]; then
 		OFS=$(cut -d ' ' -f 2 <<< "$LINE" | tr -d ':')
 		BANK=$((0x$OFS / 0x4000))
-		ADDR=$((0x$OFS % 0x4000 + ($BANK != 0) * 0x4000))
+		ADDR=$((0x$OFS % 0x4000 + (BANK != 0) * 0x4000))
 		printf "%s %02x:%04x: %s\n" "${LINE:0:1}" $BANK $ADDR "${LINE#*: }"
 	fi
 done

contrib/zsh_compl/_rgbasm

@@ -25,10 +25,11 @@ _rgbasm_warnings() {
 		'shift:Warn when shifting negative values'
 		'shift-amount:Warn when a shift'\''s operand it negative or \> 32'
 		'truncation:Warn when implicit truncation loses bits'
+		'unmapped-char:Warn on unmapped character'
 		'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
 }
 
@@ -37,22 +38,26 @@ local args=(
 	'(- : * options)'{-V,--version}'[Print version number]'
 
 	'(-E --export-all)'{-E,--export-all}'[Export all symbols]'
-	'(-h --halt-without-nop)'{-h,--halt-without-nop}'[Avoid outputting a `nop` after `halt`]'
+	'(-H --nop-after-halt)'{-H,--nop-after-halt}'[Output a `nop` after `halt`]'
-	'(-L ---preserve-ld)'{-L,--preserve-ld}'[Prevent auto-optimizing `ld` into `ldh`]'
+	'(-h --halt-without-nop)'{-h,--halt-without-nop}'[Prevent outputting a `nop` after `halt`]'
+	'(-L --preserve-ld)'{-L,--preserve-ld}'[Prevent optimizing `ld` into `ldh`]'
+	'(-l --auto-ldh)'{-l,--auto-ldh}'[Optimize `ld` into `ldh`]'
 	'(-v --verbose)'{-v,--verbose}'[Print additional messages regarding progression]'
 	-w'[Disable all warnings]'
 
 	'(-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'
 

contrib/zsh_compl/_rgbgfx

@@ -15,20 +15,25 @@ local args=(
 
 	'(-a --attr-map -A --output-attr-map)'{-A,--output-attr-map}'[Shortcut for -a <file>.attrmap]'
 	'(-C --color-curve)'{-C,--color-curve}'[Generate palettes using GBC color curve]'
-	'(-D --debug)'{-D,--debug}'[Enable debug features]'
-	'(-f --fix -F --fix-and-save)'{-f,--fix}'[Fix input PNG into an indexed image]'
-	'(-f --fix -F --fix-and-save)'{-F,--fix-and-save}'[Like -f but also save CLI params within the PNG]'
-	'(-h --horizontal)'{-h,--horizontal}'[Lay out tiles horizontally instead of vertically]'
 	'(-m --mirror-tiles)'{-m,--mirror-tiles}'[Eliminate mirrored tiles from output]'
 	'(-p --palette -P --output-palette)'{-P,--output-palette}'[Shortcut for -p <file>.pal]'
+	'(-q --palette-map -Q --output-palette-map)'{-Q,--output-palette-map}'[Shortcut for -p <file>.palmap]'
 	'(-t --tilemap -T --output-tilemap)'{-T,--output-tilemap}'[Shortcut for -t <file>.tilemap]'
 	'(-u --unique-tiles)'{-u,--unique-tiles}'[Eliminate redundant tiles]'
-	'(-v --verbose)'{-v,--verbose}'[Enable verbose output]'
+	{-v,--verbose}'[Enable verbose output]'
+	'(-h --horizontal -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'
+	'(-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-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"
+	'(-q --palette-map -Q --output-palette-map)'{-p,--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'
 	'(-x --trim-end)'{-x,--trim-end}'+[Trim end of output by this many tiles]:tile count:'
 

contrib/zsh_compl/_rgblink

@@ -11,6 +11,7 @@ local args=(
 	'(-x --nopad)'{-x,--nopad}'[Disable padding the end of the final file]'
 
 	'(-l --linkerscript)'{-l,--linkerscript}"+[Use a linker script]:linker script:_files -g '*.link'"
+	'(-M --no-sym-in-map)'{-M,--no-sym-in-map}'[Do not output symbol names in map file]'
 	'(-m --map)'{-m,--map}"+[Produce a map file]:map file:_files -g '*.map'"
 	'(-n --sym)'(-n,--sym)"+[Produce a symbol file]:sym file:_files -g '*.sym'"
 	'(-O --overlay)'{-O,--overlay}'+[Overlay sections over on top of bin file]:base overlay:_files'

include/asm/charmap.h

@@ -11,6 +11,8 @@
 
 #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);
@@ -20,4 +22,4 @@ void charmap_Add(char *mapping, uint8_t value);
 size_t charmap_Convert(char const *input, uint8_t *output);
 size_t charmap_ConvertNext(char const **input, uint8_t **output);
 
-#endif /* RGBDS_ASM_CHARMAP_H */
+#endif // RGBDS_ASM_CHARMAP_H

include/asm/fixpoint.h

@@ -11,21 +11,24 @@
 
 #include <stdint.h>
 
-int32_t fix_Callback_PI(void);
+extern uint8_t fixPrecision;
-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_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 */
+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.h

@@ -60,4 +60,4 @@ void fmt_FinishCharacters(struct FormatSpec *fmt);
 void fmt_PrintString(char *buf, size_t bufLen, struct FormatSpec const *fmt, char const *value);
 void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uint32_t value);
 
-#endif /* RGBDS_FORMAT_SPEC_H */
+#endif // RGBDS_FORMAT_SPEC_H

include/asm/fstack.h

@@ -6,9 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*
+// Contains some assembler-wide defines and externs
- * Contains some assembler-wide defines and externs
- */
 
 #ifndef RGBDS_ASM_FSTACK_H
 #define RGBDS_ASM_FSTACK_H
@@ -21,13 +19,13 @@
 
 
 struct FileStackNode {
-	struct FileStackNode *parent; /* Pointer to parent node, for error reporting */
+	struct FileStackNode *parent; // Pointer to parent node, for error reporting
-	/* Line at which the parent context was exited; meaningless for the root level */
+	// Line at which the parent context was exited; meaningless for the root level
 	uint32_t lineNo;
 
-	struct FileStackNode *next; /* Next node in the output linked list */
+	struct FileStackNode *next; // Next node in the output linked list
-	bool referenced; /* If referenced, don't free! */
+	bool referenced; // If referenced, don't free!
-	uint32_t ID; /* Set only if referenced: ID within the object file, -1 if not output yet */
+	uint32_t ID; // Set only if referenced: ID within the object file, -1 if not output yet
 
 	enum {
 		NODE_REPT,
@@ -36,18 +34,19 @@ struct FileStackNode {
 	} type;
 };
 
-struct FileStackReptNode { /* NODE_REPT */
+struct FileStackReptNode { // NODE_REPT
 	struct FileStackNode node;
 	uint32_t reptDepth;
-	/* WARNING: if changing this type, change overflow check in `fstk_Init` */
+	// WARNING: if changing this type, change overflow check in `fstk_Init`
-	uint32_t iters[]; /* REPT iteration counts since last named node, in reverse depth order */
+	uint32_t iters[]; // REPT iteration counts since last named node, in reverse depth order
 };
 
-struct FileStackNamedNode { /* NODE_FILE, NODE_MACRO */
+struct FileStackNamedNode { // NODE_FILE, NODE_MACRO
 	struct FileStackNode node;
-	char name[]; /* File name for files, file::macro name for macros */
+	char name[]; // File name for files, file::macro name for macros
 };
 
+#define DEFAULT_MAX_DEPTH 64
 extern size_t maxRecursionDepth;
 
 struct MacroArgs;
@@ -55,11 +54,12 @@ struct MacroArgs;
 void fstk_Dump(struct FileStackNode const *node, uint32_t lineNo);
 void fstk_DumpCurrent(void);
 struct FileStackNode *fstk_GetFileStack(void);
-/* The lifetime of the returned chars is until reaching the end of that file */
+// The lifetime of the returned chars is until reaching the end of that file
 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
  *                 The pointer's value must be a valid argument to `realloc`, including NULL
@@ -77,6 +77,7 @@ void fstk_RunFor(char const *symName, int32_t start, int32_t stop, int32_t step,
 void fstk_StopRept(void);
 bool fstk_Break(void);
 
+void fstk_NewRecursionDepth(size_t newDepth);
 void fstk_Init(char const *mainPath, size_t maxDepth);
 
-#endif /* RGBDS_ASM_FSTACK_H */
+#endif // RGBDS_ASM_FSTACK_H

include/asm/lexer.h

@@ -11,7 +11,7 @@
 
 #include <stdbool.h>
 
-#define MAXSTRLEN	255
+#define MAXSTRLEN 255
 
 struct LexerState;
 extern struct LexerState *lexerState;
@@ -49,9 +49,7 @@ static inline void lexer_SetGfxDigits(char const digits[4])
 	gfxDigits[3] = digits[3];
 }
 
-/*
+// `path` is referenced, but not held onto..!
- * `path` is referenced, but not held onto..!
- */
 struct LexerState *lexer_OpenFile(char const *path);
 struct LexerState *lexer_OpenFileView(char const *path, char *buf, size_t size, uint32_t lineNo);
 void lexer_RestartRept(uint32_t lineNo);
@@ -83,6 +81,7 @@ struct CaptureBody {
 	size_t size;
 };
 
+void lexer_CheckRecursionDepth(void);
 char const *lexer_GetFileName(void);
 uint32_t lexer_GetLineNo(void);
 uint32_t lexer_GetColNo(void);
@@ -98,4 +97,4 @@ struct DsArgList {
 	struct Expression *args;
 };
 
-#endif /* RGBDS_ASM_LEXER_H */
+#endif // RGBDS_ASM_LEXER_H

include/asm/macro.h

@@ -25,13 +25,14 @@ void macro_AppendArg(struct MacroArgs **args, char *s);
 void macro_UseNewArgs(struct MacroArgs *args);
 void macro_FreeArgs(struct MacroArgs *args);
 char const *macro_GetArg(uint32_t i);
-char *macro_GetAllArgs(void);
+char const *macro_GetAllArgs(void);
 
 uint32_t macro_GetUniqueID(void);
 char const *macro_GetUniqueIDStr(void);
 void macro_SetUniqueID(uint32_t id);
 uint32_t macro_UseNewUniqueID(void);
+uint32_t macro_UndefUniqueID(void);
 void macro_ShiftCurrentArgs(int32_t count);
 uint32_t macro_NbArgs(void);
 
-#endif
+#endif // RGBDS_MACRO_H

include/asm/main.h

@@ -16,9 +16,11 @@
 #include "helpers.h"
 
 extern bool haltnop;
+extern bool warnOnHaltNop;
 extern bool optimizeLoads;
+extern bool warnOnLdOpt;
 extern bool verbose;
-extern bool warnings; /* True to enable warnings, false to disable them. */
+extern bool warnings; // True to enable warnings, false to disable them.
 
 extern FILE *dependfile;
 extern char *targetFileName;
@@ -26,4 +28,4 @@ extern bool generatedMissingIncludes;
 extern bool failedOnMissingInclude;
 extern bool generatePhonyDeps;
 
-#endif /* RGBDS_MAIN_H */
+#endif // RGBDS_MAIN_H

include/asm/opt.h

@@ -10,10 +10,12 @@
 #define RGBDS_OPT_H
 
 #include <stdbool.h>
+#include <stdint.h>
 
-void opt_B(char chars[2]);
+void opt_B(char const chars[2]);
-void opt_G(char chars[4]);
+void opt_G(char const chars[4]);
-void opt_P(uint8_t fill);
+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_Parse(char const *option);
@@ -21,4 +23,4 @@ void opt_Parse(char const *option);
 void opt_Push(void);
 void opt_Pop(void);
 
-#endif
+#endif // RGBDS_OPT_H

include/asm/output.h

@@ -27,4 +27,4 @@ bool out_CreateAssert(enum AssertionType type, struct Expression const *expr,
 		      char const *message, uint32_t ofs);
 void out_WriteObject(void);
 
-#endif /* RGBDS_ASM_OUTPUT_H */
+#endif // RGBDS_ASM_OUTPUT_H

include/asm/rpn.h

@@ -27,17 +27,13 @@ struct Expression {
 	uint32_t rpnPatchSize; // Size the expression will take in the object file
 };
 
-/*
+// Determines if an expression is known at assembly time
- * Determines if an expression is known at assembly time
- */
 static inline bool rpn_isKnown(struct Expression const *expr)
 {
 	return expr->isKnown;
 }
 
-/*
+// Determines if an expression is a symbol suitable for const diffing
- * Determines if an expression is a symbol suitable for const diffing
- */
 static inline bool rpn_isSymbol(const struct Expression *expr)
 {
 	return expr->isSymbol;
@@ -67,4 +63,4 @@ void rpn_CheckRST(struct Expression *expr, const struct Expression *src);
 void rpn_CheckNBit(struct Expression const *expr, uint8_t n);
 int32_t rpn_GetConstVal(struct Expression const *expr);
 
-#endif /* RGBDS_ASM_RPN_H */
+#endif // RGBDS_ASM_RPN_H

include/asm/section.h

@@ -23,12 +23,12 @@ struct Section {
 	char *name;
 	enum SectionType type;
 	enum SectionModifier modifier;
-	struct FileStackNode *src; /* Where the section was defined */
+	struct FileStackNode *src; // Where the section was defined
-	uint32_t fileLine; /* Line where the section was defined */
+	uint32_t fileLine; // Line where the section was defined
 	uint32_t size;
 	uint32_t org;
 	uint32_t bank;
-	uint8_t align;
+	uint8_t align; // Exactly as specified in `ALIGN[]`
 	uint16_t alignOfs;
 	struct Section *next;
 	struct Patch *patches;
@@ -79,4 +79,4 @@ void sect_PopSection(void);
 
 bool sect_IsSizeKnown(struct Section const NONNULL(name));
 
-#endif
+#endif // RGBDS_SECTION_H

include/asm/symbol.h

@@ -32,28 +32,28 @@ enum SymbolType {
 struct Symbol {
 	char name[MAXSYMLEN + 1];
 	enum SymbolType type;
-	bool isExported; /* Whether the symbol is to be exported */
+	bool isExported; // Whether the symbol is to be exported
-	bool isBuiltin;  /* Whether the symbol is a built-in */
+	bool isBuiltin;  // Whether the symbol is a built-in
 	struct Section *section;
-	struct FileStackNode *src; /* Where the symbol was defined */
+	struct FileStackNode *src; // Where the symbol was defined
-	uint32_t fileLine; /* Line where the symbol was defined */
+	uint32_t fileLine; // Line where the symbol was defined
 
 	bool hasCallback;
 	union {
-		/* If sym_IsNumeric */
+		// If sym_IsNumeric
 		int32_t value;
 		int32_t (*numCallback)(void);
-		/* For SYM_MACRO and SYM_EQUS; TODO: have separate fields */
+		// For SYM_MACRO and SYM_EQUS; TODO: have separate fields
 		struct {
 			size_t macroSize;
 			char *macro;
 		};
-		/* For SYM_EQUS */
+		// For SYM_EQUS
 		char const *(*strCallback)(void);
 	};
 
-	uint32_t ID; /* ID of the symbol in the object file (-1 if none) */
+	uint32_t ID; // ID of the symbol in the object file (-1 if none)
-	struct Symbol *next; /* Next object to output in the object file */
+	struct Symbol *next; // Next object to output in the object file
 };
 
 bool sym_IsPC(struct Symbol const *sym);
@@ -98,9 +98,7 @@ static inline bool sym_IsExported(struct Symbol const *sym)
 	return sym->isExported;
 }
 
-/*
+// Get a string equate's value
- * Get a string equate's value
- */
 static inline char const *sym_GetStringValue(struct Symbol const *sym)
 {
 	if (sym->hasCallback)
@@ -123,18 +121,14 @@ struct Symbol *sym_AddVar(char const *symName, int32_t value);
 uint32_t sym_GetPCValue(void);
 uint32_t sym_GetConstantSymValue(struct Symbol const *sym);
 uint32_t sym_GetConstantValue(char const *symName);
-/*
+// Find a symbol by exact name, bypassing expansion checks
- * 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
- * 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
- * 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);
@@ -143,8 +137,8 @@ struct Symbol *sym_RedefString(char const *symName, char const *value);
 void sym_Purge(char const *symName);
 void sym_Init(time_t now);
 
-/* Functions to save and restore the current symbol scope. */
+// Functions to save and restore the current symbol scope.
 char const *sym_GetCurrentSymbolScope(void);
 void sym_SetCurrentSymbolScope(char const *newScope);
 
-#endif /* RGBDS_SYMBOL_H */
+#endif // RGBDS_SYMBOL_H

include/asm/util.h

@@ -18,4 +18,4 @@ char const *printChar(int c);
  */
 size_t readUTF8Char(uint8_t *dest, char const *src);
 
-#endif /* RGBDS_UTIL_H */
+#endif // RGBDS_UTIL_H

include/asm/warning.h

@@ -24,7 +24,7 @@ enum WarningID {
 	WARNING_ASSERT,		      // Assertions
 	WARNING_BACKWARDS_FOR,	      // `for` loop with backwards range
 	WARNING_BUILTIN_ARG,	      // Invalid args to builtins
-	WARNING_CHARMAP_REDEF,        // Charmap entry re-definition
+	WARNING_CHARMAP_REDEF,	      // Charmap entry re-definition
 	WARNING_DIV,		      // Division undefined behavior
 	WARNING_EMPTY_DATA_DIRECTIVE, // `db`, `dw` or `dl` directive without data in ROM
 	WARNING_EMPTY_MACRO_ARG,      // Empty macro argument
@@ -48,6 +48,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)
@@ -90,4 +93,4 @@ _Noreturn void fatalerror(char const *fmt, ...) format_(printf, 1, 2);
  */
 void error(char const *fmt, ...) format_(printf, 1, 2);
 
-#endif
+#endif // WARNING_H

include/defaultinitalloc.hpp

@@ -0,0 +1,39 @@
+/*
+ * Allocator adaptor that interposes construct() calls to convert value-initialization
+ * (which is what you get with e.g. `vector::resize`) into default-initialization (which does not
+ * zero out non-class types).
+ * From
+ * https://stackoverflow.com/questions/21028299/is-this-behavior-of-vectorresizesize-type-n-under-c11-and-boost-container/21028912#21028912
+ */
+
+#ifndef DEFAULT_INIT_ALLOC_H
+#define DEFAULT_INIT_ALLOC_H
+
+#include <memory>
+#include <vector>
+
+template<typename T, typename A = std::allocator<T>>
+class default_init_allocator : public A {
+	using a_t = std::allocator_traits<A>;
+public:
+	template<typename U>
+	struct rebind {
+		using other = default_init_allocator<U, typename a_t::template rebind_alloc<U>>;
+	};
+
+	using A::A; // Inherit the allocator's constructors
+
+	template<typename U>
+	void construct(U *ptr) noexcept(std::is_nothrow_default_constructible_v<U>) {
+		::new (static_cast<void *>(ptr)) U;
+	}
+	template<typename U, typename... Args>
+	void construct(U *ptr, Args &&...args) {
+		a_t::construct(static_cast<A &>(*this), ptr, std::forward<Args>(args)...);
+	}
+};
+
+template<typename T>
+using DefaultInitVec = std::vector<T, default_init_allocator<T>>;
+
+#endif // DEFAULT_INIT_ALLOC_H

include/error.h

@@ -12,10 +12,18 @@
 #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);
 
-#endif /* RGBDS_ERROR_H */
+#ifdef __cplusplus
+}
+#endif
+
+#endif // RGBDS_ERROR_H

include/extern/getopt.h

@@ -26,6 +26,10 @@
 #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;
 
@@ -43,4 +47,8 @@ int musl_getopt_long_only(int argc, char **argv, char const *optstring,
 #define required_argument  1
 #define optional_argument  2
 
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
 #endif

include/extern/utf8decoder.h

@@ -11,4 +11,4 @@
 
 uint32_t decode(uint32_t *state, uint32_t *codep, uint8_t byte);
 
-#endif /* EXTERN_UTF8DECODER_H */
+#endif // EXTERN_UTF8DECODER_H

include/gfx/gb.h

@@ -1,36 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef RGBDS_GFX_GB_H
-#define RGBDS_GFX_GB_H
-
-#include <stdint.h>
-#include "gfx/main.h"
-
-#define XFLIP 0x40
-#define YFLIP 0x20
-
-void raw_to_gb(const struct RawIndexedImage *raw_image, struct GBImage *gb);
-void output_file(const struct Options *opts, const struct GBImage *gb);
-int get_tile_index(uint8_t *tile, uint8_t **tiles, int num_tiles,
-		   int tile_size);
-uint8_t reverse_bits(uint8_t b);
-void xflip(uint8_t *tile, uint8_t *tile_xflip, int tile_size);
-void yflip(uint8_t *tile, uint8_t *tile_yflip, int tile_size);
-int get_mirrored_tile_index(uint8_t *tile, uint8_t **tiles, int num_tiles,
-			    int tile_size, int *flags);
-void create_mapfiles(const struct Options *opts, struct GBImage *gb,
-		     struct Mapfile *tilemap, struct Mapfile *attrmap);
-void output_tilemap_file(const struct Options *opts,
-			 const struct Mapfile *tilemap);
-void output_attrmap_file(const struct Options *opts,
-			 const struct Mapfile *attrmap);
-void output_palette_file(const struct Options *opts,
-			 const struct RawIndexedImage *raw_image);
-
-#endif

include/gfx/main.h

@@ -1,91 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef RGBDS_GFX_MAIN_H
-#define RGBDS_GFX_MAIN_H
-
-#include <png.h>
-#include <stdbool.h>
-#include <stdint.h>
-
-#include "error.h"
-
-struct Options {
-	bool debug;
-	bool verbose;
-	bool hardfix;
-	bool fix;
-	bool horizontal;
-	bool mirror;
-	bool unique;
-	bool colorcurve;
-	int trim;
-	char *tilemapfile;
-	bool tilemapout;
-	char *attrmapfile;
-	bool attrmapout;
-	char *palfile;
-	bool palout;
-	char *outfile;
-	char *infile;
-};
-
-struct RGBColor {
-	uint8_t red;
-	uint8_t green;
-	uint8_t blue;
-};
-
-struct ImageOptions {
-	bool horizontal;
-	int trim;
-	char *tilemapfile;
-	bool tilemapout;
-	char *attrmapfile;
-	bool attrmapout;
-	char *palfile;
-	bool palout;
-};
-
-struct PNGImage {
-	png_struct *png;
-	png_info *info;
-
-	png_byte **data;
-	int width;
-	int height;
-	png_byte depth;
-	png_byte type;
-};
-
-struct RawIndexedImage {
-	uint8_t **data;
-	struct RGBColor *palette;
-	int num_colors;
-	unsigned int width;
-	unsigned int height;
-};
-
-struct GBImage {
-	uint8_t *data;
-	int size;
-	bool horizontal;
-	int trim;
-};
-
-struct Mapfile {
-	uint8_t *data;
-	int size;
-};
-
-extern int depth, colors;
-
-#include "gfx/makepng.h"
-#include "gfx/gb.h"
-
-#endif /* RGBDS_GFX_MAIN_H */

include/gfx/main.hpp

@@ -0,0 +1,123 @@
+/*
+ * 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
+
+#include <array>
+#include <limits.h>
+#include <stdint.h>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "helpers.h"
+
+#include "gfx/rgba.hpp"
+
+struct Options {
+	uint16_t reversedWidth = 0; // -r, in tiles
+	bool reverse() const { return reversedWidth != 0; }
+
+	bool useColorCurve = false; // -C
+	bool allowMirroring = false; // -m
+	bool allowDedup = false; // -u
+	bool columnMajor = false; // -Z, previously -h
+	uint8_t verbosity = 0; // -v
+
+	std::string attrmap{}; // -a, -A
+	std::array<uint8_t, 2> baseTileIDs{0, 0}; // -b
+	enum {
+		NO_SPEC,
+		EXPLICIT,
+		EMBEDDED,
+	} palSpecType = NO_SPEC; // -c
+	std::vector<std::array<Rgba, 4>> palSpec{};
+	uint8_t bitDepth = 2; // -d
+	struct {
+		uint16_t left;
+		uint16_t top;
+		uint16_t width;
+		uint16_t height;
+	} inputSlice{0, 0, 0, 0}; // -L (margins in clockwise order, like CSS)
+	std::array<uint16_t, 2> maxNbTiles{UINT16_MAX, 0}; // -N
+	uint8_t nbPalettes = 8; // -n
+	std::string output{}; // -o
+	std::string palettes{}; // -p, -P
+	std::string palmap{}; // -q, -Q
+	uint8_t nbColorsPerPal = 0; // -s; 0 means "auto" = 1 << bitDepth;
+	std::string tilemap{}; // -t, -T
+	uint64_t trim = 0; // -x
+
+	std::string input{}; // positional arg
+
+	static constexpr uint8_t VERB_NONE = 0; // Normal, no extra output
+	static constexpr uint8_t VERB_CFG = 1; // Print configuration after parsing options
+	static constexpr uint8_t VERB_LOG_ACT = 2; // Log actions before doing them
+	static constexpr uint8_t VERB_INTERM = 3; // Print some intermediate results
+	static constexpr uint8_t VERB_DEBUG = 4; // Internals are logged
+	static constexpr uint8_t VERB_UNMAPPED = 5; // Unused so far
+	static constexpr uint8_t VERB_VVVVVV = 6; // What, can't I have a little fun?
+	format_(printf, 3, 4) void verbosePrint(uint8_t level, char const *fmt, ...) const;
+
+	mutable bool hasTransparentPixels = false;
+	uint8_t maxOpaqueColors() const { return nbColorsPerPal - hasTransparentPixels; }
+};
+
+extern Options options;
+
+/*
+ * Prints the error count, and exits with failure
+ */
+[[noreturn]] void giveUp();
+/*
+ * Prints a warning, and does not change the error count
+ */
+void warning(char const *fmt, ...);
+/*
+ * Prints an error, and increments the error count
+ */
+void error(char const *fmt, ...);
+/*
+ * Prints a fatal error, increments the error count, and gives up
+ */
+[[noreturn]] void fatal(char const *fmt, ...);
+
+struct Palette {
+	// An array of 4 GBC-native (RGB555) colors
+	std::array<uint16_t, 4> colors{UINT16_MAX, UINT16_MAX, UINT16_MAX, UINT16_MAX};
+
+	void addColor(uint16_t color);
+	uint8_t indexOf(uint16_t color) const;
+	uint16_t &operator[](size_t index) { return colors[index]; }
+	uint16_t const &operator[](size_t index) const { return colors[index]; }
+
+	decltype(colors)::iterator begin();
+	decltype(colors)::iterator end();
+	decltype(colors)::const_iterator begin() const;
+	decltype(colors)::const_iterator end() const;
+
+	uint8_t size() const;
+};
+
+namespace detail {
+template<typename T, T... i>
+static constexpr auto flipTable(std::integer_sequence<T, i...>) {
+	return std::array{[](uint8_t byte) {
+		// To flip all the bits, we'll flip both nibbles, then each nibble half, etc.
+		byte = (byte & 0b0000'1111) << 4 | (byte & 0b1111'0000) >> 4;
+		byte = (byte & 0b0011'0011) << 2 | (byte & 0b1100'1100) >> 2;
+		byte = (byte & 0b0101'0101) << 1 | (byte & 0b1010'1010) >> 1;
+		return byte;
+	}(i)...};
+}
+}
+// 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>());
+
+#endif // RGBDS_GFX_MAIN_HPP

include/gfx/makepng.h

@@ -1,21 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#ifndef RGBDS_GFX_PNG_H
-#define RGBDS_GFX_PNG_H
-
-#include "gfx/main.h"
-
-struct RawIndexedImage *input_png_file(const struct Options *opts,
-				       struct ImageOptions *png_options);
-void output_png_file(const struct Options *opts,
-		     const struct ImageOptions *png_options,
-		     const struct RawIndexedImage *raw_image);
-void destroy_raw_image(struct RawIndexedImage **raw_image_ptr_ptr);
-
-#endif /* RGBDS_GFX_PNG_H */

include/gfx/pal_packing.hpp

@@ -0,0 +1,32 @@
+/*
+ * 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
+
+#include <tuple>
+#include <vector>
+
+#include "defaultinitalloc.hpp"
+
+#include "gfx/main.hpp"
+
+struct Palette;
+class ProtoPalette;
+
+namespace packing {
+
+/*
+ * Returns which palette each proto-palette maps to, and how many palettes are necessary
+ */
+std::tuple<DefaultInitVec<size_t>, size_t>
+    overloadAndRemove(std::vector<ProtoPalette> const &protoPalettes);
+
+}
+
+#endif // RGBDS_GFX_PAL_PACKING_HPP

include/gfx/pal_sorting.hpp

@@ -0,0 +1,32 @@
+/*
+ * 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
+
+#include <array>
+#include <assert.h>
+#include <optional>
+#include <png.h>
+#include <vector>
+
+#include "gfx/rgba.hpp"
+
+struct Palette;
+
+namespace sorting {
+
+void indexed(std::vector<Palette> &palettes, int palSize, png_color const *palRGB,
+             png_byte *palAlpha);
+void grayscale(std::vector<Palette> &palettes,
+               std::array<std::optional<Rgba>, 0x8001> const &colors);
+void rgb(std::vector<Palette> &palettes);
+
+}
+
+#endif // RGBDS_GFX_PAL_SORTING_HPP

include/gfx/pal_spec.hpp

@@ -0,0 +1,15 @@
+/*
+ * 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
+
+void parseInlinePalSpec(char const * const arg);
+void parseExternalPalSpec(char const *arg);
+
+#endif // RGBDS_GFX_PAL_SPEC_HPP

include/gfx/process.hpp

@@ -0,0 +1,14 @@
+/*
+ * 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 process();
+
+#endif // RGBDS_GFX_CONVERT_HPP

include/gfx/proto_palette.hpp

@@ -0,0 +1,44 @@
+/*
+ * 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
+
+#include <algorithm>
+#include <array>
+#include <stddef.h>
+#include <stdint.h>
+
+class ProtoPalette {
+	// 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};
+
+public:
+	/*
+	 * Adds the specified color to the set
+	 * Returns false if the set is full
+	 */
+	bool add(uint16_t color);
+
+	enum ComparisonResult {
+		NEITHER,
+		WE_BIGGER,
+		THEY_BIGGER = -1,
+	};
+	ComparisonResult compare(ProtoPalette const &other) const;
+
+	size_t size() const;
+	bool empty() const;
+
+	decltype(_colorIndices)::const_iterator begin() const;
+	decltype(_colorIndices)::const_iterator end() const;
+};
+
+#endif // RGBDS_GFX_PROTO_PALETTE_HPP

include/gfx/reverse.hpp

@@ -0,0 +1,14 @@
+/*
+ * 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
+
+void reverse();
+
+#endif // RGBDS_GFX_REVERSE_HPP

include/gfx/rgba.hpp

@@ -0,0 +1,67 @@
+/*
+ * 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
+
+#include <cstdint>
+#include <stdint.h>
+
+struct Rgba {
+	uint8_t red;
+	uint8_t green;
+	uint8_t blue;
+	uint8_t alpha;
+
+	constexpr Rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a)
+	    : red(r), green(g), blue(b), alpha(a) {}
+	/*
+	 * Constructs the color from a "packed" RGBA representation (0xRRGGBBAA)
+	 */
+	explicit constexpr Rgba(uint32_t rgba = 0)
+	    : red(rgba >> 24), green(rgba >> 16), blue(rgba >> 8), alpha(rgba) {}
+
+	static constexpr Rgba fromCGBColor(uint16_t cgbColor) {
+		constexpr auto _5to8 = [](uint8_t fiveBpp) -> uint8_t {
+			fiveBpp &= 0b11111; // For caller's convenience
+			return fiveBpp << 3 | fiveBpp >> 2;
+		};
+		return {_5to8(cgbColor), _5to8(cgbColor >> 5), _5to8(cgbColor >> 10),
+		        (uint8_t)(cgbColor & 0x8000 ? 0x00 : 0xFF)};
+	}
+
+	/*
+	 * Returns this RGBA as a 32-bit number that can be printed in hex (`%08x`) to yield its CSS
+	 * representation
+	 */
+	uint32_t toCSS() const {
+		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(); }
+
+	/*
+	 * CGB colors are RGB555, so we use bit 15 to signify that the color is transparent instead
+	 * Since the rest of the bits don't matter then, we return 0x8000 exactly.
+	 */
+	static constexpr uint16_t transparent = 0b1'00000'00000'00000;
+
+	static constexpr uint8_t transparency_threshold = 0x10;
+	bool isTransparent() const { return alpha < transparency_threshold; }
+	static constexpr uint8_t opacity_threshold = 0xF0;
+	bool isOpaque() const { return alpha >= opacity_threshold; }
+	/*
+	 * Computes the equivalent CGB color, respects the color curve depending on options
+	 */
+	uint16_t cgbColor() const;
+
+	bool isGray() const { return red == green && green == blue; }
+	uint8_t grayIndex() const;
+};
+
+#endif // RGBDS_GFX_RGBA_HPP

include/hashmap.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Generic hashmap implementation (C++ templates are calling...) */
+// Generic hashmap implementation (C++ templates are calling...)
 #ifndef RGBDS_LINK_HASHMAP_H
 #define RGBDS_LINK_HASHMAP_H
 
@@ -18,10 +18,10 @@
 static_assert(HALF_HASH_NB_BITS * 2 == HASH_NB_BITS, "");
 #define HASHMAP_NB_BUCKETS (1 << HALF_HASH_NB_BITS)
 
-/* HashMapEntry is internal, please do not attempt to use it */
+// HashMapEntry is internal, please do not attempt to use it
 typedef struct HashMapEntry *HashMap[HASHMAP_NB_BUCKETS];
 
-/**
+/*
  * Adds an element to a hashmap.
  * @warning Adding a new element with an already-present key will not cause an
  *          error, this must be handled externally.
@@ -33,7 +33,7 @@ typedef struct HashMapEntry *HashMap[HASHMAP_NB_BUCKETS];
  */
 void **hash_AddElement(HashMap map, char const *key, void *element);
 
-/**
+/*
  * Removes an element from a hashmap.
  * @param map The HashMap to remove the element from
  * @param key The key to search the element with
@@ -41,7 +41,7 @@ void **hash_AddElement(HashMap map, char const *key, void *element);
  */
 bool hash_RemoveElement(HashMap map, char const *key);
 
-/**
+/*
  * Finds an element in a hashmap, and returns a pointer to its value field.
  * @param map The map to consider the elements of
  * @param key The key to search an element for
@@ -49,7 +49,7 @@ bool hash_RemoveElement(HashMap map, char const *key);
  */
 void **hash_GetNode(HashMap const map, char const *key);
 
-/**
+/*
  * Finds an element in a hashmap.
  * @param map The map to consider the elements of
  * @param key The key to search an element for
@@ -58,7 +58,7 @@ void **hash_GetNode(HashMap const map, char const *key);
  */
 void *hash_GetElement(HashMap const map, char const *key);
 
-/**
+/*
  * Executes a function on each element in a hashmap.
  * @param map The map to consider the elements of
  * @param func The function to run. The first argument will be the element,
@@ -67,11 +67,11 @@ void *hash_GetElement(HashMap const map, char const *key);
  */
 void hash_ForEach(HashMap const map, void (*func)(void *, void *), void *arg);
 
-/**
+/*
  * Cleanly empties a hashmap from its contents.
  * This does not `free` the data structure itself!
  * @param map The map to empty
  */
 void hash_EmptyMap(HashMap map);
 
-#endif /* RGBDS_LINK_HASHMAP_H */
+#endif // RGBDS_LINK_HASHMAP_H

include/helpers.h

@@ -31,7 +31,7 @@
 	#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)
-	static inline _Noreturn unreachable_(void) {}
+	static inline _Noreturn void unreachable_(void) {}
 #endif
 
 // Use builtins whenever possible, and shim them otherwise
@@ -93,4 +93,4 @@
 // (Having two instances of `arr` is OK because the contents of `sizeof` are not evaluated.)
 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof *(arr))
 
-#endif /* HELPERS_H */
+#endif // HELPERS_H

include/itertools.hpp

@@ -0,0 +1,88 @@
+/*
+ * 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
+
+#include <tuple>
+#include <utility>
+
+template<typename... Ts>
+static inline void report() {
+	puts(__PRETTY_FUNCTION__);
+}
+
+// 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>
+class Zip {
+	std::tuple<Iters...> _iters;
+
+public:
+	explicit Zip(std::tuple<Iters...> &&iters) : _iters(iters) {}
+
+	Zip &operator++() {
+		std::apply([](auto &&...it) { (++it, ...); }, _iters);
+		return *this;
+	}
+
+	auto operator*() const {
+		return std::apply([](auto &&...it) { return std::tuple<decltype(*it)...>(*it...); },
+		                  _iters);
+	}
+
+	friend auto operator==(Zip const &lhs, Zip const &rhs) {
+		return std::get<0>(lhs._iters) == std::get<0>(rhs._iters);
+	}
+
+	friend auto operator!=(Zip const &lhs, Zip const &rhs) {
+		return std::get<0>(lhs._iters) != std::get<0>(rhs._iters);
+	}
+};
+
+namespace detail {
+template<typename... Containers>
+class ZipContainer {
+	std::tuple<Containers...> _containers;
+
+public:
+	ZipContainer(Containers &&...containers)
+	    : _containers(std::forward<Containers>(containers)...) {}
+
+	auto begin() {
+		return Zip(std::apply(
+		    [](auto &&...containers) {
+			    using std::begin;
+			    return std::make_tuple(begin(containers)...);
+		    },
+		    _containers));
+	}
+
+	auto end() {
+		return Zip(std::apply(
+		    [](auto &&...containers) {
+			    using std::end;
+			    return std::make_tuple(end(containers)...);
+		    },
+		    _containers));
+	}
+};
+
+// Take ownership of objects and rvalue refs passed to us, but not lvalue refs
+template<typename T>
+using Holder = std::conditional_t<std::is_lvalue_reference_v<T>, T,
+                                  std::remove_cv_t<std::remove_reference_t<T>>>;
+}
+
+// Does the same number of iterations as the first container's iterator!
+template<typename... Containers>
+static constexpr auto zip(Containers &&...cs) {
+	return detail::ZipContainer<detail::Holder<Containers>...>(std::forward<Containers>(cs)...);
+}
+
+#endif // RGBDS_ITERTOOLS_HPP

include/link/assign.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Assigning all sections a place */
+// Assigning all sections a place
 #ifndef RGBDS_LINK_ASSIGN_H
 #define RGBDS_LINK_ASSIGN_H
 
@@ -14,14 +14,10 @@
 
 extern uint64_t nbSectionsToAssign;
 
-/**
+// Assigns all sections a slice of the address space
- * Assigns all sections a slice of the address space
- */
 void assign_AssignSections(void);
 
-/**
+// `free`s all assignment memory that was allocated
- * `free`s all assignment memory that was allocated.
- */
 void assign_Cleanup(void);
 
-#endif /* RGBDS_LINK_ASSIGN_H */
+#endif // RGBDS_LINK_ASSIGN_H

include/link/main.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Declarations that all modules use, as well as `main` and related */
+// Declarations that all modules use, as well as `main` and related
 #ifndef RGBDS_LINK_MAIN_H
 #define RGBDS_LINK_MAIN_H
 
@@ -16,10 +16,11 @@
 
 #include "helpers.h"
 
-/* Variables related to CLI options */
+// Variables related to CLI options
 extern bool isDmgMode;
 extern char       *linkerScriptName;
 extern char const *mapFileName;
+extern bool noSymInMap;
 extern char const *symFileName;
 extern char const *overlayFileName;
 extern char const *outputFileName;
@@ -34,7 +35,7 @@ extern bool disablePadding;
 
 struct FileStackNode {
 	struct FileStackNode *parent;
-	/* Line at which the parent context was exited; meaningless for the root level */
+	// Line at which the parent context was exited; meaningless for the root level
 	uint32_t lineNo;
 
 	enum {
@@ -43,21 +44,21 @@ struct FileStackNode {
 		NODE_MACRO,
 	} type;
 	union {
-		char *name; /* NODE_FILE, NODE_MACRO */
+		char *name; // NODE_FILE, NODE_MACRO
-		struct { /* NODE_REPT */
+		struct { // NODE_REPT
 			uint32_t reptDepth;
 			uint32_t *iters;
 		};
 	};
 };
 
-/* Helper macro for printing verbose-mode messages */
+// Helper macro for printing verbose-mode messages
 #define verbosePrint(...)   do { \
 					if (beVerbose) \
 						fprintf(stderr, __VA_ARGS__); \
 				} while (0)
 
-/**
+/*
  * Dump a file stack to stderr
  * @param node The leaf node to dump the context of
  */
@@ -72,7 +73,7 @@ void error(struct FileStackNode const *where, uint32_t lineNo,
 _Noreturn void fatal(struct FileStackNode const *where, uint32_t lineNo,
 		     char const *fmt, ...) format_(printf, 3, 4);
 
-/**
+/*
  * Opens a file if specified, and aborts on error.
  * @param fileName The name of the file to open; if NULL, no file will be opened
  * @param mode The mode to open the file with
@@ -86,4 +87,4 @@ FILE *openFile(char const *fileName, char const *mode);
 					fclose(tmp); \
 			} while (0)
 
-#endif /* RGBDS_LINK_MAIN_H */
+#endif // RGBDS_LINK_MAIN_H

include/link/object.h

@@ -6,37 +6,37 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Declarations related to processing of object (.o) files */
+// Declarations related to processing of object (.o) files
 
 #ifndef RGBDS_LINK_OBJECT_H
 #define RGBDS_LINK_OBJECT_H
 
-/**
+/*
  * Read an object (.o) file, and add its info to the data structures.
  * @param fileName A path to the object file to be read
  * @param i The ID of the file
  */
 void obj_ReadFile(char const *fileName, unsigned int i);
 
-/**
+/*
  * Perform validation on the object files' contents
  */
 void obj_DoSanityChecks(void);
 
-/**
+/*
  * Evaluate all assertions
  */
 void obj_CheckAssertions(void);
 
-/**
+/*
  * Sets up object file reading
  * @param nbFiles The number of object files that will be read
  */
 void obj_Setup(unsigned int nbFiles);
 
-/**
+/*
  * `free`s all object memory that was allocated.
  */
 void obj_Cleanup(void);
 
-#endif /* RGBDS_LINK_OBJECT_H */
+#endif // RGBDS_LINK_OBJECT_H

include/link/output.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Outputting the result of linking */
+// Outputting the result of linking
 #ifndef RGBDS_LINK_OUTPUT_H
 #define RGBDS_LINK_OUTPUT_H
 
@@ -14,22 +14,22 @@
 
 #include "link/section.h"
 
-/**
+/*
  * Registers a section for output.
  * @param section The section to add
  */
 void out_AddSection(struct Section const *section);
 
-/**
+/*
  * Finds an assigned section overlapping another one.
  * @param section The section that is being overlapped
  * @return A section overlapping it
  */
 struct Section const *out_OverlappingSection(struct Section const *section);
 
-/**
+/*
  * Writes all output (bin, sym, map) files.
  */
 void out_WriteFiles(void);
 
-#endif /* RGBDS_LINK_OUTPUT_H */
+#endif // RGBDS_LINK_OUTPUT_H

include/link/patch.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Applying patches to SECTIONs */
+// Applying patches to SECTIONs
 #ifndef RGBDS_LINK_PATCH_H
 #define RGBDS_LINK_PATCH_H
 
@@ -27,15 +27,15 @@ struct Assertion {
 	struct Assertion *next;
 };
 
-/**
+/*
  * Checks all assertions
  * @return true if assertion failed
  */
 void patch_CheckAssertions(struct Assertion *assertion);
 
-/**
+/*
  * Applies all SECTIONs' patches to them
  */
 void patch_ApplyPatches(void);
 
-#endif /* RGBDS_LINK_PATCH_H */
+#endif // RGBDS_LINK_PATCH_H

include/link/script.h

@@ -6,31 +6,33 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Parsing a linker script */
+// 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 */
+#endif // RGBDS_LINK_SCRIPT_H

include/link/sdas_obj.h

@@ -0,0 +1,19 @@
+/*
+ * 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
+#define RGBDS_LINK_SDAS_OBJ_H
+
+#include <stdio.h>
+
+struct FileStackNode;
+
+void sdobj_ReadFile(struct FileStackNode const *fileName, FILE *file);
+
+#endif // RGBDS_LINK_SDAS_OBJ_H

include/link/section.h

@@ -6,11 +6,11 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Declarations manipulating symbols */
+// 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>
@@ -41,27 +41,29 @@ struct Patch {
 };
 
 struct Section {
-	/* Info contained in the object files */
+	// Info contained in the object files
 	char *name;
 	uint16_t size;
 	uint16_t offset;
 	enum SectionType type;
 	enum SectionModifier modifier;
 	bool isAddressFixed;
+	// This `struct`'s address in ROM.
+	// Importantly for fragments, this does not include `offset`!
 	uint16_t org;
 	bool isBankFixed;
 	uint32_t bank;
 	bool isAlignFixed;
 	uint16_t alignMask;
 	uint16_t alignOfs;
-	uint8_t *data; /* Array of size `size`*/
+	uint8_t *data; // Array of size `size`
 	uint32_t nbPatches;
 	struct Patch *patches;
-	/* Extra info computed during linking */
+	// Extra info computed during linking
 	struct Symbol **fileSymbols;
 	uint32_t nbSymbols;
-	struct Symbol const **symbols;
+	struct Symbol **symbols;
-	struct Section *nextu; /* The next "component" of this unionized sect */
+	struct Section *nextu; // The next "component" of this unionized sect
 };
 
 /*
@@ -74,27 +76,27 @@ struct Section {
  */
 void sect_ForEach(void (*callback)(struct Section *, void *), void *arg);
 
-/**
+/*
  * Registers a section to be processed.
  * @param section The section to register.
  */
 void sect_AddSection(struct Section *section);
 
-/**
+/*
  * Finds a section by its name.
  * @param name The name of the section to look for
  * @return A pointer to the section, or NULL if it wasn't found
  */
 struct Section *sect_GetSection(char const *name);
 
-/**
+/*
  * `free`s all section memory that was allocated.
  */
 void sect_CleanupSections(void);
 
-/**
+/*
  * Checks if all sections meet reasonable criteria, such as max size
  */
 void sect_DoSanityChecks(void);
 
-#endif /* RGBDS_LINK_SECTION_H */
+#endif // RGBDS_LINK_SECTION_H

include/link/symbol.h

@@ -6,11 +6,11 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* Declarations manipulating symbols */
+// 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>
 
@@ -19,7 +19,7 @@
 struct FileStackNode;
 
 struct Symbol {
-	/* Info contained in the object files */
+	// Info contained in the object files
 	char *name;
 	enum ExportLevel type;
 	char const *objFileName;
@@ -27,10 +27,11 @@ struct Symbol {
 	int32_t lineNo;
 	int32_t sectionID;
 	union {
+		// Both types must be identical
 		int32_t offset;
 		int32_t value;
 	};
-	/* Extra info computed during linking */
+	// Extra info computed during linking
 	struct Section *section;
 };
 
@@ -46,16 +47,16 @@ void sym_ForEach(void (*callback)(struct Symbol *, void *), void *arg);
 
 void sym_AddSymbol(struct Symbol *symbol);
 
-/**
+/*
  * Finds a symbol in all the defined symbols.
  * @param name The name of the symbol to look for
  * @return A pointer to the symbol, or NULL if not found.
  */
 struct Symbol *sym_GetSymbol(char const *name);
 
-/**
+/*
  * `free`s all symbol memory that was allocated.
  */
 void sym_CleanupSymbols(void);
 
-#endif /* RGBDS_LINK_SYMBOL_H */
+#endif // RGBDS_LINK_SYMBOL_H

include/linkdefs.h

@@ -9,12 +9,12 @@
 #ifndef RGBDS_LINKDEFS_H
 #define RGBDS_LINKDEFS_H
 
+#include <assert.h>
 #include <stdbool.h>
 #include <stdint.h>
 
-#define RGBDS_OBJECT_VERSION_STRING "RGB%1u"
+#define RGBDS_OBJECT_VERSION_STRING "RGB9"
-#define RGBDS_OBJECT_VERSION_NUMBER 9U
+#define RGBDS_OBJECT_REV 9U
-#define RGBDS_OBJECT_REV 8U
 
 enum AssertionType {
 	ASSERT_WARN,
@@ -49,6 +49,7 @@ enum RPNCommand {
 
 	RPN_SHL			= 0x40,
 	RPN_SHR			= 0x41,
+	RPN_USHR		= 0x42,
 
 	RPN_BANK_SYM		= 0x50,
 	RPN_BANK_SECT		= 0x51,
@@ -73,9 +74,50 @@ enum SectionType {
 	SECTTYPE_SRAM,
 	SECTTYPE_OAM,
 
+	// In RGBLINK, this is used for "indeterminate" sections; this is primarily for SDCC
+	// areas, which do not carry any section type info and must be told from the linker script
 	SECTTYPE_INVALID
 };
 
+// Nont-`const` members may be patched in RGBLINK depending on CLI flags
+extern struct SectionTypeInfo {
+	char const *const name;
+	uint16_t const startAddr;
+	uint16_t size;
+	uint32_t const firstBank;
+	uint32_t lastBank;
+} sectionTypeInfo[SECTTYPE_INVALID];
+
+/*
+ * Tells whether a section has data in its object file definition,
+ * depending on type.
+ * @param type The section's type
+ * @return `true` if the section's definition includes data
+ */
+static inline bool sect_HasData(enum SectionType type)
+{
+	assert(type != SECTTYPE_INVALID);
+	return type == SECTTYPE_ROM0 || type == SECTTYPE_ROMX;
+}
+
+/*
+ * Computes a memory region's end address (last byte), eg. 0x7FFF
+ * @return The address of the last byte in that memory region
+ */
+static inline uint16_t endaddr(enum SectionType type)
+{
+	return sectionTypeInfo[type].startAddr + sectionTypeInfo[type].size - 1;
+}
+
+/*
+ * Computes a memory region's number of banks
+ * @return The number of banks, 1 for regions without banking
+ */
+static inline uint32_t nbbanks(enum SectionType type)
+{
+	return sectionTypeInfo[type].lastBank - sectionTypeInfo[type].firstBank + 1;
+}
+
 enum SectionModifier {
 	SECTION_NORMAL,
 	SECTION_UNION,
@@ -84,17 +126,6 @@ enum SectionModifier {
 
 extern char const * const sectionModNames[];
 
-/**
- * Tells whether a section has data in its object file definition,
- * depending on type.
- * @param type The section's type
- * @return `true` if the section's definition includes data
- */
-static inline bool sect_HasData(enum SectionType type)
-{
-	return type == SECTTYPE_ROM0 || type == SECTTYPE_ROMX;
-}
-
 enum ExportLevel {
 	SYMTYPE_LOCAL,
 	SYMTYPE_IMPORT,
@@ -110,45 +141,4 @@ enum PatchType {
 	PATCHTYPE_INVALID
 };
 
-#define BANK_MIN_ROM0  0
+#endif // RGBDS_LINKDEFS_H
-#define BANK_MAX_ROM0  0
-#define BANK_MIN_ROMX  1
-#define BANK_MAX_ROMX  511
-#define BANK_MIN_VRAM  0
-#define BANK_MAX_VRAM  1
-#define BANK_MIN_SRAM  0
-#define BANK_MAX_SRAM  15
-#define BANK_MIN_WRAM0 0
-#define BANK_MAX_WRAM0 0
-#define BANK_MIN_WRAMX 1
-#define BANK_MAX_WRAMX 7
-#define BANK_MIN_OAM   0
-#define BANK_MAX_OAM   0
-#define BANK_MIN_HRAM  0
-#define BANK_MAX_HRAM  0
-
-extern uint16_t startaddr[];
-extern uint16_t maxsize[];
-extern uint32_t bankranges[][2];
-
-/**
- * Computes a memory region's end address (last byte), eg. 0x7FFF
- * @return The address of the last byte in that memory region
- */
-static inline uint16_t endaddr(enum SectionType type)
-{
-	return startaddr[type] + maxsize[type] - 1;
-}
-
-/**
- * Computes a memory region's number of banks
- * @return The number of banks, 1 for regions without banking
- */
-static inline uint32_t nbbanks(enum SectionType type)
-{
-	return bankranges[type][1] - bankranges[type][0] + 1;
-}
-
-extern char const * const typeNames[SECTTYPE_INVALID];
-
-#endif /* RGBDS_LINKDEFS_H */

include/opmath.h

@@ -16,5 +16,6 @@ int32_t op_modulo(int32_t dividend, int32_t divisor);
 int32_t op_exponent(int32_t base, uint32_t power);
 int32_t op_shift_left(int32_t value, int32_t amount);
 int32_t op_shift_right(int32_t value, int32_t amount);
+int32_t op_shift_right_unsigned(int32_t value, int32_t amount);
 
-#endif /* RGBDS_OP_MATH_H */
+#endif // RGBDS_OP_MATH_H

include/platform.h

@@ -6,7 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/* platform-specific hacks */
+// platform-specific hacks
 
 #ifndef RGBDS_PLATFORM_H
 #define RGBDS_PLATFORM_H
@@ -20,20 +20,20 @@
 # include <strings.h>
 #endif
 
-/* MSVC has deprecated strdup in favor of _strdup */
+// MSVC has deprecated strdup in favor of _strdup
 #ifdef _MSC_VER
 # define strdup _strdup
 #endif
 
-/* MSVC prefixes the names of S_* macros with underscores,
+// MSVC prefixes the names of S_* macros with underscores,
-   and doesn't define any S_IS* macros. Define them ourselves */
+// and doesn't define any S_IS* macros; define them ourselves
 #ifdef _MSC_VER
 # define S_IFMT _S_IFMT
 # define S_IFDIR _S_IFDIR
 # define S_ISDIR(mode) (((mode) & S_IFMT) == S_IFDIR)
 #endif
 
-/* MSVC doesn't use POSIX types or defines for `read` */
+// MSVC doesn't use POSIX types or defines for `read`
 #ifdef _MSC_VER
 # include <io.h>
 # define STDIN_FILENO 0
@@ -46,12 +46,14 @@
 # include <unistd.h>
 #endif
 
-/* MSVC doesn't support `[static N]` for array arguments from C99 */
+// MSVC doesn't support `[static N]` for array arguments from C99 or C11
 #ifdef _MSC_VER
 # define MIN_NB_ELMS(N)
+# define ARR_QUALS(...)
 # define NONNULL(ptr) *ptr
 #else
 # define MIN_NB_ELMS(N) static (N)
+# define ARR_QUALS(...) __VA_ARGS__
 # define NONNULL(ptr) ptr[static 1]
 #endif
 
@@ -73,4 +75,4 @@
 # define setmode(fd, mode) ((void)0)
 #endif
 
-#endif /* RGBDS_PLATFORM_H */
+#endif // RGBDS_PLATFORM_H

include/version.h

@@ -9,10 +9,18 @@
 #ifndef EXTERN_VERSION_H
 #define EXTERN_VERSION_H
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #define PACKAGE_VERSION_MAJOR 0
-#define PACKAGE_VERSION_MINOR 5
+#define PACKAGE_VERSION_MINOR 6
-#define PACKAGE_VERSION_PATCH 2
+#define PACKAGE_VERSION_PATCH 0
 
 char const *get_package_version_string(void);
 
-#endif /* EXTERN_VERSION_H */
+#ifdef __cplusplus
+}
+#endif
+
+#endif // EXTERN_VERSION_H

man/gbz80.7

@@ -171,8 +171,8 @@ and
 .It Sx JP HL
 .It Sx JP n16
 .It Sx JP cc,n16
-.It Sx JR e8
+.It Sx JR n16
-.It Sx JR cc,e8
+.It Sx JR cc,n16
 .It Sx RET cc
 .It Sx RET
 .It Sx RETI
@@ -754,22 +754,34 @@ Cycles: 1
 Bytes: 1
 .Pp
 Flags: None affected.
-.Ss JR e8
+.Ss JR n16
-Relative Jump by adding
+Relative Jump to address
-.Ar e8
+.Ar n16 .
-to the address of the instruction following the
+The address is encoded as a signed 8-bit offset from the address immediately following the
-.Sy JR .
+.Ic JR
-To clarify, an operand of 0 is equivalent to no jumping.
+instruction, so the target address
+.Ar n16
+must be between
+.Sy -128
+and
+.Sy 127
+bytes away.
+For example:
+.Bd -literal -offset indent
+    JR Label  ; no-op; encoded offset of 0
+Label:
+    JR Label  ; infinite loop; encoded offset of -2
+.Ed
 .Pp
 Cycles: 3
 .Pp
 Bytes: 2
 .Pp
 Flags: None affected.
-.Ss JR cc,e8
+.Ss JR cc,n16
-Relative Jump by adding
+Relative Jump to address
-.Ar e8
+.Ar n16
-to the current address if condition
+if condition
 .Ar cc
 is met.
 .Pp

man/rgbasm.1

@@ -13,31 +13,32 @@
 .Nd Game Boy assembler
 .Sh SYNOPSIS
 .Nm
-.Op Fl EhLVvw
+.Op Fl EHhLlVvw
 .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
+.Ar asmfile
 .Sh DESCRIPTION
 The
 .Nm
 program creates an RGB object file from an assembly source file.
 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
@@ -55,9 +56,9 @@ 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
 Add a string symbol to the compiled source code.
 This is equivalent to
-.Ql Ar name Ic EQUS \(dq Ns Ar value Ns \(dq
+.Ql Ar name Ic EQUS No \(dq Ns Ar value Ns \(dq
 in code, or
-.Ql Ar name Ic EQUS \(dq1\(dq
+.Ql Ar name Ic EQUS No \(dq1\(dq
 if
 .Ar value
 is not specified.
@@ -66,25 +67,55 @@ Export all labels, including unreferenced and local labels.
 .It Fl g Ar chars , Fl Fl gfx-chars Ar chars
 Change the four characters used for gfx constants.
 The defaults are 0123.
-.It Fl h , Fl Fl halt-without-nop
+.It Fl H , Fl Fl nop-after-halt
 By default,
 .Nm
 inserts a
 .Ic nop
 instruction immediately after any
 .Ic halt
-instruction.
+instruction,
+but this has been deprecated and prints a warning message the first time it occurs.
 The
-.Fl h
+.Fl H
-option disables this behavior.
+option opts into this insertion,
-.It Fl i Ar path , Fl Fl include Ar path
+so no warning will be printed.
-Add an include path.
+.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
+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
+first looks up the provided path from its working directory; if this fails, it tries again from each of the
+.Dq include path
+directories, in the order they were provided.
 .It Fl L , Fl Fl preserve-ld
-Disable the optimization that turns loads of the form
+By default,
+.Nm
+optimizes loads of the form
 .Ic LD [$FF00+n8],A
 into the opcode
-.Ic LDH [$FF00+n8],A
+.Ic LDH [$FF00+n8],A ,
-in order to have full control of the result in the final ROM.
+but this has been deprecated and prints a warning message the first time it occurs.
+The
+.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
 Print
 .Xr make 1
@@ -97,6 +128,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
@@ -127,11 +159,25 @@ characters, essentially
 .Sq $ .
 .It Fl o Ar out_file , Fl Fl output Ar out_file
 Write an object file to the given filename.
+.It Fl P Ar include_file , Fl Fl preinclude Ar include_file
+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 Fl pad-value Ar pad_value
 When padding an image, pad with this value.
 The default is 0x00.
+.It Fl Q Ar fix_precision , Fl 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
-Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
+Specifies the recursion depth past which RGBASM will assume being in an infinite loop.
+The default is 64.
 .It Fl V , Fl Fl version
 Print the version of the program and exit.
 .It Fl v , Fl Fl verbose
@@ -274,6 +320,19 @@ warns when an N-bit value's absolute value is 2**N or greater.
 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=
+Warn when a character goes through charmap conversion but has no defined mapping.
+.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 .
 .It Fl Wno-user
 Warn when the
 .Ic WARN

man/rgbasm.5

@@ -1,3 +1,4 @@
+'\" e
 .\"
 .\" This file is part of RGBDS.
 .\"
@@ -17,7 +18,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
@@ -56,27 +57,25 @@ and ending with
 .Ql */ .
 It can be split across multiple lines, or occur in the middle of an expression:
 .Bd -literal -offset indent
-X = /* the value of x
+DEF X = /* the value of x
-       should be 3 */ 3
+           should be 3 */ 3
 .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 $
@@ -84,7 +83,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
@@ -169,20 +168,20 @@ 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
@@ -207,13 +206,14 @@ section.
 The instructions in the macro-language generally require constant expressions.
 .Ss Numeric formats
 There are a number of numeric formats.
-.Bl -column -offset indent "Fixed point (Q16.16)" "Prefix"
+.Bl -column -offset indent "Precise fixed-point" "Prefix"
 .It Sy Format type Ta Sy Prefix Ta Sy Accepted characters
 .It Hexadecimal Ta $ Ta 0123456789ABCDEF
 .It Decimal Ta none Ta 0123456789
 .It Octal Ta & Ta 01234567
 .It Binary Ta % Ta 01
-.It Fixed point (Q16.16) Ta none Ta 01234.56789
+.It Fixed-point Ta none Ta 01234.56789
+.It Precise fixed-point Ta none Ta 12.34q8
 .It Character constant Ta none Ta \(dqABYZ\(dq
 .It Gameboy graphics Ta \` Ta 0123
 .El
@@ -251,7 +251,9 @@ A great number of operators you can use in expressions are available (listed fro
 .It Li ** Ta Exponent
 .It Li ~ + - Ta Unary complement/plus/minus
 .It Li * / % Ta Multiply/divide/modulo
-.It Li << >> Ta Shift left/right
+.It Li << Ta Shift left
+.It Li >> Ta Signed shift right (sign-extension)
+.It Li >>> Ta Unsigned shift right (zero-extension)
 .It Li & \&| ^ Ta Binary and/or/xor
 .It Li + - Ta Add/subtract
 .It Li != == <= >= < > Ta Comparison
@@ -298,9 +300,19 @@ and
 .Ic \&!
 returns 1 if the operand was 0, and 0 otherwise.
 .Ss Fixed-point expressions
-Fixed-point numbers are basically normal (32-bit) integers, which count 65536ths instead of entire units, offering better precision than integers but limiting the range of values.
+Fixed-point numbers are basically normal (32-bit) integers, which count fractions instead of whole numbers.
-The upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths).
+They offer better precision than integers but limit the range of values.
-Since they are still akin to integers, you can use them in normal integer expressions, and some integer operators like
+By default, the upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths).
+The default number of fractional bits can be changed with the
+.Fl Q
+command-line option.
+You can also specify a precise fixed-point value by appending a
+.Dq q
+to it followed by the number of fractional bits, such as
+.Ql 12.34q8 .
+.Pp
+Since fixed-point values are still just integers, you can use them in normal integer expressions.
+Some integer operators like
 .Sq +
 and
 .Sq -
@@ -314,8 +326,9 @@ delim $$
 .EN
 .Bl -column -offset indent "ATAN2(x, y)"
 .It Sy Name Ta Sy Operation
-.It Fn DIV x y Ta $x \[di] y$
+.It Fn DIV x y Ta Fixed-point division $( x \[di] y ) \[mu] ( 2 ^ precision )$
-.It Fn MUL x y Ta $x \[mu] y$
+.It Fn MUL x y Ta Fixed-point multiplication $( x \[mu] y ) \[di] ( 2 ^ precision )$
+.It Fn FMOD x y Ta Fixed-point modulo $( x % y ) \[di] ( 2 ^ precision )$
 .It Fn POW x y Ta $x$ to the $y$ power
 .It Fn LOG x y Ta Logarithm of $x$ to the base $y$
 .It Fn ROUND x Ta Round $x$ to the nearest integer
@@ -333,44 +346,53 @@ delim $$
 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 (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 (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 (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
@@ -378,9 +400,9 @@ 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
 characters will be included as-is, without needing to escape them with
-.Ql \[rs]r
+.Ql \er
 or
-.Ql \[rs]n .
+.Ql \en .
 .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!
@@ -459,6 +481,11 @@ 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 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 Returns the size of the section named
 .Ar arg .
 The result is not constant, since only RGBLINK can compute its value.
@@ -942,9 +969,9 @@ assuming the section ends up at
 .Ad $80C0 :
 .Bd -literal -offset indent
 SECTION "Player tiles", VRAM
-PlayerTiles:
+vPlayerTiles:
     ds 6 * 16
-.end
+\&.end
 .Ed
 .Pp
 A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
@@ -998,7 +1025,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
@@ -1051,7 +1078,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
@@ -1116,7 +1143,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
@@ -1128,7 +1155,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
@@ -1210,14 +1237,16 @@ The example above defines
 .Ql MyMacro
 as a new macro.
 String constants are not expanded within the name of the macro.
-You may use the older syntax
+.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.
+following the macro's name, string constants may be expanded for the name.)
-With the older syntax, string constants may be expanded for the name.
 .Pp
 Macros can't be exported or imported.
 .Pp
@@ -1235,18 +1264,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.
@@ -1307,7 +1336,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.
@@ -1321,13 +1350,11 @@ DEF AOLer    EQUS  "Me too"
 String constants are not expanded within the symbol names.
 .Ss Predeclared symbols
 The following symbols are defined by the assembler:
-.Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"
+.Bl -column -offset indent "__ISO_8601_LOCAL__" "EQUS"
 .It Sy Name Ta Sy Type Ta Sy Contents
 .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)
@@ -1384,6 +1411,12 @@ Alternatively, you can use
 to store a list of words (16-bit) or
 .Ic DL
 to store a list of double-words/longs (32-bit).
+Both of these write their data in little-endian byte order; for example,
+.Ql dw $CAFE
+is equivalent to
+.Ql db $FE, $CA
+and not
+.Ql db $CA, $FE .
 .Pp
 Strings are handled a little specially: they first undergo charmap conversion (see
 .Sx Character maps ) ,
@@ -1538,19 +1571,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
@@ -1570,18 +1603,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
@@ -1594,14 +1627,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
@@ -1616,15 +1649,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
@@ -1634,34 +1667,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
@@ -1669,11 +1702,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
@@ -1692,9 +1725,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)
@@ -1708,7 +1741,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.
@@ -1732,17 +1765,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
@@ -1795,11 +1827,29 @@ The
 value will be updated by
 .Ar step
 until it reaches or exceeds
-.Ar stop .
+.Ar stop ,
+i.e. it covers the half-open range from
+.Ar start
+(inclusive) to
+.Ar stop
+(exclusive).
+The variable
+.Ar V
+will be assigned this value at the beginning of each new iteration; any changes made to it within the
+.Ic FOR
+loop's body will be overwritten.
+So the symbol
+.Ar V
+need not be already defined before any iterations of the
+.Ic FOR
+loop, but it must be a variable
+.Pq Sx Variables
+if so.
 For example:
 .Bd -literal -offset indent
 FOR V, 4, 25, 5
       PRINT "{d:V} "
+      DEF V *= 2
 ENDR
       PRINTLN "done {d:V}"
 .Ed
@@ -1812,7 +1862,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.
@@ -1933,6 +1983,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 ,
@@ -1985,6 +2042,7 @@ block, all of them but the first one are ignored.
 .Ss Changing options while assembling
 .Ic OPT
 can be used to change some of the options during assembling from within the source, instead of defining them on the command-line.
+.Pq See Xr rgbasm 1 .
 .Pp
 .Ic OPT
 takes a comma-separated list of options as its argument:
@@ -2000,18 +2058,18 @@ POPO
     LD [$FF88], A         ; optimized to use LDH by default
 .Ed
 .Pp
-The options that OPT can modify are currently:
+The options that
-.Cm b , g , p , h , L ,
+.Ic OPT
+can modify are currently:
+.Cm b , g , p , Q , r , h , L ,
 and
 .Cm W .
 The Boolean flag options
-.Cm h
+.Cm H , h , L ,
 and
-.Cm L
+.Cm l
-can be negated as
+can be negated like
-.Ql OPT !h
+.Ql OPT !H
-and
-.Ql OPT !L
 to act like omitting them from the command-line.
 .Pp
 .Ic POPO

man/rgbds.5

@@ -0,0 +1,405 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBDS 5
+.Os
+.Sh NAME
+.Nm rgbds
+.Nd object file format documentation
+.Sh DESCRIPTION
+This is the description of the object files used by
+.Xr rgbasm 1
+and
+.Xr rgblink 1 .
+.Em Please note that the specification is not stable yet.
+RGBDS is still in active development, and some new features require adding more information to the object file, or modifying some fields, both of which break compatibility with older versions.
+.Sh FILE STRUCTURE
+The following types are used:
+.Pp
+.Cm LONG
+is a 32-bit integer stored in little-endian format.
+.Cm BYTE
+is an 8-bit integer.
+.Cm STRING
+is a 0-terminated string of
+.Cm BYTE .
+Brackets after a type
+.Pq e.g. Cm LONG Ns Bq Ar n
+indicate
+.Ar n
+consecutive elements
+.Pq here, Cm LONG Ns s .
+All items are contiguous, with no padding anywhere\(emthis also means that they may not be aligned in the file!
+.Pp
+.Cm REPT Ar n
+indicates that the fields between the
+.Cm REPT
+and corresponding
+.Cm ENDR
+are repeated
+.Ar n
+times.
+.Pp
+All IDs refer to objects within the file; for example, symbol ID $0001 refers to the second symbol defined in
+.Em this
+object file's
+.Sx Symbols
+array.
+The only exception is the
+.Sx Source file info
+nodes, whose IDs are backwards, i.e. source node ID $0000 refers to the
+.Em last
+node in the array, not the first one.
+References to other object files are made by imports (symbols), by name (sections), etc.\(embut never by ID.
+.Ss Header
+.Bl -tag -width Ds -compact
+.It Cm BYTE Ar Magic[4]
+"RGB9"
+.It Cm LONG Ar RevisionNumber
+The format's revision number this file uses.
+.Pq This is always in the same place in all revisions.
+.It Cm LONG Ar NumberOfSymbols
+How many symbols are defined in this object file.
+.It Cm LONG Ar NumberOfSections
+How many sections are defined in this object file.
+.El
+.Ss Source file info
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar NumberOfNodes
+The number of source context nodes contained in this file.
+.It Cm REPT Ar NumberOfNodes
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar ParentID
+ID of the parent node, -1 meaning that this is the root node.
+.Pp
+.Sy Important :
+the nodes are actually written in
+.Sy reverse
+order, meaning the node with ID 0 is the last one in the list!
+.It Cm LONG Ar ParentLineNo
+Line at which the parent node's context was exited; meaningless for the root node.
+.It Cm BYTE Ar Type
+.Bl -column "Value" -compact
+.It Sy Value Ta Sy Meaning
+.It 0 Ta REPT node
+.It 1 Ta File node
+.It 2 Ta Macro node
+.El
+.It Cm IF Ar Type No \(!= 0
+If the node is not a REPT node...
+.Pp
+.Bl -tag -width Ds -compact
+.It Cm STRING Ar Name
+The node's name: either a file name, or the macro's name prefixes by its definition's file name
+.Pq e.g. Ql src/includes/defines.asm::error .
+.El
+.It Cm ELSE
+If the node is a REPT, it also contains the iteration counter of all parent REPTs.
+.Pp
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar Depth
+.It Cm LONG Ar Iter Ns Bq Ar Depth
+The number of REPT iterations, by increasing depth.
+.El
+.It Cm ENDC
+.El
+.It Cm ENDR
+.El
+.Ss Symbols
+.Bl -tag -width Ds -compact
+.It Cm REPT Ar NumberOfSymbols
+.Bl -tag -width Ds -compact
+.It Cm STRING Ar Name
+This symbol's name.
+Local symbols are stored as their full name
+.Pq Ql Scope.symbol .
+.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 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.
+.El
+.It Cm IF Ar Type No \(!= 1
+If the symbol is defined in this object file...
+.Pp
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar NodeID
+Context in which the symbol was defined.
+.It Cm LONG Ar LineNo
+Line number in the context at which the symbol was defined.
+.It Cm LONG Ar SectionID
+The ID of the section in which the symbol is defined.
+If the symbol doesn't belong to any specific section (i.e. it's a constant), this field contains -1.
+.It Cm LONG Ar Value
+The symbol's value.
+If the symbol belongs to a section, this is the offset within that symbol's section.
+.El
+.It Cm ENDC
+.El
+.It Cm ENDR
+.El
+.Ss Sections
+.Bl -tag -width Ds -compact
+.It Cm REPT Ar NumberOfSections
+.Bl -tag -width Ds -compact
+.It Cm STRING Ar Name
+The section's name.
+.It Cm LONG Ar Size
+The section's size, in bytes.
+.It Cm BYTE Ar Type
+Bits 0\(en2 indicate the section's type:
+.Bl -column "Value" -compact
+.It Sy Value Ta Sy Meaning
+.It 0 Ta WRAM0
+.It 1 Ta VRAM
+.It 2 Ta ROMX
+.It 3 Ta ROM0
+.It 4 Ta HRAM
+.It 5 Ta WRAMX
+.It 6 Ta SRAM
+.It 7 Ta OAM
+.El
+.Pp
+Bit\ 7 being set means that the section is a "union"
+.Pq see Do Unionized sections Dc in Xr rgbasm 5 .
+Bit\ 6 being set means that the section is a "fragment"
+.Pq see Do Section fragments Dc in Xr rgbasm 5 .
+These two bits are mutually exclusive.
+.It Cm LONG Ar Address
+Address this section must be placed at.
+This must either be valid for the section's
+.Ar Type
+(as affected by flags like
+.Fl t
+or
+.Fl d
+in
+.Xr rgblink 1 ) ,
+or -1 to indicate that the linker should automatically decide
+.Pq the section is Dq floating .
+.It Cm LONG Ar Bank
+ID of the bank this section must be placed in.
+This must either be valid for the section's
+.Ar Type
+(with the same caveats as for the
+.Ar Address ) ,
+or -1 to indicate that the linker should automatically decide.
+.It Cm BYTE Ar Alignment
+How many bits of the section's address should be equal to
+.Ar AlignOfs ,
+starting from the least-significant bit.
+.It Cm LONG Ar AlignOfs
+Alignment offset.
+Must be strictly less than
+.Ql 1 << Ar Alignment .
+.It Cm IF Ar Type No \(eq 2 || Ar Type No \(eq 3
+If the section has ROM type, it contains data.
+.Pp
+.Bl -tag -width Ds -compact
+.It Cm BYTE Ar Data Ns Bq Size
+The section's raw data.
+Bytes that will be patched over must be present, even though their contents will be overwritten.
+.It Cm LONG Ar NumberOfPatches
+How many patches must be applied to this section's
+.Ar Data .
+.It Cm REPT Ar NumberOfPatches
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar NodeID
+Context in which the patch was defined.
+.It Cm LONG Ar LineNo
+Line number in the context at which the patch was defined.
+.It Cm LONG Ar Offset
+Offset within the section's
+.Ar Data
+at which the patch should be applied.
+Must not be greater than the section's
+.Ar Size
+minus the patch's size
+.Pq see Ar Type No below .
+.It Cm LONG Ar PCSectionID
+ID of the section in which PC is located.
+(This is usually the same section within which the patch is applied, except for e.g.\&
+.Ql LOAD
+blocks, see
+.Do RAM code Dc in Xr rgbasm 5 . )
+.It Cm LONG Ar PCOffset
+Offset of the PC symbol within the section designated by
+.Ar PCSectionID .
+It is expected that PC points to the instruction's first byte for instruction operands (i.e.\&
+.Ql jp @
+must be an infinite loop), and to the patch's first byte otherwise
+.Ql ( db ,
+.Ql dw ,
+.Ql dl ) .
+.It Cm BYTE Ar Type
+.Bl -column "Value" -compact
+.It Sy Value Ta Sy Meaning
+.It 0 Ta Single-byte patch
+.It 1 Ta Little-endian two-byte patch
+.It 2 Ta Little-endian four-byte patch
+.It 3 Ta Single-byte Ql jr
+patch; the patch's value will be subtracted to PC + 2 (i.e.\&
+.Ql jr @
+must be the infinite loop
+.Ql 18 FE ) .
+.El
+.It Cm LONG Ar RPNSize
+Size of the
+.Ar RPNExpr
+below.
+.It Cm BYTE Ar RPNExpr Ns Bq RPNSize
+The patch's value, encoded as a RPN expression
+.Pq see Sx RPN EXPRESSIONS .
+.El
+.It Cm ENDR
+.El
+.It Cm ENDC
+.El
+.El
+.Ss Assertions
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar NumberOfAssertions
+How many assertions this object file contains.
+.It Cm REPT Ar NumberOfAssertions
+Assertions are essentially patches with a message.
+.Pp
+.Bl -tag -width Ds -compact
+.It Cm LONG Ar NodeID
+Context in which the assertions was defined.
+.It Cm LONG Ar LineNo
+Line number in the context at which the assertion was defined.
+.It Cm LONG Ar Offset
+Unused leftover from the patch structure.
+.It Cm LONG Ar PCSectionID
+ID of the section in which PC is located.
+.It Cm LONG Ar PCOffset
+Offset of the PC symbol within the section designated by
+.Ar PCSectionID .
+.It Cm BYTE Ar Type
+Describes what should happen if the expression evaluates to a non-zero value.
+.Bl -column "Value" -compact
+.It Sy Value Ta Sy Meaning
+.It 0 Ta Print a warning message, and continue linking normally.
+.It 1 Ta Print an error message, so linking will fail, but allow other assertions to be evaluated.
+.It 2 Ta Print a fatal error message, and abort immediately.
+.El
+.It Cm LONG Ar RPNSize
+Size of the
+.Ar RPNExpr
+below.
+.It Cm BYTE Ar RPNExpr Ns Bq RPNSize
+The patch's value, encoded as a RPN expression
+.Pq see Sx RPN EXPRESSIONS .
+.It Cm STRING Ar Message
+The message displayed if the expression evaluates to a non-zero value.
+If empty, a generic message is displayed instead.
+.El
+.It Cm ENDR
+.El
+.Ss RPN EXPRESSIONS
+Expressions in the object file are stored as RPN, or
+.Dq Reverse Polish Notation ,
+which is a notation that allows computing arbitrary expressions with just a simple stack.
+For example, the expression
+.Ql 2 5 -
+will first push the value
+.Dq 2
+to the stack, then
+.Dq 5 .
+The
+.Ql -
+operator pops two arguments from the stack, subtracts them, and then pushes back the result
+.Pq Dq 3
+on the stack.
+A well-formed RPN expression never tries to pop from an empty stack, and leaves exactly one value in it at the end.
+.Pp
+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.
+.Bl -column -offset Ds "Value"
+.It Sy Value Ta Sy Meaning
+.It Li $00 Ta Addition operator Pq Ql +
+.It Li $01 Ta Subtraction operator Pq Ql -
+.It Li $02 Ta Multiplication operator Pq Ql *
+.It Li $03 Ta Division operator Pq Ql /
+.It Li $04 Ta Modulo operator Pq Ql %
+.It Li $05 Ta Negation Pq unary Ql -
+.It Li $06 Ta Exponent operator Pq Ql **
+.It Li $10 Ta Bitwise OR operator Pq Ql \&|
+.It Li $11 Ta Bitwise AND operator Pq Ql &
+.It Li $12 Ta Bitwise XOR operator Pq Ql ^
+.It Li $13 Ta Bitwise complement operator Pq unary Ql ~
+.It Li $21 Ta Logical AND operator Pq Ql &&
+.It Li $22 Ta Logical OR operator Pq Ql ||
+.It Li $23 Ta Logical complement operator Pq unary Ql \&!
+.It Li $30 Ta Equality operator Pq Ql ==
+.It Li $31 Ta Non-equality operator Pq Ql !=
+.It Li $32 Ta Greater-than operator Pq Ql >
+.It Li $33 Ta Less-than operator Pq Ql <
+.It Li $34 Ta Greater-than-or-equal operator Pq Ql >=
+.It Li $35 Ta Less-than-or-equal operator Pq Ql <=
+.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 ,
+followed by the
+.Ar symbol Ap s Cm LONG
+ID.
+.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 ,
+followed by the
+.Ar section Ap s Cm STRING
+name.
+.It Li $54 Ta Fn STARTOF section ,
+followed by the
+.Ar section Ap s Cm STRING
+name.
+.It Li $60 Ta Ql ldh
+check.
+Checks if the value is a valid
+.Ql ldh
+operand
+.Pq see Do Load Instructions Dc in Xr gbz80 7 ,
+i.e. that it is between either $00 and $FF, or $FF00 and $FFFF, both inclusive.
+The value is then ANDed with $00FF
+.Pq Ql & $FF .
+.It Li $61 Ta Ql rst
+check.
+Checks if the value is a valid
+.Ql rst
+.Pq see Do RST vec Dc in Xr gbz80 7
+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.
+Followed by the
+.Cm LONG
+integer.
+.It Li $81 Ta A symbol's value.
+Followed by the symbol's
+.Cm LONG
+ID.
+.El
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.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.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .

man/rgbfix.1

@@ -192,7 +192,7 @@ SurvivalKids.gbc
 .Sh TPP1
 TPP1 is a homebrew mapper designed as a functional superset of the common traditional MBCs, allowing larger ROM and RAM sizes combined with other hardware features.
 Its specification, as well as more resources, can be found online at
-.Lk https://github.com/TwitchPlaysPokemon/tpp1 .
+.Lk https://github.com/aaaaaa123456789/tpp1 .
 .Ss MBC name
 The MBC name for TPP1 is more complex than standard mappers.
 It must be followed with the revision number, of the form

man/rgbgfx.1

@@ -0,0 +1,618 @@
+'\" e
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBGFX 1
+.Os
+.Sh NAME
+.Nm rgbgfx
+.Nd Game Boy graphics converter
+.Sh SYNOPSIS
+.Nm
+.Op Fl CmuVZ
+.Op Fl v Op Fl v No ...
+.Op Fl a Ar attrmap | Fl A
+.Op Fl b Ar base_ids
+.Op Fl c Ar color_spec
+.Op Fl d Ar depth
+.Op Fl L Ar slice
+.Op Fl N Ar nb_tiles
+.Op Fl n Ar nb_pals
+.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
+.Ar file
+.Sh DESCRIPTION
+The
+.Nm
+program converts PNG images into data suitable for display on the Game Boy and Game Boy Color, or vice-versa.
+.Pp
+The main function of
+.Nm
+is to divide the input PNG into 8\[tmu]8 pixel
+.Em squares ,
+convert each of those squares into 1bpp or 2bpp tile data, and save all of the tile data in a file.
+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
+is
+.Fl Fl verbose ,
+but
+.Fl Fl ver
+is invalid because it could also be
+.Fl Fl version .
+.Pp
+.Nm
+accepts decimal, binary, and hexadecimal numbers in option arguments.
+Decimal numbers are written as usual; binary numbers must be prefixed with either
+.Ql %
+or
+.Ql 0b ,
+and hexadecimal numbers must be prefixed with either
+.Ql $
+(which will likely need escaping or quoting to avoid being interpreted by the shell), or
+.Ql 0x .
+Leading zeros (after the base prefix, if any) are accepted, and letters are not case-sensitive.
+All of these are equivalent:
+.Ql 42 ,
+.Ql 042 ,
+.Ql 0b00101010 ,
+.Ql 0B101010 ,
+.Ql 0x2A ,
+.Ql 0X2A ,
+.Ql 0x2a .
+.Pp
+The following options are accepted:
+.Bl -tag -width Ds
+.It Fl a Ar attrmap , Fl 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
+.Fl m
+was specified), the bank bit
+.Pq see Fl N ,
+and the palette index.
+See
+.Lk https://gbdev.io/pandocs/Tile_Maps#bg-map-attributes-cgb-mode-only Pan Docs
+for the individual bytes' format.
+The output is written just like the tile map (see
+.Fl t ) ,
+follows the same order
+.Pq Fl Z ,
+and has the same size.
+.It Fl A , Fl Fl output-attr-map
+Same as
+.Fl a Ar path ,
+where
+.Ar path
+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
+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
+Use the specified color palettes instead of having
+.Nm
+automatically determine some.
+.Ar color_spec
+can be one of the following:
+.Bl -tag -width Ds
+.It Sy inline palette spec
+If
+.Ar color_spec
+begins with a hash character
+.Ql # ,
+it is treated as an inline palette specification.
+It should contain a comma-separated list of hexadecimal colors, each beginning with a hash.
+Colors in are accepted either as
+.Ql #rgb
+or
+.Ql #rrggbb
+format.
+Palettes must be separated by a colon or semicolon (the latter may require quoting to avoid special handling by the shell), and spaces are allowed around colons, semicolons and commas; trailing commas and semicolons are allowed.
+See
+.Sx EXAMPLES
+for an example of an inline palette specification.
+.It Sy embedded palette spec
+If
+.Ar color_spec
+is the case-insensitive word
+.Cm embedded ,
+then the first four colors of the input PNG's embedded palette are used.
+It is an error if the PNG is not indexed, or if colors other than these 4 are used.
+.Pq This is different from the default behavior of indexed PNGs, as then unused entries in the embedded palette are ignored, whereas they are not with Fl c Cm embedded .
+.It Sy external palette spec
+Otherwise,
+.Ar color_spec
+is assumed to be an external palette specification.
+The expected format is
+.Ql format:path ,
+where
+.Ar path
+is a path to a file, 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
+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
+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.
+.Pp
+.Ar slice
+must be two number pairs, separated by a colon.
+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 .
+.It Fl m , Fl Fl mirror-tiles
+Deduplicate tiles that are mirrors of each other.
+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.
+Implies
+.Fl u .
+.It Fl N Ar nb_tiles , Fl 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.
+Setting either number to 0 prevents any tiles from being output in that bank.
+.Pp
+If more tiles are generated than can fit in the two banks combined,
+.Nm
+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
+Abort if more than
+.Ar nb_pals
+palettes are generated.
+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
+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
+Output the image's palette set to this file.
+.It Fl P , Fl Fl output-palette
+Same as
+.Fl p Ar path ,
+where
+.Ar path
+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
+Same as
+.Fl q Ar path ,
+where
+.Ar path
+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
+.Dq Sy reverse
+mode.
+In this mode, instead of converting a PNG image into Game Boy data,
+.Nm
+will attempt to reverse the process, and render Game Boy data into an image.
+See
+.Sx REVERSE MODE
+below for details.
+.Pp
+.Ar width
+is the image's width, in tiles
+.Pq including any margins specified by Fl L .
+.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
+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
+.Fl a
+for that.
+Useful in combination with
+.Fl u
+and/or
+.Fl m
+to keep track of duplicate tiles.
+.It Fl T , Fl Fl output-tilemap
+Same as
+.Fl t Ar path ,
+where
+.Ar path
+is the input image's path with the extension set to
+.Pa .tilemap .
+.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.
+.Pp
+Note that if this option is enabled, no guarantee is made on the order in which tiles are output; while it
+.Em should
+be consistent across identical runs of a given
+.Nm
+release, the same is not true for different releases.
+.It Fl V , Fl Fl version
+Print the version of the program and exit.
+.It Fl v , Fl 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
+.It
+.Nm
+prints out its configuration before doing anything.
+.It
+A generic message is printed before doing most actions.
+.It
+Some of the actions' intermediate results are printed.
+.It
+Some internal debug printing is enabled.
+.El
+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
+Do not output the last
+.Ar quantity
+tiles to the tile data file; no other output is affected.
+This is useful for trimming
+.Dq filler
+/ blank squares at the end of an image.
+If fewer than
+.Ar quantity
+tiles would have been emitted, the file will be empty.
+.Pp
+Note that this is done
+.Em after
+deduplication if
+.Fl u
+was enabled, so you probably don't want to use this option in combination with
+.Fl u .
+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
+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
+.Ss At-files
+In a given project, many images are to be converted with different flags.
+The traditional way of solving this problem has been to specify the different flags for each image in the Makefile / build script; this can be inconvenient, as it centralizes all those flags away from the images they concern.
+.Pp
+To avoid these drawbacks,
+.Nm
+supports
+.Dq at-files :
+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:
+.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 ,
+.Sy no shell processing is performed ;
+for example, shell variables are not expanded
+.Ql ( $PWD ,
+.Ql %WINDIR% ,
+etc.).
+In at-files, lines that are empty or contain only whitespace are ignored; lines that begin with a hash sign
+.Pq Ql # ,
+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 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 reads command-line options from
+.Ql tilesets/town.flags
+then
+.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
+At-files can also specify the input image directly, and call for more at-files, both using the regular syntax.
+Note that while
+.Ql --
+can be used in an at-file (with identical semantics), it is only effective inside of it\(emnormal option processing continues in the parent scope.
+.Sh PALETTE SPECIFICATION FORMATS
+The following formats are supported:
+.Bl -tag -width Ds
+.It Cm act
+.Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1070626 Adobe Photoshop color table .
+.It Cm aco
+.Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1055819 Adobe Photoshop color swatch .
+.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
+If you wish for another format to be supported, please open an issue (see
+.Sx BUGS
+below) or contact us, and supply a few sample files.
+.Sh PALETTE GENERATION
+.Nm
+must generate palettes from the colors in the input image, unless
+.Fl c
+was used; in that case, the provided palettes will be used.
+.Sy If the order of colors in the palettes is important to you ,
+for example because you want to use palette swaps, please use
+.Fl c
+to specify the palette explicitly.
+.Pp
+First, if the image contains
+.Em any
+transparent pixel, color #0 of
+.Em all
+palettes will be allocated to it.
+This is done
+.Sy even if palettes were explicitly specified using Fl c ;
+then the specification only covers color #1 onwards.
+.Pq If you do not want this, ask your image editor to remove the alpha channel.
+.Pp
+After generating palettes,
+.Nm
+sorts colors within those palettes using the following rules:
+.EQ
+delim $$
+.EN
+.Bl -bullet -offset indent
+.It
+If the PNG file internally contains a palette (often dubbed an
+.Dq indexed
+PNG), then colors in each output palette will be sorted according to their order in the PNG's palette.
+Any unused entries will be ignored, and only the first entry is considered if there are any duplicates.
+.Po If you want a given color to appear more than once, or an unused color to appear at all, you should specify the palettes explicitly instead using Fl c ;
+.Fl c Cm embedded
+may be appropriate.
+.Pc
+.It
+Otherwise, if the PNG only contains shades of gray, they will be categorized into as many
+.Dq bins
+as there are colors per palette, and the palette is set to these bins.
+The darkest gray will end up in bin #0, and so on; note that this is the opposite of the RGB method below.
+If two distinct grays end up in the same bin, the RGB method is used instead.
+.Pp
+Be careful that
+.Nm
+is picky about what it considers
+.Dq grays :
+the red, green, and blue components of each color must
+.Em all
+be
+.Em exactly
+the same.
+.It
+If none of the above apply, colors are sorted from lightest (first) to darkest (last).
+The definition of luminance that
+.Nm
+uses is
+.Do
+$2126 times red + 7152 times green + 722 times blue$
+.Dc .
+.El
+.EQ
+delim off
+.EN
+.Pp
+Note that the
+.Dq indexed
+behavior depends on an internal detail of how the PNG is saved, specifically its
+.Ql PLTE
+chunk.
+Since few image editors (such as GIMP) expose that detail, this behavior is only kept for compatibility and should be considered deprecated.
+.Sh OUTPUT FILES
+All files output by
+.Nm
+are binary files, and designed to follow the Game Boy and Game Boy Color's native formats.
+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 .
+.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
+.Pq or Dq bitplane .
+The leftmost pixel's color ID is stored in the two bytes' most significant bits, and the rightmost pixel's color ID in their least significant bits.
+.Pp
+When the bit depth
+.Pq Fl d
+is set to 1, the most significant bitplane (second byte) of each row, being all zeros, is simply not output.
+.Ss Palette data
+Palette data is output like a dump of palette memory.
+Each color is written as GBC-native little-endian RGB555, with the unused bit 15 set to 0.
+There is no padding between colors, nor between palettes; however, empty colors in the palettes are output as 0xFFFF.
+.EQ
+delim $$
+.EN
+For example, if 5 palettes are generated with
+.Fl s Cm 4 ,
+the palette data file will be $2 times 4 times 5 = 40$ bytes long, even if some palettes contain less than 3 colors.
+.EQ
+delim off
+.EN
+Note that
+.Fl n
+only caps how many palettes are generated (and thus this file's size), but fewer may be generated still.
+.Ss Tile map data
+A tile map is an array of tile IDs, with one byte per tile ID.
+The first byte always corresponds to the ID of the tile in top-left corner of the input image; the second byte is either the ID of the tile to its right (by default), or below it
+.Pq with Fl Z ;
+and so on, continuing in the same direction.
+Rows / columns (respectively) are stored consecutively, with no padding.
+.Ss Attribute map data
+Attribute maps mirror the format of tile maps, like on the GBC, especially the order in which bytes are output.
+The contents of individual bytes follows the GBC's native format:
+.Bl -column "Bit 2\(en0" "Background Palette number"
+.It Bit 7 Ta BG-to-OAM Priority Ta Set to 0
+.It Bit 6 Ta Vertical Flip Ta 0=Normal, 1=Mirror vertically
+.It Bit 5 Ta Horizontal Flip Ta 0=Normal, 1=Mirror horizontally
+.It Bit 4 Ta Not used Ta Set to 0
+.It Bit 3 Ta Tile VRAM Bank number Ta 0=Bank 0, 1=Bank 1
+.It Bit 2\(en0 Ta Background Palette number Ta BGP0-7
+.El
+.Pp
+Note that if more than 8 palettes are used, only the lowest 3 bits of the palette ID are output.
+.Sh REVERSE MODE
+.Nm
+can produce a PNG image from valid data.
+This may be useful for ripping graphics, recovering lost source images, etc.
+An important caveat on that last one, though: the conversion process is
+.Sy lossy
+both ways, so the
+.Do reversed Dc image won't be perfectly identical to the original\(embut it should be close to a Game Boy's output .
+.Pq Keep in mind that many of consoles output different colors, so there is no true reference rendering.
+.Pp
+When using reverse mode, make sure to pass the same flags that were given when generating the data, especially
+.Fl C , d , N , s , x ,
+and
+.Fl Z .
+.Do Sx At-files Dc may help with this .
+.Nm
+will warn about any inconsistencies it detects.
+.Pp
+Files that are normally outputs
+.Pq Fl a , p , t
+become inputs, and
+.Ar file
+will be written to instead of read from, and thus needs not exist beforehand.
+Any of these inputs not passed is assumed to be some default:
+.Bl -column "attribute map"
+.It palettes Ta Unspecified palette data makes
+.Nm
+assume DMG (monochrome Game Boy) mode: a single palette of 4 grays.
+It is possible to pass palettes using
+.Fl c
+instead of
+.Fl p .
+.It tile data Ta Tile data must be provided, as there is no reasonable assumption to fall back on.
+.It tile map Ta A missing tile map makes
+.Nm
+assume that tiles were not deduplicated, and should be laid out in the order they are stored.
+.It attribute map Ta Without an attribute map,
+.Nm
+assumes that no tiles were mirrored.
+.El
+.Sh NOTES
+Some flags have had their functionality removed.
+.Fl D , f ,
+and
+.Fl F
+are now ignored, and
+.Fl h
+is an alias for the new (and less confusingly named)
+.Fl Z .
+These will be removed and/or repurposed in future versions of
+.Nm ,
+so relying on them is not recommended.
+The same applies to the corresponding long options.
+.Pp
+If you are curious, you may find out that palette generation is an NP-complete problem, so
+.Nm
+does not attempt to find the optimal solution, but instead to find a good one in a reasonable amount of time.
+It is possible to compute the optimal solution externally (using a solver, for example), and then provide it to
+.Nm
+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:
+.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
+.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
+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
+.Pp
+The Game Boy hardware reference
+.Lk https://gbdev.io/pandocs/Rendering.html Pan Docs ,
+particularly the section about graphics.
+.Sh HISTORY
+.Nm
+was originally created by
+.An stag019
+to be included in RGBDS.
+It was later rewritten by
+.An ISSOtm ,
+and is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .

man/rgblink.1

@@ -13,7 +13,7 @@
 .Nd Game Boy linker
 .Sh SYNOPSIS
 .Nm
-.Op Fl dtVvwx
+.Op Fl dMtVvwx
 .Op Fl l Ar linker_script
 .Op Fl m Ar map_file
 .Op Fl n Ar sym_file
@@ -73,6 +73,8 @@ The attributes assigned in the linker script must be consistent with any assigne
 See
 .Xr rgblink 5
 for more information about the linker script format.
+.It Fl M , Fl 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
 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

man/rgblink.5

@@ -14,18 +14,22 @@
 .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.
 .Pp
-A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
+A linker script consists of a series of bank declarations, each optionally followed by a list of section names (in double quotes) or commands.
-They can be lowercase or uppercase, it is ignored.
+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:
+that ends at the end of the line.
+.Pp
 .Bd -literal -offset indent
-ROMX $F ; This is a comment
+; This line is a comment
-  "Functions to read array"
+ROMX $F            ; start a bank
-  ALIGN 8
+  "Some functions" ; a section name
-  "Array aligned to 256 bytes"
+  ALIGN 8          ; a command
+  "Some array"
 
-WRAMX 2
+WRAMX 2            ; start another bank
+  org $d123        ; another command
   "Some variables"
 .Ed
 .Pp
@@ -47,6 +51,19 @@ 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
+.Ql \e\e ,
+.Ql \e" ,
+.Ql \en ,
+.Ql \er ,
+and
+.Ql \et .
+Other backslash escape sequences in
+.Xr rgbasm 5
+are only relevant to assembly code and do not apply in section names.
+.Pp
 When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
 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.
 .Pp

src/.gitignore

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

src/CMakeLists.txt

@@ -6,20 +6,14 @@
 # SPDX-License-Identifier: MIT
 #
 
+configure_file(version.c _version.c ESCAPE_QUOTES)
+
 set(common_src
     "error.c"
     "extern/getopt.c"
-    "version.c"
+    "_version.c"
     )
 
-find_package(PkgConfig)
-if(MSVC OR NOT PKG_CONFIG_FOUND)
-  # fallback to find_package
-  find_package(PNG REQUIRED)
-else()
-  pkg_check_modules(LIBPNG REQUIRED libpng)
-endif()
-
 find_package(BISON REQUIRED)
 set(BISON_FLAGS "-Wall")
 # Set sompe optimization flags on versions that support them
@@ -68,9 +62,16 @@ set(rgbfix_src
     )
 
 set(rgbgfx_src
-    "gfx/gb.c"
+    "gfx/main.cpp"
-    "gfx/main.c"
+    "gfx/pal_packing.cpp"
-    "gfx/makepng.c"
+    "gfx/pal_sorting.cpp"
+    "gfx/pal_spec.cpp"
+    "gfx/process.cpp"
+    "gfx/proto_palette.cpp"
+    "gfx/reverse.cpp"
+    "gfx/rgba.cpp"
+    "extern/getopt.c"
+    "error.c"
     )
 
 set(rgblink_src
@@ -80,8 +81,10 @@ set(rgblink_src
     "link/output.c"
     "link/patch.c"
     "link/script.c"
+    "link/sdas_obj.c"
     "link/section.c"
     "link/symbol.c"
+    "extern/utf8decoder.c"
     "hashmap.c"
     "linkdefs.c"
     "opmath.c"
@@ -95,22 +98,6 @@ foreach(PROG "asm" "fix" "gfx" "link")
   install(TARGETS rgb${PROG} RUNTIME DESTINATION bin)
 endforeach()
 
-set(MANDIR "share/man")
-set(man1 "asm/rgbasm.1"
-         "fix/rgbfix.1"
-         "gfx/rgbgfx.1"
-         "link/rgblink.1")
-set(man5 "asm/rgbasm.5"
-         "link/rgblink.5"
-         "rgbds.5")
-set(man7 "gbz80.7"
-         "rgbds.7")
-
-foreach(SECTION "man1" "man5" "man7")
-  set(DEST "${MANDIR}/${SECTION}")
-  install(FILES ${${SECTION}} DESTINATION ${DEST})
-endforeach()
-
 if(LIBPNG_FOUND) # pkg-config
   target_include_directories(rgbgfx PRIVATE ${LIBPNG_INCLUDE_DIRS})
   target_link_directories(rgbgfx PRIVATE ${LIBPNG_LIBRARY_DIRS})

src/asm/charmap.c

@@ -21,33 +21,29 @@
 
 #include "hashmap.h"
 
-/*
+// Charmaps are stored using a structure known as "trie".
- * Charmaps are stored using a structure known as "trie".
+// Essentially a tree, where each nodes stores a single character's worth of info:
- * Essentially a tree, where each nodes stores a single character's worth of info:
+// whether there exists a mapping that ends at the current character,
- * whether there exists a mapping that ends at the current character,
- */
 struct Charnode {
-	bool isTerminal; /* Whether there exists a mapping that ends here */
+	bool isTerminal; // Whether there exists a mapping that ends here
-	uint8_t value; /* If the above is true, its corresponding value */
+	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 */
+	size_t next[255]; // Indexes of where to go next, 0 = nowhere
 };
 
 #define INITIAL_CAPACITY 32
 
 struct Charmap {
 	char *name;
-	size_t usedNodes; /* How many nodes are being used */
+	size_t usedNodes; // How many nodes are being used
-	size_t capacity; /* How many nodes have been allocated */
+	size_t capacity; // How many nodes have been allocated
-	struct Charnode nodes[]; /* first node is reserved for the root node */
+	struct Charnode nodes[]; // first node is reserved for the root node
 };
 
 static HashMap charmaps;
 
-/*
+// Store pointers to hashmap nodes, so that there is only one pointer to the memory block
- * Store pointers to hashmap nodes, so that there is only one pointer to the memory block
+// that gets reallocated.
- * that gets reallocated.
- */
 static struct Charmap **currentCharmap;
 
 struct CharmapStackEntry {
@@ -96,7 +92,7 @@ struct Charmap *charmap_New(char const *name, char const *baseName)
 		return charmap;
 	}
 
-	/* Init the new charmap's fields */
+	// Init the new charmap's fields
 	if (base) {
 		resizeCharmap(&charmap, base->capacity);
 		charmap->usedNodes = base->usedNodes;
@@ -105,7 +101,7 @@ struct Charmap *charmap_New(char const *name, char const *baseName)
 	} else {
 		resizeCharmap(&charmap, INITIAL_CAPACITY);
 		charmap->usedNodes = 1;
-		initNode(&charmap->nodes[0]); /* Init the root node */
+		initNode(&charmap->nodes[0]); // Init the root node
 	}
 	charmap->name = strdup(name);
 
@@ -169,16 +165,16 @@ void charmap_Add(char *mapping, uint8_t value)
 		if (node->next[c]) {
 			node = &charmap->nodes[node->next[c]];
 		} else {
-			/* Register next available node */
+			// Register next available node
 			node->next[c] = charmap->usedNodes;
-			/* If no more nodes are available, get new ones */
+			// If no more nodes are available, get new ones
 			if (charmap->usedNodes == charmap->capacity) {
 				charmap->capacity *= 2;
 				resizeCharmap(currentCharmap, charmap->capacity);
 				charmap = *currentCharmap;
 			}
 
-			/* Switch to and init new node */
+			// Switch to and init new node
 			node = &charmap->nodes[charmap->usedNodes++];
 			initNode(node);
 		}
@@ -203,12 +199,10 @@ size_t charmap_Convert(char const *input, uint8_t *output)
 
 size_t charmap_ConvertNext(char const **input, uint8_t **output)
 {
-	/*
+	// The goal is to match the longest mapping possible.
-	 * The goal is to match the longest mapping possible.
+	// For that, advance through the trie with each character read.
-	 * For that, advance through the trie with each character read.
+	// If that would lead to a dead end, rewind characters until the last match, and output.
-	 * If that would lead to a dead end, rewind characters until the last match, and output.
+	// If no match, read a UTF-8 codepoint and output that.
-	 * If no match, read a UTF-8 codepoint and output that.
-	 */
 	struct Charmap const *charmap = *currentCharmap;
 	struct Charnode const *node = &charmap->nodes[0];
 	struct Charnode const *match = NULL;
@@ -242,6 +236,7 @@ size_t charmap_ConvertNext(char const **input, uint8_t **output)
 				return 1;
 
 			} else if (**input) { // No match found, but there is some input left
+				int firstChar = **input;
 				// This will write the codepoint's value to `output`, little-endian
 				size_t codepointLen = readUTF8Char(output ? *output : NULL,
 								   *input);
@@ -254,6 +249,15 @@ size_t charmap_ConvertNext(char const **input, uint8_t **output)
 				if (output)
 					*output += codepointLen;
 
+				// Warn if this character is not mapped but any others are
+				if (charmap->usedNodes > 1)
+					warning(WARNING_UNMAPPED_CHAR_1,
+						"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;
 
 			} else { // End of input

src/asm/fixpoint.c

@@ -6,165 +6,110 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*
+// Fixed-point math routines
- * 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"
 
-#define fix2double(i)	((double)((i) / 65536.0))
-#define double2fix(d)	((int32_t)round((d) * 65536.0))
-
-// pi radians == 32768 fixed-point "degrees"
-#define fdeg2rad(f)	((f) * (M_PI / 32768.0))
-#define rad2fdeg(r)	((r) * (32768.0 / M_PI))
-
 #ifndef M_PI
 #define M_PI 3.14159265358979323846
 #endif
 
-/*
+#define fix2double(i, q)	((double)((i) / pow(2.0, q)))
- * Return the _PI symbol value
+#define double2fix(d, q)	((int32_t)round((d) * pow(2.0, q)))
- */
-int32_t fix_Callback_PI(void)
-{
-	warning(WARNING_OBSOLETE, "`_PI` is deprecated; use 3.14159\n");
 
-	return double2fix(M_PI);
+// 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)
- * Print a fixed point value
- */
-void fix_Print(int32_t i)
 {
-	uint32_t u = i;
+	return pow(2.0, fixPrecision);
-	char const *sign = "";
-
-	if (i < 0) {
-		u = -u;
-		sign = "-";
-	}
-
-	printf("%s%" PRIu32 ".%05" PRIu32, sign, u >> 16,
-	       ((uint32_t)(fix2double(u) * 100000 + 0.5)) % 100000);
 }
 
-/*
+int32_t fix_Sin(int32_t i, int32_t q)
- * Calculate sine
- */
-int32_t fix_Sin(int32_t i)
 {
-	return double2fix(sin(fdeg2rad(fix2double(i))));
+	return double2fix(sin(turn2rad(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_Cos(int32_t i, int32_t q)
- * Calculate cosine
- */
-int32_t fix_Cos(int32_t i)
 {
-	return double2fix(cos(fdeg2rad(fix2double(i))));
+	return double2fix(cos(turn2rad(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_Tan(int32_t i, int32_t q)
- * Calculate tangent
- */
-int32_t fix_Tan(int32_t i)
 {
-	return double2fix(tan(fdeg2rad(fix2double(i))));
+	return double2fix(tan(turn2rad(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_ASin(int32_t i, int32_t q)
- * Calculate arcsine
- */
-int32_t fix_ASin(int32_t i)
 {
-	return double2fix(rad2fdeg(asin(fix2double(i))));
+	return double2fix(rad2turn(asin(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_ACos(int32_t i, int32_t q)
- * Calculate arccosine
- */
-int32_t fix_ACos(int32_t i)
 {
-	return double2fix(rad2fdeg(acos(fix2double(i))));
+	return double2fix(rad2turn(acos(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_ATan(int32_t i, int32_t q)
- * Calculate arctangent
- */
-int32_t fix_ATan(int32_t i)
 {
-	return double2fix(rad2fdeg(atan(fix2double(i))));
+	return double2fix(rad2turn(atan(fix2double(i, q))), q);
 }
 
-/*
+int32_t fix_ATan2(int32_t i, int32_t j, int32_t q)
- * Calculate atan2
- */
-int32_t fix_ATan2(int32_t i, int32_t j)
 {
-	return double2fix(rad2fdeg(atan2(fix2double(i), fix2double(j))));
+	return double2fix(rad2turn(atan2(fix2double(i, q), fix2double(j, q))), q);
 }
 
-/*
+int32_t fix_Mul(int32_t i, int32_t j, int32_t q)
- * Multiplication
- */
-int32_t fix_Mul(int32_t i, int32_t j)
 {
-	return double2fix(fix2double(i) * fix2double(j));
+	return double2fix(fix2double(i, q) * fix2double(j, q), q);
 }
 
-/*
+int32_t fix_Div(int32_t i, int32_t j, int32_t q)
- * Division
- */
-int32_t fix_Div(int32_t i, int32_t j)
 {
-	return double2fix(fix2double(i) / fix2double(j));
+	return double2fix(fix2double(i, q) / fix2double(j, q), q);
 }
 
-/*
+int32_t fix_Mod(int32_t i, int32_t j, int32_t q)
- * Power
- */
-int32_t fix_Pow(int32_t i, int32_t j)
 {
-	return double2fix(pow(fix2double(i), fix2double(j)));
+	return double2fix(fmod(fix2double(i, q), fix2double(j, q)), q);
 }
 
-/*
+int32_t fix_Pow(int32_t i, int32_t j, int32_t q)
- * Logarithm
- */
-int32_t fix_Log(int32_t i, int32_t j)
 {
-	return double2fix(log(fix2double(i)) / log(fix2double(j)));
+	return double2fix(pow(fix2double(i, q), fix2double(j, q)), q);
 }
 
-/*
+int32_t fix_Log(int32_t i, int32_t j, int32_t q)
- * Round
- */
-int32_t fix_Round(int32_t i)
 {
-	return double2fix(round(fix2double(i)));
+	return double2fix(log(fix2double(i, q)) / log(fix2double(j, q)), q);
 }
 
-/*
+int32_t fix_Round(int32_t i, int32_t q)
- * Ceil
- */
-int32_t fix_Ceil(int32_t i)
 {
-	return double2fix(ceil(fix2double(i)));
+	return double2fix(round(fix2double(i, q)), q);
 }
 
-/*
+int32_t fix_Ceil(int32_t i, int32_t q)
- * Floor
- */
-int32_t fix_Floor(int32_t i)
 {
-	return double2fix(floor(fix2double(i)));
+	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.c

@@ -15,6 +15,7 @@
 #include <stdlib.h>
 #include <string.h>
 
+#include "asm/fixpoint.h"
 #include "asm/format.h"
 #include "asm/warning.h"
 
@@ -46,7 +47,7 @@ void fmt_UseCharacter(struct FormatSpec *fmt, int c)
 		return;
 
 	switch (c) {
-	/* sign */
+	// sign
 	case ' ':
 	case '+':
 		if (fmt->state > FORMAT_SIGN)
@@ -55,7 +56,7 @@ void fmt_UseCharacter(struct FormatSpec *fmt, int c)
 		fmt->sign = c;
 		break;
 
-	/* prefix */
+	// prefix
 	case '#':
 		if (fmt->state > FORMAT_PREFIX)
 			goto invalid;
@@ -63,7 +64,7 @@ void fmt_UseCharacter(struct FormatSpec *fmt, int c)
 		fmt->prefix = true;
 		break;
 
-	/* align */
+	// align
 	case '-':
 		if (fmt->state > FORMAT_ALIGN)
 			goto invalid;
@@ -71,11 +72,11 @@ void fmt_UseCharacter(struct FormatSpec *fmt, int c)
 		fmt->alignLeft = true;
 		break;
 
-	/* pad and width */
+	// pad and width
 	case '0':
 		if (fmt->state < FORMAT_WIDTH)
 			fmt->padZero = true;
-		/* fallthrough */
+		// fallthrough
 	case '1':
 	case '2':
 	case '3':
@@ -104,7 +105,7 @@ void fmt_UseCharacter(struct FormatSpec *fmt, int c)
 		fmt->hasFrac = true;
 		break;
 
-	/* type */
+	// type
 	case 'd':
 	case 'u':
 	case 'X':
@@ -149,7 +150,7 @@ void fmt_PrintString(char *buf, size_t bufLen, struct FormatSpec const *fmt, cha
 	size_t len = strlen(value);
 	size_t totalLen = fmt->width > len ? fmt->width : len;
 
-	if (totalLen > bufLen - 1) { /* bufLen includes terminator */
+	if (totalLen > bufLen - 1) { // bufLen includes terminator
 		error("Formatted string value too long\n");
 		totalLen = bufLen - 1;
 		if (len > totalLen)
@@ -182,7 +183,7 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 	if (fmt->type == 's')
 		error("Formatting number as type 's'\n");
 
-	char sign = fmt->sign; /* 0 or ' ' or '+' */
+	char sign = fmt->sign; // 0 or ' ' or '+'
 
 	if (fmt->type == 'd' || fmt->type == 'f') {
 		int32_t v = value;
@@ -200,10 +201,10 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 		: fmt->type == 'o' ? '&'
 		: 0;
 
-	char valueBuf[262]; /* Max 5 digits + decimal + 255 fraction digits + terminator */
+	char valueBuf[262]; // Max 5 digits + decimal + 255 fraction digits + terminator
 
 	if (fmt->type == 'b') {
-		/* Special case for binary */
+		// Special case for binary
 		char *ptr = valueBuf;
 
 		do {
@@ -213,7 +214,7 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 
 		*ptr = '\0';
 
-		/* Reverse the digits */
+		// Reverse the digits
 		size_t valueLen = ptr - valueBuf;
 
 		for (size_t i = 0, j = valueLen - 1; i < j; i++, j--) {
@@ -223,9 +224,9 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 			valueBuf[j] = c;
 		}
 	} else if (fmt->type == 'f') {
-		/* Special case for fixed-point */
+		// Special case for fixed-point
 
-		/* Default fractional width (C's is 6 for "%f"; here 5 is enough) */
+		// Default fractional width (C's is 6 for "%f"; here 5 is enough for Q16.16)
 		size_t fracWidth = fmt->hasFrac ? fmt->fracWidth : 5;
 
 		if (fracWidth > 255) {
@@ -234,7 +235,8 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 			fracWidth = 255;
 		}
 
-		snprintf(valueBuf, sizeof(valueBuf), "%.*f", (int)fracWidth, value / 65536.0);
+		snprintf(valueBuf, sizeof(valueBuf), "%.*f", (int)fracWidth,
+			 value / fix_PrecisionFactor());
 	} else {
 		char const *spec = fmt->type == 'd' ? "%" PRId32
 				 : fmt->type == 'u' ? "%" PRIu32
@@ -247,10 +249,10 @@ 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 */
+	if (totalLen > bufLen - 1) { // bufLen includes terminator
 		error("Formatted numeric value too long\n");
 		totalLen = bufLen - 1;
 		if (numLen > totalLen) {
@@ -273,7 +275,7 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 			buf[i] = ' ';
 	} else {
 		if (fmt->padZero) {
-			/* sign, then prefix, then zero padding */
+			// sign, then prefix, then zero padding
 			if (sign)
 				buf[pos++] = sign;
 			if (prefix)
@@ -281,7 +283,7 @@ void fmt_PrintNumber(char *buf, size_t bufLen, struct FormatSpec const *fmt, uin
 			for (size_t i = 0; i < padLen; i++)
 				buf[pos++] = '0';
 		} else {
-			/* space padding, then sign, then prefix */
+			// space padding, then sign, then prefix
 			for (size_t i = 0; i < padLen; i++)
 				buf[pos++] = ' ';
 			if (sign)

src/asm/fstack.c

@@ -19,7 +19,8 @@
 #include "asm/main.h"
 #include "asm/symbol.h"
 #include "asm/warning.h"
-#include "platform.h" /* S_ISDIR (stat macro) */
+#include "error.h"
+#include "platform.h" // S_ISDIR (stat macro)
 
 #define MAXINCPATHS 128
 
@@ -28,7 +29,7 @@ struct Context {
 	struct FileStackNode *fileInfo;
 	struct LexerState *lexerState;
 	uint32_t uniqueID;
-	struct MacroArgs *macroArgs; /* Macro args are *saved* here */
+	struct MacroArgs *macroArgs; // Macro args are *saved* here
 	uint32_t nbReptIters;
 	int32_t forValue;
 	int32_t forStep;
@@ -37,18 +38,19 @@ struct Context {
 
 static struct Context *contextStack;
 static size_t contextDepth = 0;
-#define DEFAULT_MAX_DEPTH 64
 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;
 
 	if (node->type == NODE_REPT) {
-		assert(node->parent); /* REPT nodes should always have a parent */
+		assert(node->parent); // REPT nodes should always have a parent
 		struct FileStackReptNode const *reptInfo = (struct FileStackReptNode const *)node;
 
 		name = dumpNodeAndParents(node->parent);
@@ -89,7 +91,7 @@ struct FileStackNode *fstk_GetFileStack(void)
 
 	struct FileStackNode *node = contextStack->fileInfo;
 
-	/* Mark node and all of its parents as referenced if not already so they don't get freed */
+	// Mark node and all of its parents as referenced if not already so they don't get freed
 	while (node && !node->referenced) {
 		node->ID = -1;
 		node->referenced = true;
@@ -100,7 +102,7 @@ struct FileStackNode *fstk_GetFileStack(void)
 
 char const *fstk_GetFileName(void)
 {
-	/* Iterating via the nodes themselves skips nested REPTs */
+	// Iterating via the nodes themselves skips nested REPTs
 	struct FileStackNode const *node = contextStack->fileInfo;
 
 	while (node->type != NODE_FILE)
@@ -121,7 +123,7 @@ void fstk_AddIncludePath(char const *path)
 	char *str = malloc(allocSize);
 
 	if (!str) {
-		/* Attempt to continue without that path */
+		// Attempt to continue without that path
 		error("Failed to allocate new include path: %s\n", strerror(errno));
 		return;
 	}
@@ -134,6 +136,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) {
@@ -150,14 +161,14 @@ static bool isPathValid(char const *path)
 	if (stat(path, &statbuf) != 0)
 		return false;
 
-	/* Reject directories */
+	// Reject directories
 	return !S_ISDIR(statbuf.st_mode);
 }
 
 bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 {
 	if (!*size) {
-		*size = 64; /* This is arbitrary, really */
+		*size = 64; // This is arbitrary, really
 		*fullPath = realloc(*fullPath, *size);
 		if (!*fullPath)
 			error("realloc error during include path search: %s\n",
@@ -175,8 +186,8 @@ bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 				break;
 			}
 
-			/* Oh how I wish `asnprintf` was standard... */
+			// Oh how I wish `asnprintf` was standard...
-			if ((size_t)len >= *size) { /* `len` doesn't include the terminator, `size` does */
+			if ((size_t)len >= *size) { // `size` includes the terminator, `len` doesn't
 				*size = len + 1;
 				*fullPath = realloc(*fullPath, *size);
 				if (!*fullPath) {
@@ -213,17 +224,18 @@ bool yywrap(void)
 		fatalerror("Ended block with %" PRIu32 " unterminated IF construct%s\n",
 			   ifDepth, ifDepth == 1 ? "" : "s");
 
-	if (contextStack->fileInfo->type == NODE_REPT) { /* The context is a REPT block, which may loop */
+	if (contextStack->fileInfo->type == NODE_REPT) {
+		// The context is a REPT or FOR block, which may loop
 		struct FileStackReptNode *fileInfo = (struct FileStackReptNode *)contextStack->fileInfo;
 
-		/* If the node is referenced, we can't edit it; duplicate it */
+		// 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);
 
 			if (!copy)
 				fatalerror("Failed to duplicate REPT file node: %s\n", strerror(errno));
-			/* Copy all info but the referencing */
+			// Copy all info but the referencing
 			memcpy(copy, fileInfo, size);
 			copy->node.next = NULL;
 			copy->node.referenced = false;
@@ -232,19 +244,19 @@ bool yywrap(void)
 			contextStack->fileInfo = (struct FileStackNode *)fileInfo;
 		}
 
-		/* If this is a FOR, update the symbol value */
+		// If this is a FOR, update the symbol value
 		if (contextStack->forName && fileInfo->iters[0] <= contextStack->nbReptIters) {
 			contextStack->forValue += contextStack->forStep;
 			struct Symbol *sym = sym_AddVar(contextStack->forName,
 				contextStack->forValue);
 
-			/* This error message will refer to the current iteration */
+			// This error message will refer to the current iteration
 			if (sym->type != SYM_VAR)
 				fatalerror("Failed to update FOR symbol value\n");
 		}
-		/* Advance to the next iteration */
+		// Advance to the next iteration
 		fileInfo->iters[0]++;
-		/* If this wasn't the last iteration, wrap instead of popping */
+		// If this wasn't the last iteration, wrap instead of popping
 		if (fileInfo->iters[0] <= contextStack->nbReptIters) {
 			lexer_RestartRept(contextStack->fileInfo->lineNo);
 			contextStack->uniqueID = macro_UseNewUniqueID();
@@ -261,45 +273,47 @@ bool yywrap(void)
 	contextDepth--;
 
 	lexer_DeleteState(context->lexerState);
-	/* Restore args if a macro (not REPT) saved them */
+	// Restore args if a macro (not REPT) saved them
 	if (context->fileInfo->type == NODE_MACRO)
 		macro_UseNewArgs(contextStack->macroArgs);
-	/* Free the file stack node */
+	// Free the file stack node
 	if (!context->fileInfo->referenced)
 		free(context->fileInfo);
-	/* Free the FOR symbol name */
+	// Free the FOR symbol name
 	free(context->forName);
-	/* Free the entry and make its parent the current entry */
+	// Free the entry and make its parent the current entry
 	free(context);
 
 	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.
- * 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.
- * Callers should set contextStack->lexerState after this so it is not NULL
- */
 static void newContext(struct FileStackNode *fileInfo)
 {
-	if (++contextDepth >= maxRecursionDepth)
+	++contextDepth;
-		fatalerror("Recursion limit (%zu) exceeded\n", maxRecursionDepth);
+	fstk_NewRecursionDepth(maxRecursionDepth); // Only checks if the max depth was exceeded
+
+	// Save the current `\@` value, to be restored when this context ends
+	contextStack->uniqueID = macro_GetUniqueID();
+
 	struct Context *context = malloc(sizeof(*context));
 
 	if (!context)
 		fatalerror("Failed to allocate memory for new context: %s\n", strerror(errno));
 	fileInfo->parent = contextStack->fileInfo;
-	fileInfo->lineNo = 0; /* Init to a default value, see struct definition for info */
+	fileInfo->lineNo = 0; // Init to a default value, see struct definition for info
 	fileInfo->referenced = false;
 	fileInfo->lineNo = lexer_GetLineNo();
 	context->fileInfo = fileInfo;
 	context->forName = NULL;
-	/*
+
-	 * Link new entry to its parent so it's reachable later
+	// 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;
 }
@@ -337,9 +351,43 @@ 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 */
+	// We're back at top-level, so most things are reset
-	contextStack->uniqueID = 0;
+	contextStack->uniqueID = macro_UndefUniqueID();
-	macro_SetUniqueID(0);
+}
+
+// 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 = 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();
 }
 
 void fstk_RunMacro(char const *macroName, struct MacroArgs *args)
@@ -356,16 +404,16 @@ void fstk_RunMacro(char const *macroName, struct MacroArgs *args)
 	}
 	contextStack->macroArgs = macro_GetCurrentArgs();
 
-	/* Compute total length of this node's name: <base name>::<macro> */
+	// Compute total length of this node's name: <base name>::<macro>
 	size_t reptNameLen = 0;
 	struct FileStackNode const *node = macro->src;
 
 	if (node->type == NODE_REPT) {
 		struct FileStackReptNode const *reptNode = (struct FileStackReptNode const *)node;
 
-		/* 4294967295 = 2^32 - 1, aka UINT32_MAX */
+		// 4294967295 = 2^32 - 1, aka UINT32_MAX
 		reptNameLen += reptNode->reptDepth * strlen("::REPT~4294967295");
-		/* Look for next named node */
+		// Look for next named node
 		do {
 			node = node->parent;
 		} while (node->type == NODE_REPT);
@@ -381,7 +429,7 @@ void fstk_RunMacro(char const *macroName, struct MacroArgs *args)
 		return;
 	}
 	fileInfo->node.type = NODE_MACRO;
-	/* Print the name... */
+	// Print the name...
 	char *dest = fileInfo->name;
 
 	memcpy(dest, baseNode->name, baseLen);
@@ -428,13 +476,13 @@ static bool newReptContext(int32_t reptLineNo, char *body, size_t size)
 	fileInfo->reptDepth = reptDepth + 1;
 	fileInfo->iters[0] = 1;
 	if (reptDepth)
-		/* Copy all parent iter counts */
+		// Copy all parent iter counts
 		memcpy(&fileInfo->iters[1],
 		       ((struct FileStackReptNode *)contextStack->fileInfo)->iters,
 		       reptDepth * sizeof(fileInfo->iters[0]));
 
 	newContext((struct FileStackNode *)fileInfo);
-	/* Correct our line number, which currently points to the `ENDR` line */
+	// Correct our line number, which currently points to the `ENDR` line
 	contextStack->fileInfo->lineNo = reptLineNo;
 
 	contextStack->lexerState = lexer_OpenFileView("REPT", body, size, reptLineNo);
@@ -492,7 +540,7 @@ void fstk_RunFor(char const *symName, int32_t start, int32_t stop, int32_t step,
 
 void fstk_StopRept(void)
 {
-	/* Prevent more iterations */
+	// Prevent more iterations
 	contextStack->nbReptIters = 0;
 }
 
@@ -507,6 +555,13 @@ bool fstk_Break(void)
 	return true;
 }
 
+void fstk_NewRecursionDepth(size_t newDepth)
+{
+	if (contextDepth > newDepth)
+		fatalerror("Recursion limit (%zu) exceeded\n", newDepth);
+	maxRecursionDepth = newDepth;
+}
+
 void fstk_Init(char const *mainPath, size_t maxDepth)
 {
 	struct LexerState *state = lexer_OpenFile(mainPath);
@@ -525,7 +580,7 @@ void fstk_Init(char const *mainPath, size_t maxDepth)
 		fatalerror("Failed to allocate memory for main file info: %s\n", strerror(errno));
 
 	context->fileInfo = (struct FileStackNode *)fileInfo;
-	/* lineNo and reptIter are unused on the top-level context */
+	// lineNo and reptIter are unused on the top-level context
 	context->fileInfo->parent = NULL;
 	context->fileInfo->lineNo = 0; // This still gets written to the object file, so init it
 	context->fileInfo->referenced = false;
@@ -534,20 +589,17 @@ void fstk_Init(char const *mainPath, size_t maxDepth)
 
 	context->parent = NULL;
 	context->lexerState = state;
-	context->uniqueID = 0;
+	context->uniqueID = macro_UndefUniqueID();
-	macro_SetUniqueID(0);
 	context->nbReptIters = 0;
 	context->forValue = 0;
 	context->forStep = 0;
 	context->forName = NULL;
 
-	/* Now that it's set up properly, register the context */
+	// Now that it's set up properly, register the context
 	contextStack = context;
 
-	/*
+	// Check that max recursion depth won't allow overflowing node `malloc`s
-	 * Check that max recursion depth won't allow overflowing node `malloc`s
+	// This assumes that the rept node is larger
-	 * This assumes that the rept node is larger
-	 */
 #define DEPTH_LIMIT ((SIZE_MAX - sizeof(struct FileStackReptNode)) / sizeof(uint32_t))
 	if (maxDepth > DEPTH_LIMIT) {
 		error("Recursion depth may not be higher than %zu, defaulting to "
@@ -556,7 +608,9 @@ void fstk_Init(char const *mainPath, size_t maxDepth)
 	} else {
 		maxRecursionDepth = maxDepth;
 	}
-	/* Make sure that the default of 64 is OK, though */
+	// Make sure that the default of 64 is OK, though
 	assert(DEPTH_LIMIT >= DEFAULT_MAX_DEPTH);
 #undef DEPTH_LIMIT
+
+	runPreIncludeFile();
 }

src/asm/macro.c

@@ -1,5 +1,11 @@
+/*
+ * This file is part of RGBDS.
+ *
+ * Copyright (c) 2022, Eldred Habert and RGBDS contributors.
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
-#include <assert.h>
 #include <errno.h>
 #include <inttypes.h>
 #include <stdbool.h>
@@ -12,13 +18,11 @@
 
 #define MAXMACROARGS 99999
 
-/*
+// Your average macro invocation does not go past the tens, but some go further
- * Your average macro invocation does not go past the tens, but some go further
+// This ensures that sane and slightly insane invocations suffer no penalties,
- * This ensures that sane and slightly insane invocations suffer no penalties,
+// and the rest is insane and thus will assume responsibility.
- * and the rest is insane and thus will assume responsibility.
+// Additionally, ~300 bytes (on x64) of memory per level of nesting has been
- * Additionally, ~300 bytes (on x64) of memory per level of nesting has been
+// deemed reasonable. (Halve that on x86.)
- * deemed reasonable. (Halve that on x86.)
- */
 #define INITIAL_ARG_SIZE 32
 struct MacroArgs {
 	unsigned int nbArgs;
@@ -33,11 +37,9 @@ struct MacroArgs {
 static struct MacroArgs *macroArgs = NULL;
 static uint32_t uniqueID = 0;
 static uint32_t maxUniqueID = 0;
-/*
+// The initialization is somewhat harmful, since it is never used, but it
- * The initialization is somewhat harmful, since it is never used, but it
+// guarantees the size of the buffer will be correct. I was unable to find a
- * guarantees the size of the buffer will be correct. I was unable to find a
+// better solution, but if you have one, please feel free!
- * better solution, but if you have one, please feel free!
- */
 static char uniqueIDBuf[] = "_u4294967295"; // UINT32_MAX
 static char *uniqueIDPtr = NULL;
 
@@ -68,7 +70,7 @@ void macro_AppendArg(struct MacroArgs **argPtr, char *s)
 		error("A maximum of " EXPAND_AND_STR(MAXMACROARGS) " arguments is allowed\n");
 	if (macArgs->nbArgs >= macArgs->capacity) {
 		macArgs->capacity *= 2;
-		/* Check that overflow didn't roll us back */
+		// 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));
@@ -101,7 +103,7 @@ char const *macro_GetArg(uint32_t i)
 					      : macroArgs->args[realIndex];
 }
 
-char *macro_GetAllArgs(void)
+char const *macro_GetAllArgs(void)
 {
 	if (!macroArgs)
 		return NULL;
@@ -112,9 +114,9 @@ char *macro_GetAllArgs(void)
 	size_t len = 0;
 
 	for (uint32_t i = macroArgs->shift; i < macroArgs->nbArgs; i++)
-		len += strlen(macroArgs->args[i]) + 1; /* 1 for comma */
+		len += strlen(macroArgs->args[i]) + 1; // 1 for comma
 
-	char *str = malloc(len + 1); /* 1 for '\0' */
+	char *str = malloc(len + 1); // 1 for '\0'
 	char *ptr = str;
 
 	if (!str)
@@ -126,9 +128,9 @@ char *macro_GetAllArgs(void)
 		memcpy(ptr, macroArgs->args[i], n);
 		ptr += n;
 
-		/* Commas go between args and after a last empty arg */
+		// Commas go between args and after a last empty arg
 		if (i < macroArgs->nbArgs - 1 || n == 0)
-			*ptr++ = ','; /* no space after comma */
+			*ptr++ = ','; // no space after comma
 	}
 	*ptr = '\0';
 
@@ -142,19 +144,21 @@ uint32_t macro_GetUniqueID(void)
 
 char const *macro_GetUniqueIDStr(void)
 {
+	// Generate a new unique ID on the first use of `\@`
+	if (uniqueID == 0)
+		macro_SetUniqueID(++maxUniqueID);
+
 	return uniqueIDPtr;
 }
 
 void macro_SetUniqueID(uint32_t id)
 {
 	uniqueID = id;
-	if (id == 0) {
+	if (id == 0 || id == (uint32_t)-1) {
 		uniqueIDPtr = NULL;
 	} else {
-		if (uniqueID > maxUniqueID)
+		// The buffer is guaranteed to be the correct size
-			maxUniqueID = uniqueID;
+		// This is a valid label fragment, but not a valid numeric
-		/* The buffer is guaranteed to be the correct size */
-		/* This is a valid label fragment, but not a valid numeric */
 		sprintf(uniqueIDBuf, "_u%" PRIu32, id);
 		uniqueIDPtr = uniqueIDBuf;
 	}
@@ -162,8 +166,16 @@ void macro_SetUniqueID(uint32_t id)
 
 uint32_t macro_UseNewUniqueID(void)
 {
-	macro_SetUniqueID(++maxUniqueID);
+	// A new ID will be generated on the first use of `\@`
-	return maxUniqueID;
+	macro_SetUniqueID(0);
+	return uniqueID;
+}
+
+uint32_t macro_UndefUniqueID(void)
+{
+	// No ID will be generated; use of `\@` is an error
+	macro_SetUniqueID((uint32_t)-1);
+	return uniqueID;
 }
 
 void macro_ShiftCurrentArgs(int32_t count)

src/asm/main.c

@@ -19,6 +19,7 @@
 #include <time.h>
 
 #include "asm/charmap.h"
+#include "asm/fixpoint.h"
 #include "asm/format.h"
 #include "asm/fstack.h"
 #include "asm/lexer.h"
@@ -39,8 +40,8 @@
 #ifdef __clang__
 #if __has_feature(address_sanitizer) && !defined(__SANITIZE_ADDRESS__)
 #define __SANITIZE_ADDRESS__
-#endif /* __has_feature(address_sanitizer) && !defined(__SANITIZE_ADDRESS__) */
+#endif // __has_feature(address_sanitizer) && !defined(__SANITIZE_ADDRESS__)
-#endif /* __clang__ */
+#endif // __clang__
 
 #ifdef __SANITIZE_ADDRESS__
 // There are known, non-trivial to fix leaks. We would still like to have `make develop'
@@ -52,18 +53,20 @@ char const *__asan_default_options(void) { return "detect_leaks=0"; }
 // Unfortunately, macOS still ships 2.3, which is from 2008...
 int yyparse(void);
 
-FILE * dependfile;
+FILE *dependfile = NULL;
-bool generatedMissingIncludes;
+bool generatedMissingIncludes = false;
-bool failedOnMissingInclude;
+bool failedOnMissingInclude = false;
-bool generatePhonyDeps;
+bool generatePhonyDeps = false;
-char *targetFileName;
+char *targetFileName = NULL;
 
 bool haltnop;
+bool warnOnHaltNop;
 bool optimizeLoads;
+bool warnOnLdOpt;
 bool verbose;
-bool warnings; /* True to enable warnings, false to disable them. */
+bool warnings; // True to enable warnings, false to disable them.
 
-/* Escapes Make-special chars from a string */
+// Escapes Make-special chars from a string
 static char *make_escape(char const *str)
 {
 	char * const escaped_str = malloc(strlen(str) * 2 + 1);
@@ -73,7 +76,7 @@ static char *make_escape(char const *str)
 		err("%s: Failed to allocate memory", __func__);
 
 	while (*str) {
-		/* All dollars needs to be doubled */
+		// All dollars needs to be doubled
 		if (*str == '$')
 			*dest++ = '$';
 		*dest++ = *str++;
@@ -83,37 +86,39 @@ static char *make_escape(char const *str)
 	return escaped_str;
 }
 
-/* Short options */
+// Short options
-static const char *optstring = "b:D:Eg:hi:LM:o:p:r:VvW:w";
+static const char *optstring = "b:D:Eg:Hhi:I:LlM:o:P:p:Q:r:VvW:w";
 
-/* Variables for the long-only options */
+// Variables for the long-only options
-static int depType; /* Variants of `-M` */
+static int depType; // Variants of `-M`
 
-/*
+// Equivalent long options
- * Equivalent long options
+// Please keep in the same order as short opts
- * Please keep in the same order as short opts
+//
- *
+// Also, make sure long opts don't create ambiguity:
- * Also, make sure long opts don't create ambiguity:
+// A long opt's name should start with the same letter as its short opt,
- * A long opt's name should start with the same letter as its short opt,
+// except if it doesn't create any ambiguity (`verbose` versus `version`).
- * except if it doesn't create any ambiguity (`verbose` versus `version`).
+// This is because long opt matching, even to a single char, is prioritized
- * This is because long opt matching, even to a single char, is prioritized
+// over short opt matching
- * over short opt matching
- */
 static struct option const longopts[] = {
 	{ "binary-digits",    required_argument, NULL,     'b' },
 	{ "define",           required_argument, NULL,     'D' },
 	{ "export-all",       no_argument,       NULL,     'E' },
 	{ "gfx-chars",        required_argument, NULL,     'g' },
+	{ "nop-after-halt",   no_argument,       NULL,     'H' },
 	{ "halt-without-nop", no_argument,       NULL,     'h' },
-	{ "include",          required_argument, NULL,     'i' },
+	{ "include",          required_argument, NULL,     'I' },
 	{ "preserve-ld",      no_argument,       NULL,     'L' },
+	{ "auto-ldh",         no_argument,       NULL,     'l' },
 	{ "dependfile",       required_argument, NULL,     'M' },
 	{ "MG",               no_argument,       &depType, 'G' },
 	{ "MP",               no_argument,       &depType, 'P' },
 	{ "MT",               required_argument, &depType, 'T' },
 	{ "MQ",               required_argument, &depType, 'Q' },
 	{ "output",           required_argument, NULL,     'o' },
+	{ "preinclude",       required_argument, NULL,     'P' },
 	{ "pad-value",        required_argument, NULL,     'p' },
+	{ "q-precision",      required_argument, NULL,     'Q' },
 	{ "recursion-depth",  required_argument, NULL,     'r' },
 	{ "version",          no_argument,       NULL,     'V' },
 	{ "verbose",          no_argument,       NULL,     'v' },
@@ -124,9 +129,10 @@ static struct option const longopts[] = {
 static void print_usage(void)
 {
 	fputs(
-"Usage: rgbasm [-EhLVvw] [-b chars] [-D name[=value]] [-g chars] [-i path]\n"
+"Usage: rgbasm [-EHhLlVvw] [-b chars] [-D name[=value]] [-g chars] [-I path]\n"
 "              [-M depend_file] [-MG] [-MP] [-MT target_file] [-MQ target_file]\n"
-"              [-o out_file] [-p pad_value] [-r depth] [-W warning] <file>\n"
+"              [-o out_file] [-P include_file] [-p pad_value] [-Q precision]\n"
+"              [-r depth] [-W warning] <file>\n"
 "Useful options:\n"
 "    -E, --export-all         export all labels\n"
 "    -M, --dependfile <path>  set the output dependency file\n"
@@ -142,47 +148,41 @@ static void print_usage(void)
 
 int main(int argc, char *argv[])
 {
-	int ch;
-	char *ep;
-
 	time_t now = time(NULL);
 	char const *sourceDateEpoch = getenv("SOURCE_DATE_EPOCH");
 
-	/*
+	// Support SOURCE_DATE_EPOCH for reproducible builds
-	 * Support SOURCE_DATE_EPOCH for reproducible builds
+	// https://reproducible-builds.org/docs/source-date-epoch/
-	 * https://reproducible-builds.org/docs/source-date-epoch/
-	 */
 	if (sourceDateEpoch)
 		now = (time_t)strtoul(sourceDateEpoch, NULL, 0);
 
-	dependfile = NULL;
-
 	// Perform some init for below
 	sym_Init(now);
 
 	// Set defaults
 
-	generatePhonyDeps = false;
-	generatedMissingIncludes = false;
-	failedOnMissingInclude = false;
-	targetFileName = NULL;
-
 	opt_B("01");
 	opt_G("0123");
 	opt_P(0);
-	optimizeLoads = true;
+	opt_Q(16);
 	haltnop = true;
+	warnOnHaltNop = true;
+	optimizeLoads = true;
+	warnOnLdOpt = true;
 	verbose = false;
 	warnings = true;
 	sym_SetExportAll(false);
-	uint32_t maxDepth = 64;
+	uint32_t maxDepth = DEFAULT_MAX_DEPTH;
+	char *dependFileName = NULL;
 	size_t targetFileNameLen = 0;
 
+	int ch;
+	char *ep;
 	while ((ch = musl_getopt_long_only(argc, argv, optstring, longopts, NULL)) != -1) {
 		switch (ch) {
 		case 'b':
 			if (strlen(musl_optarg) == 2)
-				opt_B(&musl_optarg[1]);
+				opt_B(musl_optarg);
 			else
 				errx("Must specify exactly 2 characters for option 'b'");
 			break;
@@ -204,47 +204,91 @@ int main(int argc, char *argv[])
 
 		case 'g':
 			if (strlen(musl_optarg) == 4)
-				opt_G(&musl_optarg[1]);
+				opt_G(musl_optarg);
 			else
 				errx("Must specify exactly 4 characters for option 'g'");
 			break;
 
+		case 'H':
+			if (!haltnop)
+				errx("`-H` and `-h` don't make sense together");
+			warnOnHaltNop = false;
+			break;
 		case 'h':
+			if (!warnOnHaltNop)
+				errx("`-H` and `-h` don't make sense together");
 			haltnop = false;
 			break;
 
+		// `-i` was the only short option for `--include` until `-I` was
+		// introduced to better match the `-I dir` option of gcc and clang.
+		// `-i` is now undocumented but still supported for now.
+		case 'I':
 		case 'i':
 			fstk_AddIncludePath(musl_optarg);
 			break;
 
 		case 'L':
+			if (!warnOnLdOpt)
+				errx("`-L` and `-l` don't make sense together");
 			optimizeLoads = false;
 			break;
+		case 'l':
+			if (!optimizeLoads)
+				errx("`-L` and `-l` don't make sense together");
+			warnOnLdOpt = false;
+			break;
 
 		case 'M':
-			if (!strcmp("-", musl_optarg))
+			if (dependfile)
+				warnx("Overriding dependfile %s", dependFileName);
+			if (!strcmp("-", musl_optarg)) {
 				dependfile = stdout;
-			else
+				dependFileName = "<stdout>";
+			} else {
 				dependfile = fopen(musl_optarg, "w");
+				dependFileName = musl_optarg;
+			}
 			if (dependfile == NULL)
-				err("Could not open dependfile %s", musl_optarg);
+				err("Could not open dependfile %s", dependFileName);
 			break;
 
 		case 'o':
 			out_SetFileName(musl_optarg);
 			break;
 
-			unsigned long fill;
+		case 'P':
+			fstk_SetPreIncludeFile(musl_optarg);
+			break;
+
+			unsigned long padByte;
 		case 'p':
-			fill = strtoul(musl_optarg, &ep, 0);
+			padByte = strtoul(musl_optarg, &ep, 0);
 
 			if (musl_optarg[0] == '\0' || *ep != '\0')
 				errx("Invalid argument for option 'p'");
 
-			if (fill < 0 || fill > 0xFF)
+			if (padByte > 0xFF)
 				errx("Argument for option 'p' must be between 0 and 0xFF");
 
-			opt_P(fill);
+			opt_P(padByte);
+			break;
+
+			unsigned long precision;
+			const char *precisionArg;
+		case 'Q':
+			precisionArg = musl_optarg;
+			if (precisionArg[0] == '.')
+				precisionArg++;
+			precision = strtoul(precisionArg, &ep, 0);
+
+			if (musl_optarg[0] == '\0' || *ep != '\0')
+				errx("Invalid argument for option 'Q'");
+
+			if (precision < 1 || precision > 31)
+				errx("Argument for option 'Q' must be between 1 and 31");
+
+			opt_Q(precision);
 			break;
 
 		case 'r':
@@ -257,6 +301,7 @@ int main(int argc, char *argv[])
 		case 'V':
 			printf("rgbasm %s\n", get_package_version_string());
 			exit(0);
+
 		case 'v':
 			verbose = true;
 			break;
@@ -269,7 +314,7 @@ int main(int argc, char *argv[])
 			warnings = false;
 			break;
 
-		/* Long-only options */
+		// Long-only options
 		case 0:
 			switch (depType) {
 			case 'G':
@@ -301,10 +346,10 @@ int main(int argc, char *argv[])
 			}
 			break;
 
-		/* Unrecognized options */
+		// Unrecognized options
 		default:
 			print_usage();
-			/* NOTREACHED */
+			// NOTREACHED
 		}
 	}
 
@@ -333,9 +378,9 @@ int main(int argc, char *argv[])
 		fprintf(dependfile, "%s: %s\n", targetFileName, mainFileName);
 	}
 
-	charmap_New("main", NULL);
+	charmap_New(DEFAULT_CHARMAP_NAME, NULL);
 
-	// Init lexer and file stack, prodiving file info
+	// Init lexer and file stack, providing file info
 	lexer_Init();
 	fstk_Init(mainFileName, maxDepth);
 
@@ -356,7 +401,7 @@ int main(int argc, char *argv[])
 	if (failedOnMissingInclude)
 		return 0;
 
-	/* If no path specified, don't write file */
+	// If no path specified, don't write file
 	if (objectName != NULL)
 		out_WriteObject();
 	return 0;

src/asm/opt.c

@@ -1,3 +1,12 @@
+/*
+ * This file is part of RGBDS.
+ *
+ * Copyright (c) 2022, RGBDS contributors.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <ctype.h>
 #include <errno.h>
 #include <stdbool.h>
 #include <stdint.h>
@@ -5,6 +14,8 @@
 #include <stdlib.h>
 #include <string.h>
 
+#include "asm/fixpoint.h"
+#include "asm/fstack.h"
 #include "asm/lexer.h"
 #include "asm/main.h"
 #include "asm/section.h"
@@ -13,10 +24,14 @@
 struct OptStackEntry {
 	char binary[2];
 	char gbgfx[4];
-	int32_t fillByte;
+	uint8_t fixPrecision;
+	uint8_t fillByte;
 	bool haltnop;
+	bool warnOnHaltNop;
 	bool optimizeLoads;
+	bool warnOnLdOpt;
 	bool warningsAreErrors;
+	size_t maxRecursionDepth;
 	// Don't be confused: we use the size of the **global variable** `warningStates`!
 	enum WarningState warningStates[sizeof(warningStates)];
 	struct OptStackEntry *next;
@@ -24,19 +39,35 @@ struct OptStackEntry {
 
 static struct OptStackEntry *stack = NULL;
 
-void opt_B(char chars[2])
+void opt_B(char const chars[2])
 {
 	lexer_SetBinDigits(chars);
 }
 
-void opt_G(char chars[4])
+void opt_G(char const chars[4])
 {
 	lexer_SetGfxDigits(chars);
 }
 
-void opt_P(uint8_t fill)
+void opt_P(uint8_t padByte)
 {
-	fillByte = fill;
+	fillByte = padByte;
+}
+
+void opt_Q(uint8_t precision)
+{
+	fixPrecision = precision;
+}
+
+void opt_R(size_t newDepth)
+{
+	fstk_NewRecursionDepth(newDepth);
+	lexer_CheckRecursionDepth();
+}
+
+void opt_H(bool warn)
+{
+	warnOnHaltNop = warn;
 }
 
 void opt_h(bool halt)
@@ -49,6 +80,11 @@ void opt_L(bool optimize)
 	optimizeLoads = optimize;
 }
 
+void opt_l(bool warn)
+{
+	warnOnLdOpt = warn;
+}
+
 void opt_W(char *flag)
 {
 	processWarningFlag(flag);
@@ -74,18 +110,71 @@ void opt_Parse(char *s)
 	case 'p':
 		if (strlen(&s[1]) <= 2) {
 			int result;
-			unsigned int fillchar;
+			unsigned int padByte;
 
-			result = sscanf(&s[1], "%x", &fillchar);
+			result = sscanf(&s[1], "%x", &padByte);
-			if (result != EOF && result != 1)
+			if (result != 1)
 				error("Invalid argument for option 'p'\n");
+			else if (padByte > 0xFF)
+				error("Argument for option 'p' must be between 0 and 0xFF\n");
 			else
-				opt_P(fillchar);
+				opt_P(padByte);
 		} else {
 			error("Invalid argument for option 'p'\n");
 		}
 		break;
 
+		const char *precisionArg;
+	case 'Q':
+		precisionArg = &s[1];
+		if (precisionArg[0] == '.')
+			precisionArg++;
+		if (strlen(precisionArg) <= 2) {
+			int result;
+			unsigned int precision;
+
+			result = sscanf(precisionArg, "%u", &precision);
+			if (result != 1)
+				error("Invalid argument for option 'Q'\n");
+			else if (precision < 1 || precision > 31)
+				error("Argument for option 'Q' must be between 1 and 31\n");
+			else
+				opt_Q(precision);
+		} else {
+			error("Invalid argument for option 'Q'\n");
+		}
+		break;
+
+	case 'r': {
+		++s; // Skip 'r'
+		while (isblank(*s))
+			++s; // Skip leading whitespace
+
+		if (s[0] == '\0') {
+			error("Missing argument to option 'r'\n");
+			break;
+		}
+
+		char *endptr;
+		unsigned long newDepth = strtoul(s, &endptr, 10);
+
+		if (*endptr != '\0') {
+			error("Invalid argument to option 'r' (\"%s\")\n", s);
+		} else if (errno == ERANGE) {
+			error("Argument to 'r' is out of range (\"%s\")\n", s);
+		} else {
+			opt_R(newDepth);
+		}
+		break;
+	}
+
+	case 'H':
+		if (s[1] == '\0')
+			opt_H(false);
+		else
+			error("Option 'H' does not take an argument\n");
+		break;
+
 	case 'h':
 		if (s[1] == '\0')
 			opt_h(false);
@@ -100,6 +189,13 @@ void opt_Parse(char *s)
 			error("Option 'L' does not take an argument\n");
 		break;
 
+	case 'l':
+		if (s[1] == '\0')
+			opt_l(false);
+		else
+			error("Option 'l' does not take an argument\n");
+		break;
+
 	case 'W':
 		if (strlen(&s[1]) > 0)
 			opt_W(&s[1]);
@@ -109,6 +205,13 @@ void opt_Parse(char *s)
 
 	case '!': // negates flag options that do not take an argument
 		switch (s[1]) {
+		case 'H':
+			if (s[2] == '\0')
+				opt_H(true);
+			else
+				error("Option '!H' does not take an argument\n");
+			break;
+
 		case 'h':
 			if (s[2] == '\0')
 				opt_h(true);
@@ -123,6 +226,13 @@ void opt_Parse(char *s)
 				error("Option '!L' does not take an argument\n");
 			break;
 
+		case 'l':
+			if (s[2] == '\0')
+				opt_l(true);
+			else
+				error("Option '!l' does not take an argument\n");
+			break;
+
 		default:
 			error("Unknown option '!%c'\n", s[1]);
 			break;
@@ -151,11 +261,15 @@ void opt_Push(void)
 	entry->gbgfx[2] = gfxDigits[2];
 	entry->gbgfx[3] = gfxDigits[3];
 
+	entry->fixPrecision = fixPrecision; // Pulled from fixpoint.h
+
 	entry->fillByte = fillByte; // Pulled from section.h
 
 	entry->haltnop = haltnop; // Pulled from main.h
+	entry->warnOnHaltNop = warnOnHaltNop;
 
 	entry->optimizeLoads = optimizeLoads; // Pulled from main.h
+	entry->warnOnLdOpt = warnOnLdOpt;
 
 	// Both of these pulled from warning.h
 	entry->warningsAreErrors = warningsAreErrors;
@@ -177,8 +291,11 @@ void opt_Pop(void)
 	opt_B(entry->binary);
 	opt_G(entry->gbgfx);
 	opt_P(entry->fillByte);
+	opt_Q(entry->fixPrecision);
+	opt_H(entry->warnOnHaltNop);
 	opt_h(entry->haltnop);
 	opt_L(entry->optimizeLoads);
+	opt_l(entry->warnOnLdOpt);
 
 	// opt_W does not apply a whole warning state; it processes one flag string
 	warningsAreErrors = entry->warningsAreErrors;

src/asm/output.c

@@ -6,9 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*
+// Outputs an objectfile
- * Outputs an objectfile
- */
 
 #include <assert.h>
 #include <errno.h>
@@ -54,18 +52,16 @@ char *objectName;
 
 struct Section *sectionList;
 
-/* Linked list of symbols to put in the object file */
+// Linked list of symbols to put in the object file
 static struct Symbol *objectSymbols = NULL;
 static struct Symbol **objectSymbolsTail = &objectSymbols;
-static uint32_t nbSymbols = 0; /* Length of the above list */
+static uint32_t nbSymbols = 0; // Length of the above list
 
 static struct Assertion *assertions = NULL;
 
 static struct FileStackNode *fileStackNodes = NULL;
 
-/*
+// Count the number of sections used in this object
- * Count the number of sections used in this object
- */
 static uint32_t countSections(void)
 {
 	uint32_t count = 0;
@@ -76,9 +72,7 @@ static uint32_t countSections(void)
 	return count;
 }
 
-/*
+// Count the number of patches used in this object
- * Count the number of patches used in this object
- */
 static uint32_t countPatches(struct Section const *sect)
 {
 	uint32_t r = 0;
@@ -90,9 +84,7 @@ static uint32_t countPatches(struct Section const *sect)
 	return r;
 }
 
-/**
+// Count the number of assertions used in this object
- * Count the number of assertions used in this object
- */
 static uint32_t countAsserts(void)
 {
 	struct Assertion *assert = assertions;
@@ -105,9 +97,7 @@ static uint32_t countAsserts(void)
 	return count;
 }
 
-/*
+// Write a long to a file (little-endian)
- * Write a long to a file (little-endian)
- */
 static void putlong(uint32_t i, FILE *f)
 {
 	putc(i, f);
@@ -116,9 +106,7 @@ static void putlong(uint32_t i, FILE *f)
 	putc(i >> 24, f);
 }
 
-/*
+// Write a NULL-terminated string to a file
- * Write a NULL-terminated string to a file
- */
 static void putstring(char const *s, FILE *f)
 {
 	while (*s)
@@ -133,7 +121,7 @@ static uint32_t getNbFileStackNodes(void)
 
 void out_RegisterNode(struct FileStackNode *node)
 {
-	/* If node is not already registered, register it (and parents), and give it a unique ID */
+	// If node is not already registered, register it (and parents), and give it a unique ID
 	while (node->ID == (uint32_t)-1) {
 		node->ID = getNbFileStackNodes();
 		if (node->ID == (uint32_t)-1)
@@ -141,7 +129,7 @@ void out_RegisterNode(struct FileStackNode *node)
 		node->next = fileStackNodes;
 		fileStackNodes = node;
 
-		/* Also register the node's parents */
+		// Also register the node's parents
 		node = node->parent;
 		if (!node)
 			break;
@@ -156,25 +144,21 @@ This is code intended to replace a node, which is pretty useless until ref count
 
 	struct FileStackNode **ptr = &fileStackNodes;
 
-	/*
+	// The linked list is supposed to have decrementing IDs, so iterate with less memory reads,
-	 * The linked list is supposed to have decrementing IDs, so iterate with less memory reads,
+	// to hopefully hit the cache less. A debug check is added after, in case a change is made
-	 * to hopefully hit the cache less. A debug check is added after, in case a change is made
+	// that breaks this assumption.
-	 * that breaks this assumption.
-	 */
 	for (uint32_t i = fileStackNodes->ID; i != node->ID; i--)
 		ptr = &(*ptr)->next;
 	assert((*ptr)->ID == node->ID);
 
 	node->next = (*ptr)->next;
-	assert(!node->next || node->next->ID == node->ID - 1); /* Catch inconsistencies early */
+	assert(!node->next || node->next->ID == node->ID - 1); // Catch inconsistencies early
-	/* TODO: unreference the node */
+	// TODO: unreference the node
 	*ptr = node;
 #endif
 }
 
-/*
+// Return a section's ID
- * Return a section's ID
- */
 static uint32_t getsectid(struct Section const *sect)
 {
 	struct Section const *sec = sectionList;
@@ -192,15 +176,13 @@ static uint32_t getsectid(struct Section const *sect)
 
 static uint32_t getSectIDIfAny(struct Section const *sect)
 {
-	return sect ? getsectid(sect) : -1;
+	return sect ? getsectid(sect) : (uint32_t)-1;
 }
 
-/*
+// Write a patch to a file
- * Write a patch to a file
- */
 static void writepatch(struct Patch const *patch, FILE *f)
 {
-	assert(patch->src->ID != -1);
+	assert(patch->src->ID != (uint32_t)-1);
 	putlong(patch->src->ID, f);
 	putlong(patch->lineNo, f);
 	putlong(patch->offset, f);
@@ -211,9 +193,7 @@ static void writepatch(struct Patch const *patch, FILE *f)
 	fwrite(patch->rpn, 1, patch->rpnSize, f);
 }
 
-/*
+// Write a section to a file
- * Write a section to a file
- */
 static void writesection(struct Section const *sect, FILE *f)
 {
 	putstring(sect->name, f);
@@ -255,16 +235,14 @@ static void freesection(struct Section const *sect)
 	}
 }
 
-/*
+// Write a symbol to a file
- * Write a symbol to a file
- */
 static void writesymbol(struct Symbol const *sym, FILE *f)
 {
 	putstring(sym->name, f);
 	if (!sym_IsDefined(sym)) {
 		putc(SYMTYPE_IMPORT, f);
 	} else {
-		assert(sym->src->ID != -1);
+		assert(sym->src->ID != (uint32_t)-1);
 
 		putc(sym->isExported ? SYMTYPE_EXPORT : SYMTYPE_LOCAL, f);
 		putlong(sym->src->ID, f);
@@ -285,10 +263,8 @@ static void registerSymbol(struct Symbol *sym)
 	sym->ID = nbSymbols++;
 }
 
-/*
+// Returns a symbol's ID within the object file
- * Returns a symbol's ID within the object file
+// If the symbol does not have one, one is assigned by registering the symbol
- * If the symbol does not have one, one is assigned by registering the symbol
- */
 static uint32_t getSymbolID(struct Symbol *sym)
 {
 	if (sym->ID == (uint32_t)-1 && !sym_IsPC(sym))
@@ -392,10 +368,8 @@ static void writerpn(uint8_t *rpnexpr, uint32_t *rpnptr, uint8_t *rpn,
 	}
 }
 
-/*
+// Allocate a new patch structure and link it into the list
- * Allocate a new patch structure and link it into the list
+// WARNING: all patches are assumed to eventually be written, so the file stack node is registered
- * WARNING: all patches are assumed to eventually be written, so the file stack node is registered
- */
 static struct Patch *allocpatch(uint32_t type, struct Expression const *expr, uint32_t ofs)
 {
 	struct Patch *patch = malloc(sizeof(struct Patch));
@@ -417,10 +391,10 @@ static struct Patch *allocpatch(uint32_t type, struct Expression const *expr, ui
 	patch->pcSection = sect_GetSymbolSection();
 	patch->pcOffset = sect_GetSymbolOffset();
 
-	/* If the rpnSize's value is known, output a constant RPN rpnSize directly */
+	// If the rpnSize's value is known, output a constant RPN rpnSize directly
 	if (expr->isKnown) {
 		patch->rpnSize = rpnSize;
-		/* Make sure to update `rpnSize` above if modifying this! */
+		// Make sure to update `rpnSize` above if modifying this!
 		patch->rpn[0] = RPN_CONST;
 		patch->rpn[1] = (uint32_t)(expr->val) & 0xFF;
 		patch->rpn[2] = (uint32_t)(expr->val) >> 8;
@@ -435,9 +409,7 @@ static struct Patch *allocpatch(uint32_t type, struct Expression const *expr, ui
 	return patch;
 }
 
-/*
+// Create a new patch (includes the rpn expr)
- * Create a new patch (includes the rpn expr)
- */
 void out_CreatePatch(uint32_t type, struct Expression const *expr, uint32_t ofs, uint32_t pcShift)
 {
 	struct Patch *patch = allocpatch(type, expr, ofs);
@@ -451,9 +423,7 @@ void out_CreatePatch(uint32_t type, struct Expression const *expr, uint32_t ofs,
 	currentSection->patches = patch;
 }
 
-/**
+// Creates an assert that will be written to the object file
- * Creates an assert that will be written to the object file
- */
 bool out_CreateAssert(enum AssertionType type, struct Expression const *expr,
 		      char const *message, uint32_t ofs)
 {
@@ -490,7 +460,7 @@ static void freeassert(struct Assertion *assert)
 
 static void writeFileStackNode(struct FileStackNode const *node, FILE *f)
 {
-	putlong(node->parent ? node->parent->ID : -1, f);
+	putlong(node->parent ? node->parent->ID : (uint32_t)-1, f);
 	putlong(node->lineNo, f);
 	putc(node->type, f);
 	if (node->type != NODE_REPT) {
@@ -499,7 +469,7 @@ static void writeFileStackNode(struct FileStackNode const *node, FILE *f)
 		struct FileStackReptNode const *reptNode = (struct FileStackReptNode const *)node;
 
 		putlong(reptNode->reptDepth, f);
-		/* Iters are stored by decreasing depth, so reverse the order for output */
+		// Iters are stored by decreasing depth, so reverse the order for output
 		for (uint32_t i = reptNode->reptDepth; i--; )
 			putlong(reptNode->iters[i], f);
 	}
@@ -515,24 +485,22 @@ static void registerUnregisteredSymbol(struct Symbol *symbol, void *arg)
 	}
 }
 
-/*
+// Write an objectfile
- * Write an objectfile
- */
 void out_WriteObject(void)
 {
 	FILE *f;
 	if (strcmp(objectName, "-") != 0)
 		f = fopen(objectName, "wb");
 	else
-		f = fdopen(1, "wb");
+		f = fdopen(STDOUT_FILENO, "wb");
 
 	if (!f)
 		err("Couldn't write file '%s'", objectName);
 
-	/* Also write symbols that weren't written above */
+	// Also write symbols that weren't written above
 	sym_ForEach(registerUnregisteredSymbol, NULL);
 
-	fprintf(f, RGBDS_OBJECT_VERSION_STRING, RGBDS_OBJECT_VERSION_NUMBER);
+	fprintf(f, RGBDS_OBJECT_VERSION_STRING);
 	putlong(RGBDS_OBJECT_REV, f);
 
 	putlong(nbSymbols, f);
@@ -569,12 +537,12 @@ void out_WriteObject(void)
 	fclose(f);
 }
 
-/*
+// Set the objectfilename
- * Set the objectfilename
- */
 void out_SetFileName(char *s)
 {
+	if (objectName)
+		warnx("Overriding output filename %s", objectName);
 	objectName = s;
 	if (verbose)
-		printf("Output filename %s\n", s);
+		printf("Output filename %s\n", objectName);
 }

src/asm/parser.y

@@ -36,7 +36,7 @@
 #include "linkdefs.h"
 #include "platform.h" // strncasecmp, strdup
 
-static struct CaptureBody captureBody; /* Captures a REPT/FOR or MACRO */
+static struct CaptureBody captureBody; // Captures a REPT/FOR or MACRO
 
 static void upperstring(char *dest, char const *src)
 {
@@ -104,14 +104,14 @@ static size_t strlenUTF8(char const *s)
 		case 1:
 			errorInvalidUTF8Byte(byte, "STRLEN");
 			state = 0;
-			/* fallthrough */
+			// fallthrough
 		case 0:
 			len++;
 			break;
 		}
 	}
 
-	/* Check for partial code point. */
+	// Check for partial code point.
 	if (state != 0)
 		error("STRLEN: Incomplete UTF-8 character\n");
 
@@ -127,13 +127,13 @@ static void strsubUTF8(char *dest, size_t destLen, char const *src, uint32_t pos
 	uint32_t curLen = 0;
 	uint32_t curPos = 1;
 
-	/* Advance to starting position in source string. */
+	// Advance to starting position in source string.
 	while (src[srcIndex] && curPos < pos) {
 		switch (decode(&state, &codep, src[srcIndex])) {
 		case 1:
 			errorInvalidUTF8Byte(src[srcIndex], "STRSUB");
 			state = 0;
-			/* fallthrough */
+			// fallthrough
 		case 0:
 			curPos++;
 			break;
@@ -141,21 +141,19 @@ static void strsubUTF8(char *dest, size_t destLen, char const *src, uint32_t pos
 		srcIndex++;
 	}
 
-	/*
+	// A position 1 past the end of the string is allowed, but will trigger the
-	 * A position 1 past the end of the string is allowed, but will trigger the
+	// "Length too big" warning below if the length is nonzero.
-	 * "Length too big" warning below if the length is nonzero.
-	 */
 	if (!src[srcIndex] && pos > curPos)
 		warning(WARNING_BUILTIN_ARG,
 			"STRSUB: Position %" PRIu32 " is past the end of the string\n", pos);
 
-	/* Copy from source to destination. */
+	// Copy from source to destination.
 	while (src[srcIndex] && destIndex < destLen - 1 && curLen < len) {
 		switch (decode(&state, &codep, src[srcIndex])) {
 		case 1:
 			errorInvalidUTF8Byte(src[srcIndex], "STRSUB");
 			state = 0;
-			/* fallthrough */
+			// fallthrough
 		case 0:
 			curLen++;
 			break;
@@ -166,7 +164,7 @@ static void strsubUTF8(char *dest, size_t destLen, char const *src, uint32_t pos
 	if (curLen < len)
 		warning(WARNING_BUILTIN_ARG, "STRSUB: Length too big: %" PRIu32 "\n", len);
 
-	/* Check for partial code point. */
+	// Check for partial code point.
 	if (state != 0)
 		error("STRSUB: Incomplete UTF-8 character\n");
 
@@ -187,7 +185,7 @@ static void charsubUTF8(char *dest, char const *src, uint32_t pos)
 {
 	size_t charLen = 1;
 
-	/* Advance to starting position in source string. */
+	// Advance to starting position in source string.
 	for (uint32_t curPos = 1; charLen && curPos < pos; curPos++)
 		charLen = charmap_ConvertNext(&src, NULL);
 
@@ -197,7 +195,7 @@ static void charsubUTF8(char *dest, char const *src, uint32_t pos)
 		warning(WARNING_BUILTIN_ARG,
 			"CHARSUB: Position %" PRIu32 " is past the end of the string\n", pos);
 
-	/* Copy from source to destination. */
+	// Copy from source to destination.
 	memcpy(dest, start, src - start);
 
 	dest[src - start] = '\0';
@@ -205,10 +203,8 @@ static void charsubUTF8(char *dest, char const *src, uint32_t pos)
 
 static uint32_t adjustNegativePos(int32_t pos, size_t len, char const *functionName)
 {
-	/*
+	// STRSUB and CHARSUB adjust negative `pos` arguments the same way,
-	 * STRSUB and CHARSUB adjust negative `pos` arguments the same way,
+	// such that position -1 is the last character of a string.
-	 * such that position -1 is the last character of a string.
-	 */
 	if (pos < 0)
 		pos += len + 1;
 	if (pos < 1) {
@@ -218,10 +214,10 @@ static uint32_t adjustNegativePos(int32_t pos, size_t len, char const *functionN
 	return (uint32_t)pos;
 }
 
-static void strrpl(char *dest, size_t destLen, char const *src, char const *old, char const *new)
+static void strrpl(char *dest, size_t destLen, char const *src, char const *old, char const *rep)
 {
 	size_t oldLen = strlen(old);
-	size_t newLen = strlen(new);
+	size_t repLen = strlen(rep);
 	size_t i = 0;
 
 	if (!oldLen) {
@@ -240,8 +236,8 @@ static void strrpl(char *dest, size_t destLen, char const *src, char const *old,
 			break;
 
 		// Copy the replacement substring
-		memcpy(dest + i, new, newLen < destLen - i ? newLen : destLen - i);
+		memcpy(dest + i, rep, repLen < destLen - i ? repLen : destLen - i);
-		i += newLen;
+		i += repLen;
 		if (i >= destLen)
 			break;
 
@@ -385,7 +381,7 @@ static void initDsArgList(struct DsArgList *args)
 			   strerror(errno));
 }
 
-static size_t nextDsArgListIndex(struct DsArgList *args)
+static void appendDsArgList(struct DsArgList *args, const struct Expression *expr)
 {
 	if (args->nbArgs == args->capacity) {
 		args->capacity = (args->capacity + 1) * 2;
@@ -394,7 +390,7 @@ static size_t nextDsArgListIndex(struct DsArgList *args)
 			fatalerror("realloc error while resizing ds arg list: %s\n",
 				   strerror(errno));
 	}
-	return args->nbArgs++;
+	args->args[args->nbArgs++] = *expr;
 }
 
 static void freeDsArgList(struct DsArgList *args)
@@ -534,7 +530,7 @@ enum {
 %token	T_OP_LOGICNE "!=" T_OP_LOGICEQU "=="
 %token	T_OP_ADD "+" T_OP_SUB "-"
 %token	T_OP_OR "|" T_OP_XOR "^" T_OP_AND "&"
-%token	T_OP_SHL "<<" T_OP_SHR ">>"
+%token	T_OP_SHL "<<" T_OP_SHR ">>" T_OP_USHR ">>>"
 %token	T_OP_MUL "*" T_OP_DIV "/" T_OP_MOD "%"
 %token	T_OP_NOT "~"
 %left	T_OP_LOGICOR
@@ -542,10 +538,10 @@ enum {
 %left	T_OP_LOGICGT T_OP_LOGICLT T_OP_LOGICGE T_OP_LOGICLE T_OP_LOGICNE T_OP_LOGICEQU
 %left	T_OP_ADD T_OP_SUB
 %left	T_OP_OR T_OP_XOR T_OP_AND
-%left	T_OP_SHL T_OP_SHR
+%left	T_OP_SHL T_OP_SHR T_OP_USHR
 %left	T_OP_MUL T_OP_DIV T_OP_MOD
 
-%precedence	NEG /* negation -- unary minus */
+%precedence	NEG // negation -- unary minus
 
 %token	T_OP_EXP "**"
 %left	T_OP_EXP
@@ -554,14 +550,17 @@ enum {
 %token	T_OP_BANK "BANK"
 %token	T_OP_ALIGN "ALIGN"
 %token	T_OP_SIZEOF "SIZEOF" T_OP_STARTOF "STARTOF"
+
 %token	T_OP_SIN "SIN" T_OP_COS "COS" T_OP_TAN "TAN"
 %token	T_OP_ASIN "ASIN" T_OP_ACOS "ACOS" T_OP_ATAN "ATAN" T_OP_ATAN2 "ATAN2"
 %token	T_OP_FDIV "FDIV"
 %token	T_OP_FMUL "FMUL"
+%token	T_OP_FMOD "FMOD"
 %token	T_OP_POW "POW"
 %token	T_OP_LOG "LOG"
 %token	T_OP_ROUND "ROUND"
 %token	T_OP_CEIL "CEIL" T_OP_FLOOR "FLOOR"
+%type	<constValue> opt_q_arg
 
 %token	T_OP_HIGH "HIGH" T_OP_LOW "LOW"
 %token	T_OP_ISCONST "ISCONST"
@@ -587,7 +586,6 @@ enum {
 %type	<symName> scoped_id
 %type	<symName> scoped_anon_id
 %token	T_POP_EQU "EQU"
-%token	T_POP_SET "SET"
 %token	T_POP_EQUAL "="
 %token	T_POP_EQUS "EQUS"
 
@@ -599,7 +597,6 @@ enum {
 
 %token	T_POP_INCLUDE "INCLUDE"
 %token	T_POP_PRINT "PRINT" T_POP_PRINTLN "PRINTLN"
-%token	T_POP_PRINTF "PRINTF" T_POP_PRINTT "PRINTT" T_POP_PRINTV "PRINTV" T_POP_PRINTI "PRINTI"
 %token	T_POP_IF "IF" T_POP_ELIF "ELIF" T_POP_ELSE "ELSE" T_POP_ENDC "ENDC"
 %token	T_POP_EXPORT "EXPORT"
 %token	T_POP_DB "DB" T_POP_DS "DS" T_POP_DW "DW" T_POP_DL "DL"
@@ -642,7 +639,7 @@ enum {
 %type	<forArgs> for_args
 
 %token	T_Z80_ADC "adc" T_Z80_ADD "add" T_Z80_AND "and"
-%token	T_Z80_BIT "bit" // There is no T_Z80_SET, only T_POP_SET
+%token	T_Z80_BIT "bit"
 %token	T_Z80_CALL "call" T_Z80_CCF "ccf" T_Z80_CP "cp" T_Z80_CPL "cpl"
 %token	T_Z80_DAA "daa" T_Z80_DEC "dec" T_Z80_DI "di"
 %token	T_Z80_EI "ei"
@@ -659,7 +656,7 @@ enum {
 %token	T_Z80_RES "res" T_Z80_RET "ret" T_Z80_RETI "reti" T_Z80_RST "rst"
 %token	T_Z80_RL "rl" T_Z80_RLA "rla" T_Z80_RLC "rlc" T_Z80_RLCA "rlca"
 %token	T_Z80_RR "rr" T_Z80_RRA "rra" T_Z80_RRC "rrc" T_Z80_RRCA "rrca"
-%token	T_Z80_SBC "sbc" T_Z80_SCF "scf" T_Z80_STOP "stop"
+%token	T_Z80_SBC "sbc" T_Z80_SCF "scf" T_Z80_SET "set" T_Z80_STOP "stop"
 %token	T_Z80_SLA "sla" T_Z80_SRA "sra" T_Z80_SRL "srl" T_Z80_SUB "sub"
 %token	T_Z80_SWAP "swap"
 %token	T_Z80_XOR "xor"
@@ -707,8 +704,8 @@ plain_directive	: label
 ;
 
 line		: plain_directive endofline
-		| line_directive /* Directives that manage newlines themselves */
+		| line_directive // Directives that manage newlines themselves
-		/* Continue parsing the next line on a syntax error */
+		// Continue parsing the next line on a syntax error
 		| error {
 			lexer_SetMode(LEXER_NORMAL);
 			lexer_ToggleStringExpansion(true);
@@ -716,7 +713,7 @@ line		: plain_directive endofline
 			fstk_StopRept();
 			yyerrok;
 		}
-		/* Hint about unindented macros parsed as labels */
+		// Hint about unindented macros parsed as labels
 		| T_LABEL error {
 			lexer_SetMode(LEXER_NORMAL);
 			lexer_ToggleStringExpansion(true);
@@ -731,19 +728,17 @@ line		: plain_directive endofline
 		}
 ;
 
-/*
+// For "logistical" reasons, these directives must manage newlines themselves.
- * For "logistical" reasons, these directives must manage newlines themselves.
+// This is because we need to switch the lexer's mode *after* the newline has been read,
- * This is because we need to switch the lexer's mode *after* the newline has been read,
+// and to avoid causing some grammar conflicts (token reducing is finicky).
- * and to avoid causing some grammar conflicts (token reducing is finicky).
+// This is DEFINITELY one of the more FRAGILE parts of the codebase, handle with care.
- * This is DEFINITELY one of the more FRAGILE parts of the codebase, handle with care.
- */
 line_directive	: macrodef
 		| rept
 		| for
 		| break
 		| include
 		| if
-		/* It's important that all of these require being at line start for `skipIfBlock` */
+		// It's important that all of these require being at line start for `skipIfBlock`
 		| elif
 		| else
 ;
@@ -854,9 +849,9 @@ macroargs	: %empty {
 		}
 ;
 
-/* These commands start with a T_LABEL. */
+// These commands start with a T_LABEL.
 assignment_directive	: equ
-		| set
+		| assignment
 		| rb
 		| rw
 		| rl
@@ -866,10 +861,6 @@ assignment_directive	: equ
 directive	: endc
 		| print
 		| println
-		| printf
-		| printt
-		| printv
-		| printi
 		| export
 		| db
 		| dw
@@ -927,12 +918,8 @@ compoundeq	: T_POP_ADDEQ { $$ = RPN_ADD; }
 equ		: T_LABEL T_POP_EQU const { sym_AddEqu($1, $3); }
 ;
 
-set		: T_LABEL T_POP_EQUAL const { sym_AddVar($1, $3); }
+assignment	: T_LABEL T_POP_EQUAL const { sym_AddVar($1, $3); }
 		| T_LABEL compoundeq const { compoundAssignment($1, $2, $3); }
-		| T_LABEL T_POP_SET const {
-			warning(WARNING_OBSOLETE, "`SET` for variables is deprecated; use `=`\n");
-			sym_AddVar($1, $3);
-		}
 ;
 
 equs		: T_LABEL T_POP_EQUS string { sym_AddString($1, $3); }
@@ -1108,6 +1095,7 @@ macrodef	: T_POP_MACRO {
 					     captureBody.size);
 		}
 		| T_LABEL T_COLON T_POP_MACRO T_NEWLINE {
+			warning(WARNING_OBSOLETE, "`%s: MACRO` is deprecated; use `MACRO %s`\n", $1, $1);
 			$<captureTerminated>$ = lexer_CaptureMacroBody(&captureBody);
 		} endofline {
 			if ($<captureTerminated>5)
@@ -1144,14 +1132,10 @@ ds		: T_POP_DS uconst { sect_Skip($2, true); }
 
 ds_args		: reloc_8bit {
 			initDsArgList(&$$);
-			size_t i = nextDsArgListIndex(&$$);
+			appendDsArgList(&$$, &$1);
-
-			$$.args[i] = $1;
 		}
 		| ds_args T_COMMA reloc_8bit {
-			size_t i = nextDsArgListIndex(&$1);
+			appendDsArgList(&$1, &$3);
-
-			$1.args[i] = $3;
 			$$ = $1;
 		}
 ;
@@ -1178,14 +1162,6 @@ def_set		: def_id T_POP_EQUAL const { sym_AddVar($1, $3); }
 		| redef_id T_POP_EQUAL const { sym_AddVar($1, $3); }
 		| def_id compoundeq const { compoundAssignment($1, $2, $3); }
 		| redef_id compoundeq const { compoundAssignment($1, $2, $3); }
-		| def_id T_POP_SET const {
-			warning(WARNING_OBSOLETE, "`SET` for variables is deprecated; use `=`\n");
-			sym_AddVar($1, $3);
-		}
-		| redef_id T_POP_SET const {
-			warning(WARNING_OBSOLETE, "`SET` for variables is deprecated; use `=`\n");
-			sym_AddVar($1, $3);
-		}
 ;
 
 def_rb		: def_id T_POP_RB rs_uconst {
@@ -1299,30 +1275,6 @@ print_expr	: const_no_str { printf("$%" PRIX32, $1); }
 		| string { printf("%s", $1); }
 ;
 
-printt		: T_POP_PRINTT string {
-			warning(WARNING_OBSOLETE, "`PRINTT` is deprecated; use `PRINT`\n");
-			printf("%s", $2);
-		}
-;
-
-printv		: T_POP_PRINTV const {
-			warning(WARNING_OBSOLETE, "`PRINTV` is deprecated; use `PRINT`\n");
-			printf("$%" PRIX32, $2);
-		}
-;
-
-printi		: T_POP_PRINTI const {
-			warning(WARNING_OBSOLETE, "`PRINTI` is deprecated; use `PRINT` with `STRFMT` \"%%d\"\n");
-			printf("%" PRId32, $2);
-		}
-;
-
-printf		: T_POP_PRINTF const {
-			warning(WARNING_OBSOLETE, "`PRINTF` is deprecated; use `PRINT` with `STRFMT` \"%%f\"\n");
-			fix_Print($2);
-		}
-;
-
 const_3bit	: const {
 			int32_t value = $1;
 
@@ -1343,7 +1295,7 @@ constlist_8bit_entry : reloc_8bit_no_str {
 			sect_RelByte(&$1, 0);
 		}
 		| string {
-			uint8_t *output = malloc(strlen($1)); /* Cannot be larger than that */
+			uint8_t *output = malloc(strlen($1)); // Cannot be larger than that
 			size_t length = charmap_Convert($1, output);
 
 			sect_AbsByteGroup(output, length);
@@ -1359,7 +1311,7 @@ constlist_16bit_entry : reloc_16bit_no_str {
 			sect_RelWord(&$1, 0);
 		}
 		| string {
-			uint8_t *output = malloc(strlen($1)); /* Cannot be larger than that */
+			uint8_t *output = malloc(strlen($1)); // Cannot be larger than that
 			size_t length = charmap_Convert($1, output);
 
 			sect_AbsWordGroup(output, length);
@@ -1481,6 +1433,9 @@ relocexpr_no_str : scoped_anon_id { rpn_Symbol(&$$, $1); }
 		| relocexpr T_OP_SHR relocexpr {
 			rpn_BinaryOp(RPN_SHR, &$$, &$1, &$3);
 		}
+		| relocexpr T_OP_USHR relocexpr {
+			rpn_BinaryOp(RPN_USHR, &$$, &$1, &$3);
+		}
 		| relocexpr T_OP_MUL relocexpr {
 			rpn_BinaryOp(RPN_MUL, &$$, &$1, &$3);
 		}
@@ -1509,53 +1464,54 @@ relocexpr_no_str : scoped_anon_id { rpn_Symbol(&$$, $1); }
 		| T_OP_DEF {
 			lexer_ToggleStringExpansion(false);
 		} T_LPAREN scoped_anon_id T_RPAREN {
-			struct Symbol const *sym = sym_FindScopedSymbol($4);
+			rpn_Number(&$$, sym_FindScopedValidSymbol($4) != NULL);
-
-			rpn_Number(&$$, !!sym);
 
 			lexer_ToggleStringExpansion(true);
 		}
-		| T_OP_ROUND T_LPAREN const T_RPAREN {
+		| T_OP_ROUND T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Round($3));
+			rpn_Number(&$$, fix_Round($3, $4));
 		}
-		| T_OP_CEIL T_LPAREN const T_RPAREN {
+		| T_OP_CEIL T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Ceil($3));
+			rpn_Number(&$$, fix_Ceil($3, $4));
 		}
-		| T_OP_FLOOR T_LPAREN const T_RPAREN {
+		| T_OP_FLOOR T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Floor($3));
+			rpn_Number(&$$, fix_Floor($3, $4));
 		}
-		| T_OP_FDIV T_LPAREN const T_COMMA const T_RPAREN {
+		| T_OP_FDIV T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Div($3, $5));
+			rpn_Number(&$$, fix_Div($3, $5, $6));
 		}
-		| T_OP_FMUL T_LPAREN const T_COMMA const T_RPAREN {
+		| T_OP_FMUL T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Mul($3, $5));
+			rpn_Number(&$$, fix_Mul($3, $5, $6));
 		}
-		| T_OP_POW T_LPAREN const T_COMMA const T_RPAREN {
+		| T_OP_FMOD T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Pow($3, $5));
+			rpn_Number(&$$, fix_Mod($3, $5, $6));
 		}
-		| T_OP_LOG T_LPAREN const T_COMMA const T_RPAREN {
+		| T_OP_POW T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Log($3, $5));
+			rpn_Number(&$$, fix_Pow($3, $5, $6));
 		}
-		| T_OP_SIN T_LPAREN const T_RPAREN {
+		| T_OP_LOG T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Sin($3));
+			rpn_Number(&$$, fix_Log($3, $5, $6));
 		}
-		| T_OP_COS T_LPAREN const T_RPAREN {
+		| T_OP_SIN T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Cos($3));
+			rpn_Number(&$$, fix_Sin($3, $4));
 		}
-		| T_OP_TAN T_LPAREN const T_RPAREN {
+		| T_OP_COS T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_Tan($3));
+			rpn_Number(&$$, fix_Cos($3, $4));
 		}
-		| T_OP_ASIN T_LPAREN const T_RPAREN {
+		| T_OP_TAN T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_ASin($3));
+			rpn_Number(&$$, fix_Tan($3, $4));
 		}
-		| T_OP_ACOS T_LPAREN const T_RPAREN {
+		| T_OP_ASIN T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_ACos($3));
+			rpn_Number(&$$, fix_ASin($3, $4));
 		}
-		| T_OP_ATAN T_LPAREN const T_RPAREN {
+		| T_OP_ACOS T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_ATan($3));
+			rpn_Number(&$$, fix_ACos($3, $4));
 		}
-		| T_OP_ATAN2 T_LPAREN const T_COMMA const T_RPAREN {
+		| T_OP_ATAN T_LPAREN const opt_q_arg T_RPAREN {
-			rpn_Number(&$$, fix_ATan2($3, $5));
+			rpn_Number(&$$, fix_ATan($3, $4));
+		}
+		| T_OP_ATAN2 T_LPAREN const T_COMMA const opt_q_arg T_RPAREN {
+			rpn_Number(&$$, fix_ATan2($3, $5, $6));
 		}
 		| T_OP_STRCMP T_LPAREN string T_COMMA string T_RPAREN {
 			rpn_Number(&$$, strcmp($3, $5));
@@ -1582,7 +1538,7 @@ relocexpr_no_str : scoped_anon_id { rpn_Symbol(&$$, $1); }
 uconst		: const {
 			$$ = $1;
 			if ($$ < 0)
-				fatalerror("Constant mustn't be negative: %d\n", $1);
+				fatalerror("Constant must not be negative: %d\n", $1);
 		}
 ;
 
@@ -1595,6 +1551,17 @@ const_no_str	: relocexpr_no_str { $$ = rpn_GetConstVal(&$1); }
 const_8bit	: reloc_8bit { $$ = rpn_GetConstVal(&$1); }
 ;
 
+opt_q_arg	: %empty { $$ = fix_Precision(); }
+		| T_COMMA const {
+			if ($2 >= 1 && $2 <= 31) {
+				$$ = $2;
+			} else {
+				error("Fixed-point precision must be between 1 and 31\n");
+				$$ = fix_Precision();
+			}
+		}
+;
+
 string		: T_STRING
 		| T_OP_STRSUB T_LPAREN string T_COMMA const T_COMMA uconst T_RPAREN {
 			size_t len = strlenUTF8($3);
@@ -1633,6 +1600,19 @@ string		: T_STRING
 			strfmt($$, sizeof($$), $3.format, $3.nbArgs, $3.args);
 			freeStrFmtArgList(&$3);
 		}
+		| T_POP_SECTION T_LPAREN scoped_anon_id T_RPAREN {
+			struct Symbol *sym = sym_FindScopedValidSymbol($3);
+
+			if (!sym)
+				fatalerror("Unknown symbol \"%s\"\n", $3);
+			struct Section const *section = sym_GetSection(sym);
+
+			if (!section)
+				fatalerror("\"%s\" does not belong to any section\n", sym->name);
+			// Section names are capped by rgbasm's maximum string length,
+			// so this currently can't overflow.
+			strcpy($$, section->name);
+		}
 ;
 
 strcat_args	: string
@@ -1718,7 +1698,7 @@ sectattrs	: %empty {
 			$$.alignOfs = $7;
 		}
 		| sectattrs T_COMMA T_OP_BANK T_LBRACK uconst T_RBRACK {
-			/* We cannot check the validity of this now */
+			// We cannot check the validity of this now
 			$$.bank = $5;
 		}
 ;
@@ -1843,8 +1823,13 @@ z80_ei		: T_Z80_EI { sect_AbsByte(0xFB); }
 
 z80_halt	: T_Z80_HALT {
 			sect_AbsByte(0x76);
-			if (haltnop)
+			if (haltnop) {
+				if (warnOnHaltNop) {
+					warnOnHaltNop = false;
+					warning(WARNING_OBSOLETE, "`nop` after `halt` will stop being the default; pass `-H` to opt into it\n");
+				}
 				sect_AbsByte(0x00);
+			}
 		}
 ;
 
@@ -1952,6 +1937,10 @@ z80_ld_mem	: T_Z80_LD op_mem_ind T_COMMA T_MODE_SP {
 		| T_Z80_LD op_mem_ind T_COMMA T_MODE_A {
 			if (optimizeLoads && rpn_isKnown(&$2)
 			 && $2.val >= 0xFF00) {
+				if (warnOnLdOpt) {
+					warnOnLdOpt = false;
+					warning(WARNING_OBSOLETE, "ld optimization will stop being the default; pass `-l` to opt into it\n");
+				}
 				sect_AbsByte(0xE0);
 				sect_AbsByte($2.val & 0xFF);
 				rpn_Free(&$2);
@@ -2000,6 +1989,10 @@ z80_ld_a	: T_Z80_LD reg_r T_COMMA c_ind {
 			if ($2 == REG_A) {
 				if (optimizeLoads && rpn_isKnown(&$4)
 				 && $4.val >= 0xFF00) {
+					if (warnOnLdOpt) {
+						warnOnLdOpt = false;
+						warning(WARNING_OBSOLETE, "ld optimization will stop being the default; pass `-l` to opt into it\n");
+					}
 					sect_AbsByte(0xF0);
 					sect_AbsByte($4.val & 0xFF);
 					rpn_Free(&$4);
@@ -2022,10 +2015,8 @@ z80_ld_ss	: T_Z80_LD T_MODE_BC T_COMMA reloc_16bit {
 			sect_AbsByte(0x01 | (REG_DE << 4));
 			sect_RelWord(&$4, 1);
 		}
-		/*
+		// HL is taken care of in z80_ld_hl
-		 * HL is taken care of in z80_ld_hl
+		// SP is taken care of in z80_ld_sp
-		 * SP is taken care of in z80_ld_sp
-		 */
 ;
 
 z80_nop		: T_Z80_NOP { sect_AbsByte(0x00); }
@@ -2113,7 +2104,7 @@ z80_sbc		: T_Z80_SBC op_a_n {
 z80_scf		: T_Z80_SCF { sect_AbsByte(0x37); }
 ;
 
-z80_set		: T_POP_SET const_3bit T_COMMA reg_r {
+z80_set		: T_Z80_SET const_3bit T_COMMA reg_r {
 			sect_AbsByte(0xCB);
 			sect_AbsByte(0xC0 | ($2 << 3) | $4);
 		}

src/asm/rpn.c

@@ -6,9 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*
+// Controls RPN expressions for objectfiles
- * Controls RPN expressions for objectfiles
- */
 
 #include <assert.h>
 #include <errno.h>
@@ -28,7 +26,7 @@
 
 #include "opmath.h"
 
-/* Makes an expression "not known", also setting its error message */
+// Makes an expression "not known", also setting its error message
 #define makeUnknown(expr_, ...) do { \
 	struct Expression *_expr = expr_; \
 	_expr->isKnown = false; \
@@ -39,23 +37,23 @@
 	int size = snprintf(_expr->reason, 128, __VA_ARGS__); \
 	if (size >= 128) { /* If this wasn't enough, try again */ \
 		_expr->reason = realloc(_expr->reason, size + 1); \
+		if (!_expr->reason) \
+			fatalerror("Can't allocate err string: %s\n", strerror(errno)); \
 		sprintf(_expr->reason, __VA_ARGS__); \
 	} \
 } while (0)
 
 static uint8_t *reserveSpace(struct Expression *expr, uint32_t size)
 {
-	/* This assumes the RPN length is always less than the capacity */
+	// This assumes the RPN length is always less than the capacity
 	if (expr->rpnCapacity - expr->rpnLength < size) {
-		/* If there isn't enough room to reserve the space, realloc */
+		// If there isn't enough room to reserve the space, realloc
 		if (!expr->rpn)
-			expr->rpnCapacity = 256; /* Initial size */
+			expr->rpnCapacity = 256; // Initial size
 		while (expr->rpnCapacity - expr->rpnLength < size) {
 			if (expr->rpnCapacity >= MAXRPNLEN)
-				/*
+				// To avoid generating humongous object files, cap the
-				 * To avoid generating humongous object files, cap the
+				// size of RPN expressions
-				 * size of RPN expressions
-				 */
 				fatalerror("RPN expression cannot grow larger than "
 					   EXPAND_AND_STR(MAXRPNLEN) " bytes\n");
 			else if (expr->rpnCapacity > MAXRPNLEN / 2)
@@ -75,9 +73,7 @@ static uint8_t *reserveSpace(struct Expression *expr, uint32_t size)
 	return ptr;
 }
 
-/*
+// Init a RPN expression
- * Init a RPN expression
- */
 static void rpn_Init(struct Expression *expr)
 {
 	expr->reason = NULL;
@@ -89,9 +85,7 @@ static void rpn_Init(struct Expression *expr)
 	expr->rpnPatchSize = 0;
 }
 
-/*
+// Free the RPN expression
- * Free the RPN expression
- */
 void rpn_Free(struct Expression *expr)
 {
 	free(expr->rpn);
@@ -99,9 +93,7 @@ void rpn_Free(struct Expression *expr)
 	rpn_Init(expr);
 }
 
-/*
+// Add symbols, constants and operators to expression
- * Add symbols, constants and operators to expression
- */
 void rpn_Number(struct Expression *expr, uint32_t i)
 {
 	rpn_Init(expr);
@@ -122,9 +114,9 @@ void rpn_Symbol(struct Expression *expr, char const *symName)
 		makeUnknown(expr, sym_IsPC(sym) ? "PC is not constant at assembly time"
 						: "'%s' is not constant at assembly time", symName);
 		sym = sym_Ref(symName);
-		expr->rpnPatchSize += 5; /* 1-byte opcode + 4-byte symbol ID */
+		expr->rpnPatchSize += 5; // 1-byte opcode + 4-byte symbol ID
 
-		size_t nameLen = strlen(sym->name) + 1; /* Don't forget NUL! */
+		size_t nameLen = strlen(sym->name) + 1; // Don't forget NUL!
 		uint8_t *ptr = reserveSpace(expr, nameLen + 1);
 		*ptr++ = RPN_SYM;
 		memcpy(ptr, sym->name, nameLen);
@@ -153,7 +145,7 @@ void rpn_BankSymbol(struct Expression *expr, char const *symName)
 {
 	struct Symbol const *sym = sym_FindScopedSymbol(symName);
 
-	/* The @ symbol is treated differently. */
+	// The @ symbol is treated differently.
 	if (sym_IsPC(sym)) {
 		rpn_BankSelf(expr);
 		return;
@@ -167,13 +159,13 @@ void rpn_BankSymbol(struct Expression *expr, char const *symName)
 		assert(sym); // If the symbol didn't exist, it should have been created
 
 		if (sym_GetSection(sym) && sym_GetSection(sym)->bank != (uint32_t)-1) {
-			/* Symbol's section is known and bank is fixed */
+			// Symbol's section is known and bank is fixed
 			expr->val = sym_GetSection(sym)->bank;
 		} else {
 			makeUnknown(expr, "\"%s\"'s bank is not known", symName);
-			expr->rpnPatchSize += 5; /* opcode + 4-byte sect ID */
+			expr->rpnPatchSize += 5; // opcode + 4-byte sect ID
 
-			size_t nameLen = strlen(sym->name) + 1; /* Room for NUL! */
+			size_t nameLen = strlen(sym->name) + 1; // Room for NUL!
 			uint8_t *ptr = reserveSpace(expr, nameLen + 1);
 			*ptr++ = RPN_BANK_SYM;
 			memcpy(ptr, sym->name, nameLen);
@@ -192,7 +184,7 @@ void rpn_BankSection(struct Expression *expr, char const *sectionName)
 	} else {
 		makeUnknown(expr, "Section \"%s\"'s bank is not known", sectionName);
 
-		size_t nameLen = strlen(sectionName) + 1; /* Room for NUL! */
+		size_t nameLen = strlen(sectionName) + 1; // Room for NUL!
 		uint8_t *ptr = reserveSpace(expr, nameLen + 1);
 
 		expr->rpnPatchSize += nameLen + 1;
@@ -212,7 +204,7 @@ void rpn_SizeOfSection(struct Expression *expr, char const *sectionName)
 	} else {
 		makeUnknown(expr, "Section \"%s\"'s size is not known", sectionName);
 
-		size_t nameLen = strlen(sectionName) + 1; /* Room for NUL! */
+		size_t nameLen = strlen(sectionName) + 1; // Room for NUL!
 		uint8_t *ptr = reserveSpace(expr, nameLen + 1);
 
 		expr->rpnPatchSize += nameLen + 1;
@@ -232,7 +224,7 @@ void rpn_StartOfSection(struct Expression *expr, char const *sectionName)
 	} else {
 		makeUnknown(expr, "Section \"%s\"'s start is not known", sectionName);
 
-		size_t nameLen = strlen(sectionName) + 1; /* Room for NUL! */
+		size_t nameLen = strlen(sectionName) + 1; // Room for NUL!
 		uint8_t *ptr = reserveSpace(expr, nameLen + 1);
 
 		expr->rpnPatchSize += nameLen + 1;
@@ -250,7 +242,7 @@ void rpn_CheckHRAM(struct Expression *expr, const struct Expression *src)
 		expr->rpnPatchSize++;
 		*reserveSpace(expr, 1) = RPN_HRAM;
 	} else if (expr->val >= 0xFF00 && expr->val <= 0xFFFF) {
-		/* That range is valid, but only keep the lower byte */
+		// That range is valid, but only keep the lower byte
 		expr->val &= 0xFF;
 	} else if (expr->val < 0 || expr->val > 0xFF) {
 		error("Source address $%" PRIx32 " not between $FF00 to $FFFF\n", expr->val);
@@ -262,10 +254,10 @@ void rpn_CheckRST(struct Expression *expr, const struct Expression *src)
 	*expr = *src;
 
 	if (rpn_isKnown(expr)) {
-		/* A valid RST address must be masked with 0x38 */
+		// A valid RST address must be masked with 0x38
 		if (expr->val & ~0x38)
 			error("Invalid address $%" PRIx32 " for RST\n", expr->val);
-		/* The target is in the "0x38" bits, all other bits are set */
+		// The target is in the "0x38" bits, all other bits are set
 		expr->val |= 0xC7;
 	} else {
 		expr->rpnPatchSize++;
@@ -273,9 +265,7 @@ void rpn_CheckRST(struct Expression *expr, const struct Expression *src)
 	}
 }
 
-/*
+// Checks that an RPN expression's value fits within N bits (signed or unsigned)
- * Checks that an RPN expression's value fits within N bits (signed or unsigned)
- */
 void rpn_CheckNBit(struct Expression const *expr, uint8_t n)
 {
 	assert(n != 0); // That doesn't make sense
@@ -317,12 +307,12 @@ struct Symbol const *rpn_SymbolOf(struct Expression const *expr)
 {
 	if (!rpn_isSymbol(expr))
 		return NULL;
-	return sym_FindScopedSymbol((char *)expr->rpn + 1);
+	return sym_FindScopedSymbol((char const *)expr->rpn + 1);
 }
 
 bool rpn_IsDiffConstant(struct Expression const *src, struct Symbol const *sym)
 {
-	/* Check if both expressions only refer to a single symbol */
+	// Check if both expressions only refer to a single symbol
 	struct Symbol const *sym1 = rpn_SymbolOf(src);
 
 	if (!sym1 || !sym || sym1->type != SYM_LABEL || sym->type != SYM_LABEL)
@@ -339,17 +329,58 @@ static bool isDiffConstant(struct Expression const *src1,
 	return rpn_IsDiffConstant(src1, rpn_SymbolOf(src2));
 }
 
+/*
+ * Attempts to compute a constant binary AND from non-constant operands
+ * This is possible if one operand is a symbol belonging to an `ALIGN[N]` section, and the other is
+ * a constant that only keeps (some of) the lower N bits.
+ *
+ * @return The constant result if it can be computed, or -1 otherwise.
+ */
+static int32_t tryConstMask(struct Expression const *lhs, struct Expression const *rhs)
+{
+	struct Symbol const *sym = rpn_SymbolOf(lhs);
+	struct Expression const *expr = rhs;
+
+	if (!sym || !sym_GetSection(sym)) {
+		// If the lhs isn't a symbol, try again the other way around
+		sym = rpn_SymbolOf(rhs);
+		expr = lhs;
+
+		if (!sym || !sym_GetSection(sym))
+			return -1;
+	}
+	assert(sym_IsNumeric(sym));
+
+	if (!rpn_isKnown(expr))
+		return -1;
+	// We can now safely use `expr->val`
+	struct Section const *sect = sym_GetSection(sym);
+	int32_t unknownBits = (1 << 16) - (1 << sect->align); // The max alignment is 16
+
+	// The mask must ignore all unknown bits
+	if ((expr->val & unknownBits) != 0)
+		return -1;
+
+	// `sym_GetValue()` attempts to add the section's address,
+	// but that's "-1" because the section is floating (otherwise we wouldn't be here)
+	assert(sect->org == (uint32_t)-1);
+	int32_t symbolOfs = sym_GetValue(sym) + 1;
+
+	return (symbolOfs + sect->alignOfs) & ~unknownBits;
+}
+
 void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 		  const struct Expression *src1, const struct Expression *src2)
 {
 	expr->isSymbol = false;
+	int32_t constMaskVal;
 
-	/* First, check if the expression is known */
+	// First, check if the expression is known
 	expr->isKnown = src1->isKnown && src2->isKnown;
 	if (expr->isKnown) {
-		rpn_Init(expr); /* Init the expression to something sane */
+		rpn_Init(expr); // Init the expression to something sane
 
-		/* If both expressions are known, just compute the value */
+		// If both expressions are known, just compute the value
 		uint32_t uleft = src1->val, uright = src2->val;
 
 		switch (op) {
@@ -421,6 +452,19 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 
 			expr->val = op_shift_right(src1->val, src2->val);
 			break;
+		case RPN_USHR:
+			if (src2->val < 0)
+				warning(WARNING_SHIFT_AMOUNT,
+					"Shifting right by negative amount %" PRId32 "\n",
+					src2->val);
+
+			if (src2->val >= 32)
+				warning(WARNING_SHIFT_AMOUNT,
+					"Shifting right by large amount %" PRId32 "\n",
+					src2->val);
+
+			expr->val = op_shift_right_unsigned(src1->val, src2->val);
+			break;
 		case RPN_MUL:
 			expr->val = uleft * uright;
 			break;
@@ -477,10 +521,13 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 
 		expr->val = sym_GetValue(symbol1) - sym_GetValue(symbol2);
 		expr->isKnown = true;
+	} else if (op == RPN_AND && (constMaskVal = tryConstMask(src1, src2)) != -1) {
+		expr->val = constMaskVal;
+		expr->isKnown = true;
 	} else {
-		/* If it's not known, start computing the RPN expression */
+		// If it's not known, start computing the RPN expression
 
-		/* Convert the left-hand expression if it's constant */
+		// Convert the left-hand expression if it's constant
 		if (src1->isKnown) {
 			uint32_t lval = src1->val;
 			uint8_t bytes[] = {RPN_CONST, lval, lval >> 8,
@@ -492,11 +539,11 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 			memcpy(reserveSpace(expr, sizeof(bytes)), bytes,
 			       sizeof(bytes));
 
-			/* Use the other expression's un-const reason */
+			// Use the other expression's un-const reason
 			expr->reason = src2->reason;
 			free(src1->reason);
 		} else {
-			/* Otherwise just reuse its RPN buffer */
+			// Otherwise just reuse its RPN buffer
 			expr->rpnPatchSize = src1->rpnPatchSize;
 			expr->rpn = src1->rpn;
 			expr->rpnCapacity = src1->rpnCapacity;
@@ -505,12 +552,12 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 			free(src2->reason);
 		}
 
-		/* Now, merge the right expression into the left one */
+		// Now, merge the right expression into the left one
-		uint8_t *ptr = src2->rpn; /* Pointer to the right RPN */
+		uint8_t *ptr = src2->rpn; // Pointer to the right RPN
-		uint32_t len = src2->rpnLength; /* Size of the right RPN */
+		uint32_t len = src2->rpnLength; // Size of the right RPN
 		uint32_t patchSize = src2->rpnPatchSize;
 
-		/* If the right expression is constant, merge a shim instead */
+		// If the right expression is constant, merge a shim instead
 		uint32_t rval = src2->val;
 		uint8_t bytes[] = {RPN_CONST, rval, rval >> 8, rval >> 16,
 				   rval >> 24};
@@ -519,13 +566,13 @@ void rpn_BinaryOp(enum RPNCommand op, struct Expression *expr,
 			len = sizeof(bytes);
 			patchSize = sizeof(bytes);
 		}
-		/* Copy the right RPN and append the operator */
+		// Copy the right RPN and append the operator
 		uint8_t *buf = reserveSpace(expr, len + 1);
 
 		memcpy(buf, ptr, len);
 		buf[len] = op;
 
-		free(src2->rpn); /* If there was none, this is `free(NULL)` */
+		free(src2->rpn); // If there was none, this is `free(NULL)`
 		expr->rpnPatchSize += patchSize + 1;
 	}
 }

src/asm/section.c

@@ -1,3 +1,10 @@
+/*
+ * This file is part of RGBDS.
+ *
+ * Copyright (c) 2022, RGBDS contributors.
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
 #include <assert.h>
 #include <errno.h>
@@ -16,6 +23,7 @@
 #include "asm/warning.h"
 
 #include "error.h"
+#include "linkdefs.h"
 #include "platform.h" // strdup
 
 uint8_t fillByte;
@@ -29,7 +37,7 @@ struct UnionStackEntry {
 struct SectionStackEntry {
 	struct Section *section;
 	struct Section *loadSection;
-	char const *scope; /* Section's symbol scope */
+	char const *scope; // Section's symbol scope
 	uint32_t offset;
 	int32_t loadOffset;
 	struct UnionStackEntry *unionStack;
@@ -37,14 +45,12 @@ struct SectionStackEntry {
 };
 
 struct SectionStackEntry *sectionStack;
-uint32_t curOffset; /* Offset into the current section (see sect_GetSymbolOffset) */
+uint32_t curOffset; // Offset into the current section (see sect_GetSymbolOffset)
 struct Section *currentSection = NULL;
 static struct Section *currentLoadSection = NULL;
-int32_t loadOffset; /* Offset into the LOAD section's parent (see sect_GetOutputOffset) */
+int32_t loadOffset; // Offset into the LOAD section's parent (see sect_GetOutputOffset)
 
-/*
+// A quick check to see if we have an initialized section
- * A quick check to see if we have an initialized section
- */
 attr_(warn_unused_result) static bool checksection(void)
 {
 	if (currentSection)
@@ -54,10 +60,8 @@ attr_(warn_unused_result) static bool checksection(void)
 	return false;
 }
 
-/*
+// A quick check to see if we have an initialized section that can contain
- * A quick check to see if we have an initialized section that can contain
+// this much initialized data
- * this much initialized data
- */
 attr_(warn_unused_result) static bool checkcodesection(void)
 {
 	if (!checksection())
@@ -73,7 +77,7 @@ attr_(warn_unused_result) static bool checkcodesection(void)
 
 attr_(warn_unused_result) static bool checkSectionSize(struct Section const *sect, uint32_t size)
 {
-	uint32_t maxSize = maxsize[sect->type];
+	uint32_t maxSize = sectionTypeInfo[sect->type].size;
 
 	// If the new size is reasonable, keep going
 	if (size <= maxSize)
@@ -84,17 +88,13 @@ attr_(warn_unused_result) static bool checkSectionSize(struct Section const *sec
 	return false;
 }
 
-/*
+// Check if the section has grown too much.
- * Check if the section has grown too much.
- */
 attr_(warn_unused_result) static bool reserveSpace(uint32_t delta_size)
 {
-	/*
+	// This check is here to trap broken code that generates sections that are too big and to
-	 * This check is here to trap broken code that generates sections that are too big and to
+	// prevent the assembler from generating huge object files or trying to allocate too much
-	 * prevent the assembler from generating huge object files or trying to allocate too much
+	// memory.
-	 * memory.
+	// A check at the linking stage is still necessary.
-	 * A check at the linking stage is still necessary.
-	 */
 
 	// If the section has already overflowed, skip the check to avoid erroring out ad nauseam
 	if (currentSection->size != UINT32_MAX
@@ -132,15 +132,13 @@ static unsigned int mergeSectUnion(struct Section *sect, enum SectionType type,
 	assert(alignment < 16); // Should be ensured by the caller
 	unsigned int nbSectErrors = 0;
 
-	/*
+	// Unionized sections only need "compatible" constraints, and they end up with the strictest
-	 * Unionized sections only need "compatible" constraints, and they end up with the strictest
+	// combination of both.
-	 * combination of both.
-	 */
 	if (sect_HasData(type))
 		fail("Cannot declare ROM sections as UNION\n");
 
 	if (org != (uint32_t)-1) {
-		/* If both are fixed, they must be the same */
+		// If both are fixed, they must be the same
 		if (sect->org != (uint32_t)-1 && sect->org != org)
 			fail("Section already declared as fixed at different address $%04"
 			     PRIx32 "\n", sect->org);
@@ -148,16 +146,16 @@ static unsigned int mergeSectUnion(struct Section *sect, enum SectionType type,
 			fail("Section already declared as aligned to %u bytes (offset %"
 				   PRIu16 ")\n", 1U << sect->align, sect->alignOfs);
 		else
-			/* Otherwise, just override */
+			// Otherwise, just override
 			sect->org = org;
 
 	} else if (alignment != 0) {
-		/* Make sure any fixed address given is compatible */
+		// Make sure any fixed address given is compatible
 		if (sect->org != (uint32_t)-1) {
 			if ((sect->org - alignOffset) & mask(alignment))
 				fail("Section already declared as fixed at incompatible address $%04"
 				     PRIx32 "\n", sect->org);
-		/* Check if alignment offsets are compatible */
+		// Check if alignment offsets are compatible
 		} else if ((alignOffset & mask(sect->align))
 			   != (sect->alignOfs & mask(alignment))) {
 			fail("Section already declared with incompatible %u"
@@ -180,15 +178,13 @@ static unsigned int mergeFragments(struct Section *sect, enum SectionType type,
 	assert(alignment < 16); // Should be ensured by the caller
 	unsigned int nbSectErrors = 0;
 
-	/*
+	// Fragments only need "compatible" constraints, and they end up with the strictest
-	 * Fragments only need "compatible" constraints, and they end up with the strictest
+	// combination of both.
-	 * combination of both.
+	// The merging is however performed at the *end* of the original section!
-	 * The merging is however performed at the *end* of the original section!
-	 */
 	if (org != (uint32_t)-1) {
 		uint16_t curOrg = org - sect->size;
 
-		/* If both are fixed, they must be the same */
+		// If both are fixed, they must be the same
 		if (sect->org != (uint32_t)-1 && sect->org != curOrg)
 			fail("Section already declared as fixed at incompatible address $%04"
 			     PRIx32 " (cur addr = %04" PRIx32 ")\n",
@@ -197,7 +193,7 @@ static unsigned int mergeFragments(struct Section *sect, enum SectionType type,
 			fail("Section already declared as aligned to %u bytes (offset %"
 			     PRIu16 ")\n", 1U << sect->align, sect->alignOfs);
 		else
-			/* Otherwise, just override */
+			// Otherwise, just override
 			sect->org = curOrg;
 
 	} else if (alignment != 0) {
@@ -206,12 +202,12 @@ static unsigned int mergeFragments(struct Section *sect, enum SectionType type,
 		if (curOfs < 0)
 			curOfs += 1U << alignment;
 
-		/* Make sure any fixed address given is compatible */
+		// Make sure any fixed address given is compatible
 		if (sect->org != (uint32_t)-1) {
 			if ((sect->org - curOfs) & mask(alignment))
 				fail("Section already declared as fixed at incompatible address $%04"
 				     PRIx32 "\n", sect->org);
-		/* Check if alignment offsets are compatible */
+		// Check if alignment offsets are compatible
 		} else if ((curOfs & mask(sect->align)) != (sect->alignOfs & mask(alignment))) {
 			fail("Section already declared with incompatible %u"
 			     "-byte alignment (offset %" PRIu16 ")\n",
@@ -232,7 +228,7 @@ static void mergeSections(struct Section *sect, enum SectionType type, uint32_t
 	unsigned int nbSectErrors = 0;
 
 	if (type != sect->type)
-		fail("Section already exists but with type %s\n", typeNames[sect->type]);
+		fail("Section already exists but with type %s\n", sectionTypeInfo[sect->type].name);
 
 	if (sect->modifier != mod) {
 		fail("Section already declared as %s section\n", sectionModNames[sect->modifier]);
@@ -245,10 +241,10 @@ static void mergeSections(struct Section *sect, enum SectionType type, uint32_t
 
 			// Common checks
 
-			/* If the section's bank is unspecified, override it */
+			// If the section's bank is unspecified, override it
 			if (sect->bank == (uint32_t)-1)
 				sect->bank = bank;
-			/* If both specify a bank, it must be the same one */
+			// If both specify a bank, it must be the same one
 			else if (bank != (uint32_t)-1 && sect->bank != bank)
 				fail("Section already declared with different bank %" PRIu32 "\n",
 				     sect->bank);
@@ -269,9 +265,7 @@ static void mergeSections(struct Section *sect, enum SectionType type, uint32_t
 
 #undef fail
 
-/*
+// Create a new section, not yet in the list.
- * Create a new section, not yet in the list.
- */
 static struct Section *createSection(char const *name, enum SectionType type,
 				     uint32_t org, uint32_t bank, uint8_t alignment,
 				     uint16_t alignOffset, enum SectionModifier mod)
@@ -297,9 +291,9 @@ static struct Section *createSection(char const *name, enum SectionType type,
 	sect->next = NULL;
 	sect->patches = NULL;
 
-	/* It is only needed to allocate memory for ROM sections. */
+	// It is only needed to allocate memory for ROM sections.
 	if (sect_HasData(type)) {
-		sect->data = malloc(maxsize[type]);
+		sect->data = malloc(sectionTypeInfo[type].size);
 		if (sect->data == NULL)
 			fatalerror("Not enough memory for section: %s\n", strerror(errno));
 	} else {
@@ -309,9 +303,7 @@ static struct Section *createSection(char const *name, enum SectionType type,
 	return sect;
 }
 
-/*
+// Find a section by name and type. If it doesn't exist, create it.
- * Find a section by name and type. If it doesn't exist, create it.
- */
 static struct Section *getSection(char const *name, enum SectionType type, uint32_t org,
 				  struct SectionSpec const *attrs, enum SectionModifier mod)
 {
@@ -325,14 +317,13 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 		if (type != SECTTYPE_ROMX && type != SECTTYPE_VRAM
 		 && type != SECTTYPE_SRAM && type != SECTTYPE_WRAMX)
 			error("BANK only allowed for ROMX, WRAMX, SRAM, or VRAM sections\n");
-		else if (bank < bankranges[type][0]
+		else if (bank < sectionTypeInfo[type].firstBank || bank > sectionTypeInfo[type].lastBank)
-		      || bank > bankranges[type][1])
 			error("%s bank value $%04" PRIx32 " out of range ($%04" PRIx32 " to $%04"
-				PRIx32 ")\n", typeNames[type], bank,
+				PRIx32 ")\n", sectionTypeInfo[type].name, bank,
-				bankranges[type][0], bankranges[type][1]);
+				sectionTypeInfo[type].firstBank, sectionTypeInfo[type].lastBank);
 	} else if (nbbanks(type) == 1) {
 		// If the section type only has a single bank, implicitly force it
-		bank = bankranges[type][0];
+		bank = sectionTypeInfo[type].firstBank;
 	}
 
 	if (alignOffset >= 1 << alignment) {
@@ -342,10 +333,10 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 	}
 
 	if (org != (uint32_t)-1) {
-		if (org < startaddr[type] || org > endaddr(type))
+		if (org < sectionTypeInfo[type].startAddr || org > endaddr(type))
 			error("Section \"%s\"'s fixed address %#" PRIx32
 				" is outside of range [%#" PRIx16 "; %#" PRIx16 "]\n",
-				name, org, startaddr[type], endaddr(type));
+				name, org, sectionTypeInfo[type].startAddr, endaddr(type));
 	}
 
 	if (alignment != 0) {
@@ -353,18 +344,18 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 			error("Alignment must be between 0 and 16, not %u\n", alignment);
 			alignment = 16;
 		}
-		/* It doesn't make sense to have both alignment and org set */
+		// It doesn't make sense to have both alignment and org set
 		uint32_t mask = mask(alignment);
 
 		if (org != (uint32_t)-1) {
 			if ((org - alignOffset) & mask)
 				error("Section \"%s\"'s fixed address doesn't match its alignment\n",
 					name);
-			alignment = 0; /* Ignore it if it's satisfied */
+			alignment = 0; // Ignore it if it's satisfied
-		} else if (startaddr[type] & mask) {
+		} else if (sectionTypeInfo[type].startAddr & mask) {
 			error("Section \"%s\"'s alignment cannot be attained in %s\n",
-				name, typeNames[type]);
+				name, sectionTypeInfo[type].name);
-			alignment = 0; /* Ignore it if it's unattainable */
+			alignment = 0; // Ignore it if it's unattainable
 			org = 0;
 		} else if (alignment == 16) {
 			// Treat an alignment of 16 as being fixed at address 0
@@ -390,9 +381,7 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 	return sect;
 }
 
-/*
+// Set the current section
- * Set the current section
- */
 static void changeSection(void)
 {
 	if (unionStack)
@@ -401,9 +390,7 @@ static void changeSection(void)
 	sym_SetCurrentSymbolScope(NULL);
 }
 
-/*
+// Set the current section by name and type
- * Set the current section by name and type
- */
 void sect_NewSection(char const *name, uint32_t type, uint32_t org,
 		     struct SectionSpec const *attribs, enum SectionModifier mod)
 {
@@ -423,9 +410,7 @@ void sect_NewSection(char const *name, uint32_t type, uint32_t org,
 	currentSection = sect;
 }
 
-/*
+// Set the current section by name and type
- * Set the current section by name and type
- */
 void sect_SetLoadSection(char const *name, uint32_t type, uint32_t org,
 			 struct SectionSpec const *attribs, enum SectionModifier mod)
 {
@@ -478,9 +463,7 @@ struct Section *sect_GetSymbolSection(void)
 	return currentLoadSection ? currentLoadSection : currentSection;
 }
 
-/*
+// The offset into the section above
- * The offset into the section above
- */
 uint32_t sect_GetSymbolOffset(void)
 {
 	return curOffset;
@@ -615,9 +598,7 @@ void sect_CheckUnionClosed(void)
 		error("Unterminated UNION construct!\n");
 }
 
-/*
+// Output an absolute byte
- * Output an absolute byte
- */
 void sect_AbsByte(uint8_t b)
 {
 	if (!checkcodesection())
@@ -661,9 +642,7 @@ void sect_AbsLongGroup(uint8_t const *s, size_t length)
 		writelong(*s++);
 }
 
-/*
+// Skip this many bytes
- * Skip this many bytes
- */
 void sect_Skip(uint32_t skip, bool ds)
 {
 	if (!checksection())
@@ -683,9 +662,7 @@ void sect_Skip(uint32_t skip, bool ds)
 	}
 }
 
-/*
+// Output a NULL terminated string (excluding the NULL-character)
- * Output a NULL terminated string (excluding the NULL-character)
- */
 void sect_String(char const *s)
 {
 	if (!checkcodesection())
@@ -697,10 +674,8 @@ void sect_String(char const *s)
 		writebyte(*s++);
 }
 
-/*
+// Output a relocatable byte. Checking will be done to see if it
- * Output a relocatable byte. Checking will be done to see if it
+// is an absolute value in disguise.
- * is an absolute value in disguise.
- */
 void sect_RelByte(struct Expression *expr, uint32_t pcShift)
 {
 	if (!checkcodesection())
@@ -717,10 +692,8 @@ void sect_RelByte(struct Expression *expr, uint32_t pcShift)
 	rpn_Free(expr);
 }
 
-/*
+// Output several copies of a relocatable byte. Checking will be done to see if
- * Output several copies of a relocatable byte. Checking will be done to see if
+// it is an absolute value in disguise.
- * it is an absolute value in disguise.
- */
 void sect_RelBytes(uint32_t n, struct Expression *exprs, size_t size)
 {
 	if (!checkcodesection())
@@ -743,10 +716,8 @@ void sect_RelBytes(uint32_t n, struct Expression *exprs, size_t size)
 		rpn_Free(&exprs[i]);
 }
 
-/*
+// Output a relocatable word. Checking will be done to see if
- * Output a relocatable word. Checking will be done to see if
+// it's an absolute value in disguise.
- * it's an absolute value in disguise.
- */
 void sect_RelWord(struct Expression *expr, uint32_t pcShift)
 {
 	if (!checkcodesection())
@@ -763,10 +734,8 @@ void sect_RelWord(struct Expression *expr, uint32_t pcShift)
 	rpn_Free(expr);
 }
 
-/*
+// Output a relocatable longword. Checking will be done to see if
- * Output a relocatable longword. Checking will be done to see if
+// is an absolute value in disguise.
- * is an absolute value in disguise.
- */
 void sect_RelLong(struct Expression *expr, uint32_t pcShift)
 {
 	if (!checkcodesection())
@@ -783,10 +752,8 @@ void sect_RelLong(struct Expression *expr, uint32_t pcShift)
 	rpn_Free(expr);
 }
 
-/*
+// Output a PC-relative relocatable byte. Checking will be done to see if it
- * Output a PC-relative relocatable byte. Checking will be done to see if it
+// is an absolute value in disguise.
- * is an absolute value in disguise.
- */
 void sect_PCRelByte(struct Expression *expr, uint32_t pcShift)
 {
 	if (!checkcodesection())
@@ -800,12 +767,12 @@ void sect_PCRelByte(struct Expression *expr, uint32_t pcShift)
 		writebyte(0);
 	} else {
 		struct Symbol const *sym = rpn_SymbolOf(expr);
-		/* The offset wraps (jump from ROM to HRAM, for example) */
+		// The offset wraps (jump from ROM to HRAM, for example)
 		int16_t offset;
 
-		/* Offset is relative to the byte *after* the operand */
+		// Offset is relative to the byte *after* the operand
 		if (sym == pc)
-			offset = -2; /* PC as operand to `jr` is lower than reference PC by 2 */
+			offset = -2; // PC as operand to `jr` is lower than reference PC by 2
 		else
 			offset = sym_GetValue(sym) - (sym_GetValue(pc) + 1);
 
@@ -820,9 +787,7 @@ void sect_PCRelByte(struct Expression *expr, uint32_t pcShift)
 	rpn_Free(expr);
 }
 
-/*
+// Output a binary file
- * Output a binary file
- */
 void sect_BinaryFile(char const *s, int32_t startPos)
 {
 	if (startPos < 0) {
@@ -869,7 +834,7 @@ void sect_BinaryFile(char const *s, int32_t startPos)
 		if (errno != ESPIPE)
 			error("Error determining size of INCBIN file '%s': %s\n",
 			      s, strerror(errno));
-		/* The file isn't seekable, so we'll just skip bytes */
+		// The file isn't seekable, so we'll just skip bytes
 		while (startPos--)
 			(void)fgetc(f);
 	}
@@ -901,7 +866,7 @@ void sect_BinaryFileSlice(char const *s, int32_t start_pos, int32_t length)
 
 	if (!checkcodesection())
 		return;
-	if (length == 0) /* Don't even bother with 0-byte slices */
+	if (length == 0) // Don't even bother with 0-byte slices
 		return;
 	if (!reserveSpace(length))
 		return;
@@ -946,7 +911,7 @@ void sect_BinaryFileSlice(char const *s, int32_t start_pos, int32_t length)
 		if (errno != ESPIPE)
 			error("Error determining size of INCBIN file '%s': %s\n",
 				s, strerror(errno));
-		/* The file isn't seekable, so we'll just skip bytes */
+		// The file isn't seekable, so we'll just skip bytes
 		while (start_pos--)
 			(void)fgetc(f);
 	}
@@ -968,9 +933,7 @@ cleanup:
 	fclose(f);
 }
 
-/*
+// Section stack routines
- * Section stack routines
- */
 void sect_PushSection(void)
 {
 	struct SectionStackEntry *entry = malloc(sizeof(*entry));

src/asm/symbol.c

@@ -6,9 +6,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*
+// Symboltable and macroargs stuff
- * Symboltable and macroargs stuff
- */
 
 #include <assert.h>
 #include <errno.h>
@@ -36,8 +34,9 @@
 
 HashMap symbols;
 
-static char const *labelScope; /* Current section's label scope */
+static const char *labelScope; // Current section's label scope
 static struct Symbol *PCSymbol;
+static struct Symbol *_NARGSymbol;
 static char savedTIME[256];
 static char savedDATE[256];
 static char savedTIMESTAMP_ISO8601_LOCAL[256];
@@ -80,41 +79,42 @@ static int32_t Callback_NARG(void)
 
 static int32_t Callback__LINE__(void)
 {
+	warning(WARNING_OBSOLETE, "`__LINE__` is deprecated\n");
+
 	return lexer_GetLineNo();
 }
 
 static char const *Callback__FILE__(void)
 {
-	/*
+	warning(WARNING_OBSOLETE, "`__FILE__` is deprecated\n");
-	 * FIXME: this is dangerous, and here's why this is CURRENTLY okay. It's still bad, fix it.
+
-	 * There are only two call sites for this; one copies the contents directly, the other is
+	// There are only two call sites for this; one copies the contents directly, the other is
-	 * EQUS expansions, which cannot straddle file boundaries. So this should be fine.
+	// EQUS expansions, which cannot straddle file boundaries. So this should be fine.
-	 */
 	static char *buf = NULL;
 	static size_t bufsize = 0;
 	char const *fileName = fstk_GetFileName();
 	size_t j = 1;
 
 	assert(fileName[0]);
-	/* The assertion above ensures the loop runs at least once */
+	// The assertion above ensures the loop runs at least once
 	for (size_t i = 0; fileName[i]; i++, j++) {
-		/* Account for the extra backslash inserted below */
+		// Account for the extra backslash inserted below
 		if (fileName[i] == '"')
 			j++;
-		/* Ensure there will be enough room; DO NOT PRINT ANYTHING ABOVE THIS!! */
+		// Ensure there will be enough room; DO NOT PRINT ANYTHING ABOVE THIS!
-		if (j + 2 >= bufsize) { /* Always keep room for 2 tail chars */
+		if (j + 2 >= bufsize) { // Always keep room for 2 tail chars
 			bufsize = bufsize ? bufsize * 2 : 64;
 			buf = realloc(buf, bufsize);
 			if (!buf)
 				fatalerror("Failed to grow buffer for file name: %s\n",
 					   strerror(errno));
 		}
-		/* Escape quotes, since we're returning a string */
+		// Escape quotes, since we're returning a string
 		if (fileName[i] == '"')
 			buf[j - 1] = '\\';
 		buf[j] = fileName[i];
 	}
-	/* Write everything after the loop, to ensure the buffer has been allocated */
+	// Write everything after the loop, to ensure the buffer has been allocated
 	buf[0] = '"';
 	buf[j++] = '"';
 	buf[j] = '\0';
@@ -128,16 +128,14 @@ static int32_t CallbackPC(void)
 	return section ? section->org + sect_GetSymbolOffset() : 0;
 }
 
-/*
+// Get the value field of a symbol
- * Get the value field of a symbol
- */
 int32_t sym_GetValue(struct Symbol const *sym)
 {
 	if (sym_IsNumeric(sym) && sym->hasCallback)
 		return sym->numCallback();
 
 	if (sym->type == SYM_LABEL)
-		/* TODO: do not use section's org directly */
+		// TODO: do not use section's org directly
 		return sym->value + sym_GetSection(sym)->org;
 
 	return sym->value;
@@ -153,32 +151,26 @@ static void dumpFilename(struct Symbol const *sym)
 		fputs("<builtin>", stderr);
 }
 
-/*
+// Set a symbol's definition filename and line
- * Set a symbol's definition filename and line
- */
 static void setSymbolFilename(struct Symbol *sym)
 {
 	sym->src = fstk_GetFileStack();
 	sym->fileLine = sym->src ? lexer_GetLineNo() : 0; // This is (NULL, 1) for built-ins
 }
 
-/*
+// Update a symbol's definition filename and line
- * Update a symbol's definition filename and line
- */
 static void updateSymbolFilename(struct Symbol *sym)
 {
 	struct FileStackNode *oldSrc = sym->src;
 
 	setSymbolFilename(sym);
-	/* If the old node was referenced, ensure the new one is */
+	// If the old node was referenced, ensure the new one is
 	if (oldSrc && oldSrc->referenced && oldSrc->ID != (uint32_t)-1)
 		out_RegisterNode(sym->src);
-	/* TODO: unref the old node, and use `out_ReplaceNode` instead of deleting it */
+	// TODO: unref the old node, and use `out_ReplaceNode` instead of deleting it
 }
 
-/*
+// Create a new symbol by name
- * Create a new symbol by name
- */
 static struct Symbol *createsymbol(char const *symName)
 {
 	struct Symbol *sym = malloc(sizeof(*sym));
@@ -201,10 +193,8 @@ static struct Symbol *createsymbol(char const *symName)
 	return sym;
 }
 
-/*
+// Creates the full name of a local symbol in a given scope, by prepending
- * Creates the full name of a local symbol in a given scope, by prepending
+// the name with the parent symbol's name.
- * the name with the parent symbol's name.
- */
 static void fullSymbolName(char *output, size_t outputSize,
 			   char const *localName, char const *scopeName)
 {
@@ -250,8 +240,8 @@ struct Symbol *sym_FindScopedSymbol(char const *symName)
 		if (strchr(localName + 1, '.'))
 			fatalerror("'%s' is a nonsensical reference to a nested local symbol\n",
 				   symName);
-		/* If auto-scoped local label, expand the name */
+		// If auto-scoped local label, expand the name
-		if (localName == symName) { /* Meaning, the name begins with the dot */
+		if (localName == symName) { // Meaning, the name begins with the dot
 			char fullName[MAXSYMLEN + 1];
 
 			fullSymbolName(fullName, sizeof(fullName), symName, labelScope);
@@ -261,6 +251,21 @@ struct Symbol *sym_FindScopedSymbol(char const *symName)
 	return sym_FindExactSymbol(symName);
 }
 
+struct Symbol *sym_FindScopedValidSymbol(char const *symName)
+{
+	struct Symbol *sym = sym_FindScopedSymbol(symName);
+
+	// `@` has no value outside a section
+	if (sym == PCSymbol && !sect_GetSymbolSection()) {
+		return NULL;
+	}
+	// `_NARG` has no value outside a macro
+	if (sym == _NARGSymbol && !macro_GetCurrentArgs()) {
+		return NULL;
+	}
+	return sym;
+}
+
 struct Symbol const *sym_GetPC(void)
 {
 	return PCSymbol;
@@ -271,12 +276,10 @@ static bool isReferenced(struct Symbol const *sym)
 	return sym->ID != (uint32_t)-1;
 }
 
-/*
+// Purge a symbol
- * Purge a symbol
- */
 void sym_Purge(char const *symName)
 {
-	struct Symbol *sym = sym_FindScopedSymbol(symName);
+	struct Symbol *sym = sym_FindScopedValidSymbol(symName);
 
 	if (!sym) {
 		error("'%s' not defined\n", symName);
@@ -285,16 +288,14 @@ void sym_Purge(char const *symName)
 	} else if (isReferenced(sym)) {
 		error("Symbol \"%s\" is referenced and thus cannot be purged\n", symName);
 	} else {
-		/* Do not keep a reference to the label's name after purging it */
+		// Do not keep a reference to the label's name after purging it
 		if (sym->name == labelScope)
 			sym_SetCurrentSymbolScope(NULL);
 
-		/*
+		// FIXME: this leaks sym->macro for SYM_EQUS and SYM_MACRO, but this can't
-		 * FIXME: this leaks sym->macro for SYM_EQUS and SYM_MACRO, but this can't
+		// free(sym->macro) because the expansion may be purging itself.
-		 * free(sym->macro) because the expansion may be purging itself.
-		 */
 		hash_RemoveElement(symbols, sym->name);
-		/* TODO: ideally, also unref the file stack nodes */
+		// TODO: ideally, also unref the file stack nodes
 		free(sym);
 	}
 }
@@ -312,9 +313,7 @@ uint32_t sym_GetPCValue(void)
 	return 0;
 }
 
-/*
+// Return a constant symbol's value, assuming it's defined
- * Return a constant symbol's value, assuming it's defined
- */
 uint32_t sym_GetConstantSymValue(struct Symbol const *sym)
 {
 	if (sym == PCSymbol)
@@ -327,9 +326,7 @@ uint32_t sym_GetConstantSymValue(struct Symbol const *sym)
 	return 0;
 }
 
-/*
+// Return a constant symbol's value
- * Return a constant symbol's value
- */
 uint32_t sym_GetConstantValue(char const *symName)
 {
 	struct Symbol const *sym = sym_FindScopedSymbol(symName);
@@ -381,9 +378,7 @@ static struct Symbol *createNonrelocSymbol(char const *symName, bool numeric)
 	return sym;
 }
 
-/*
+// Add an equated symbol
- * Add an equated symbol
- */
 struct Symbol *sym_AddEqu(char const *symName, int32_t value)
 {
 	struct Symbol *sym = createNonrelocSymbol(symName, true);
@@ -465,18 +460,14 @@ struct Symbol *sym_RedefString(char const *symName, char const *value)
 	}
 
 	updateSymbolFilename(sym);
-	/*
+	// FIXME: this leaks the previous sym->macro value, but this can't
-	 * FIXME: this leaks the previous sym->macro value, but this can't
+	// free(sym->macro) because the expansion may be redefining itself.
-	 * free(sym->macro) because the expansion may be redefining itself.
-	 */
 	assignStringSymbol(sym, value);
 
 	return sym;
 }
 
-/*
+// Alter a mutable symbol's value
- * Alter a mutable symbol's value
- */
 struct Symbol *sym_AddVar(char const *symName, int32_t value)
 {
 	struct Symbol *sym = sym_FindExactSymbol(symName);
@@ -506,7 +497,7 @@ struct Symbol *sym_AddVar(char const *symName, int32_t value)
  */
 static struct Symbol *addLabel(char const *symName)
 {
-	assert(symName[0] != '.'); /* The symbol name must have been expanded prior */
+	assert(symName[0] != '.'); // The symbol name must have been expanded prior
 	struct Symbol *sym = sym_FindExactSymbol(symName);
 
 	if (!sym) {
@@ -519,7 +510,7 @@ static struct Symbol *addLabel(char const *symName)
 	} else {
 		updateSymbolFilename(sym);
 	}
-	/* If the symbol already exists as a ref, just "take over" it */
+	// If the symbol already exists as a ref, just "take over" it
 	sym->type = SYM_LABEL;
 	sym->value = sect_GetSymbolOffset();
 	if (exportall)
@@ -531,43 +522,41 @@ static struct Symbol *addLabel(char const *symName)
 	return sym;
 }
 
-/*
+// Add a local (`.name` or `Parent.name`) relocatable symbol
- * Add a local (`.name` or `Parent.name`) relocatable symbol
- */
 struct Symbol *sym_AddLocalLabel(char const *symName)
 {
 	if (!labelScope) {
 		error("Local label '%s' in main scope\n", symName);
 		return NULL;
 	}
-	assert(!strchr(labelScope, '.')); /* Assuming no dots in `labelScope` */
+	assert(!strchr(labelScope, '.')); // Assuming no dots in `labelScope`
 
 	char fullName[MAXSYMLEN + 1];
 	char const *localName = strchr(symName, '.');
 
-	assert(localName); /* There should be at least one dot in `symName` */
+	assert(localName); // There should be at least one dot in `symName`
-	/* Check for something after the dot in `localName` */
+	// Check for something after the dot in `localName`
 	if (localName[1] == '\0') {
 		fatalerror("'%s' is a nonsensical reference to an empty local label\n",
 			   symName);
 	}
-	/* Check for more than one dot in `localName` */
+	// Check for more than one dot in `localName`
 	if (strchr(localName + 1, '.'))
 		fatalerror("'%s' is a nonsensical reference to a nested local label\n",
 			   symName);
 
 	if (localName == symName) {
-		/* Expand `symName` to the full `labelScope.symName` name */
+		// Expand `symName` to the full `labelScope.symName` name
 		fullSymbolName(fullName, sizeof(fullName), symName, labelScope);
 		symName = fullName;
 	} else {
 		size_t i = 0;
 
-		/* Find where `labelScope` and `symName` first differ */
+		// Find where `labelScope` and `symName` first differ
 		while (labelScope[i] && symName[i] == labelScope[i])
 			i++;
 
-		/* Check that `symName` starts with `labelScope` and then a '.' */
+		// Check that `symName` starts with `labelScope` and then a '.'
 		if (labelScope[i] != '\0' || symName[i] != '.') {
 			size_t parentLen = localName - symName;
 
@@ -579,14 +568,12 @@ struct Symbol *sym_AddLocalLabel(char const *symName)
 	return addLabel(symName);
 }
 
-/*
+// Add a relocatable symbol
- * Add a relocatable symbol
- */
 struct Symbol *sym_AddLabel(char const *symName)
 {
 	struct Symbol *sym = addLabel(symName);
 
-	/* Set the symbol as the new scope */
+	// Set the symbol as the new scope
 	if (sym)
 		sym_SetCurrentSymbolScope(sym->name);
 	return sym;
@@ -594,9 +581,7 @@ struct Symbol *sym_AddLabel(char const *symName)
 
 static uint32_t anonLabelID;
 
-/*
+// Add an anonymous label
- * Add an anonymous label
- */
 struct Symbol *sym_AddAnonLabel(void)
 {
 	if (anonLabelID == UINT32_MAX) {
@@ -605,14 +590,12 @@ struct Symbol *sym_AddAnonLabel(void)
 	}
 	char name[MAXSYMLEN + 1];
 
-	sym_WriteAnonLabelName(name, 0, true); // The direction is important!!
+	sym_WriteAnonLabelName(name, 0, true); // The direction is important!
 	anonLabelID++;
 	return addLabel(name);
 }
 
-/*
+// Write an anonymous label's name to a buffer
- * Write an anonymous label's name to a buffer
- */
 void sym_WriteAnonLabelName(char buf[MIN_NB_ELMS(MAXSYMLEN + 1)], uint32_t ofs, bool neg)
 {
 	uint32_t id = 0;
@@ -636,9 +619,7 @@ void sym_WriteAnonLabelName(char buf[MIN_NB_ELMS(MAXSYMLEN + 1)], uint32_t ofs,
 	sprintf(buf, "!%u", id);
 }
 
-/*
+// Export a symbol
- * Export a symbol
- */
 void sym_Export(char const *symName)
 {
 	if (symName[0] == '!') {
@@ -648,15 +629,13 @@ void sym_Export(char const *symName)
 
 	struct Symbol *sym = sym_FindScopedSymbol(symName);
 
-	/* If the symbol doesn't exist, create a ref that can be purged */
+	// If the symbol doesn't exist, create a ref that can be purged
 	if (!sym)
 		sym = sym_Ref(symName);
 	sym->isExported = true;
 }
 
-/*
+// Add a macro definition
- * Add a macro definition
- */
 struct Symbol *sym_AddMacro(char const *symName, int32_t defLineNo, char *body, size_t size)
 {
 	struct Symbol *sym = createNonrelocSymbol(symName, false);
@@ -667,20 +646,16 @@ struct Symbol *sym_AddMacro(char const *symName, int32_t defLineNo, char *body,
 	sym->type = SYM_MACRO;
 	sym->macroSize = size;
 	sym->macro = body;
-	setSymbolFilename(sym); /* TODO: is this really necessary? */
+	setSymbolFilename(sym); // TODO: is this really necessary?
-	/*
+	// The symbol is created at the line after the `endm`,
-	 * The symbol is created at the line after the `endm`,
+	// override this with the actual definition line
-	 * override this with the actual definition line
-	 */
 	sym->fileLine = defLineNo;
 
 	return sym;
 }
 
-/*
+// Flag that a symbol is referenced in an RPN expression
- * Flag that a symbol is referenced in an RPN expression
+// and create it if it doesn't exist yet
- * and create it if it doesn't exist yet
- */
 struct Symbol *sym_Ref(char const *symName)
 {
 	struct Symbol *sym = sym_FindScopedSymbol(symName);
@@ -702,9 +677,7 @@ struct Symbol *sym_Ref(char const *symName)
 	return sym;
 }
 
-/*
+// Set whether to export all relocatable symbols by default
- * Set whether to export all relocatable symbols by default
- */
 void sym_SetExportAll(bool set)
 {
 	exportall = set;
@@ -721,14 +694,14 @@ static struct Symbol *createBuiltinSymbol(char const *symName)
 	return sym;
 }
 
-/*
+// Initialize the symboltable
- * Initialize the symboltable
- */
 void sym_Init(time_t now)
 {
 	PCSymbol = createBuiltinSymbol("@");
-	struct Symbol *_NARGSymbol = createBuiltinSymbol("_NARG");
+	_NARGSymbol = createBuiltinSymbol("_NARG");
+	// __LINE__ is deprecated
 	struct Symbol *__LINE__Symbol = createBuiltinSymbol("__LINE__");
+	// __FILE__ is deprecated
 	struct Symbol *__FILE__Symbol = createBuiltinSymbol("__FILE__");
 
 	PCSymbol->type = SYM_LABEL;
@@ -743,8 +716,13 @@ void sym_Init(time_t now)
 
 	sym_AddVar("_RS", 0)->isBuiltin = true;
 
-#define addNumber(name, val) sym_AddEqu(name, val)->isBuiltin = true
+#define addSym(fn, name, val) do { \
-#define addString(name, val) sym_AddString(name, val)->isBuiltin = true
+	struct Symbol *sym = fn(name, val); \
+	assert(sym); \
+	sym->isBuiltin = true; \
+} while (0)
+#define addNumber(name, val) addSym(sym_AddEqu, name, val)
+#define addString(name, val) addSym(sym_AddString, name, val)
 
 	addString("__RGBDS_VERSION__", get_package_version_string());
 	addNumber("__RGBDS_MAJOR__", PACKAGE_VERSION_MAJOR);
@@ -756,11 +734,10 @@ void sym_Init(time_t now)
 
 	if (now == (time_t)-1) {
 		warn("Couldn't determine current time");
-		/* Fall back by pretending we are at the Epoch */
+		// Fall back by pretending we are at the Epoch
 		now = 0;
 	}
 
-	const struct tm *time_utc = gmtime(&now);
 	const struct tm *time_local = localtime(&now);
 
 	strftime(savedTIME, sizeof(savedTIME), "\"%H:%M:%S\"", time_local);
@@ -769,6 +746,8 @@ void sym_Init(time_t now)
 		 sizeof(savedTIMESTAMP_ISO8601_LOCAL), "\"%Y-%m-%dT%H:%M:%S%z\"",
 		 time_local);
 
+	const struct tm *time_utc = gmtime(&now);
+
 	strftime(savedTIMESTAMP_ISO8601_UTC,
 		 sizeof(savedTIMESTAMP_ISO8601_UTC), "\"%Y-%m-%dT%H:%M:%SZ\"",
 		 time_utc);
@@ -787,16 +766,7 @@ void sym_Init(time_t now)
 
 #undef addNumber
 #undef addString
+#undef addSym
 
 	sym_SetCurrentSymbolScope(NULL);
-	anonLabelID = 0;
+	anonLabelID = 0;}
-
-	/* _PI is deprecated */
-	struct Symbol *_PISymbol = createBuiltinSymbol("_PI");
-
-	_PISymbol->type = SYM_EQU;
-	_PISymbol->src = NULL;
-	_PISymbol->fileLine = 0;
-	_PISymbol->hasCallback = true;
-	_PISymbol->numCallback = fix_Callback_PI;
-}

src/asm/util.c

@@ -44,7 +44,7 @@ char const *printChar(int c)
 		buf[2] = 't';
 		break;
 
-	default: /* Print as hex */
+	default: // Print as hex
 		buf[0] = '0';
 		buf[1] = 'x';
 		snprintf(&buf[2], 3, "%02hhX", (uint8_t)c); // includes the '\0'

src/asm/warning.c

@@ -44,23 +44,25 @@ static const enum WarningState defaultWarnings[ARRAY_SIZE(warningStates)] = {
 	[WARNING_NUMERIC_STRING_2]	= WARNING_DISABLED,
 	[WARNING_TRUNCATION_1]		= WARNING_ENABLED,
 	[WARNING_TRUNCATION_2]		= WARNING_DISABLED,
+	[WARNING_UNMAPPED_CHAR_1]	= WARNING_ENABLED,
+	[WARNING_UNMAPPED_CHAR_2]	= WARNING_DISABLED,
 };
 
 enum WarningState warningStates[ARRAY_SIZE(warningStates)];
 
-bool warningsAreErrors; /* Set if `-Werror` was specified */
+bool warningsAreErrors; // Set if `-Werror` was specified
 
 static enum WarningState warningState(enum WarningID id)
 {
-	/* Check if warnings are globally disabled */
+	// Check if warnings are globally disabled
 	if (!warnings)
 		return WARNING_DISABLED;
 
-	/* Get the actual state */
+	// Get the actual state
 	enum WarningState state = warningStates[id];
 
 	if (state == WARNING_DEFAULT)
-		/* The state isn't set, grab its default state */
+		// The state isn't set, grab its default state
 		state = defaultWarnings[id];
 
 	if (warningsAreErrors && state == WARNING_ENABLED)
@@ -92,11 +94,13 @@ static const char * const warningFlags[NB_WARNINGS] = {
 	"numeric-string",
 	"truncation",
 	"truncation",
+	"unmapped-char",
+	"unmapped-char",
 
-	/* Meta warnings */
+	// Meta warnings
 	"all",
 	"extra",
-	"everything", /* Especially useful for testing */
+	"everything", // Especially useful for testing
 };
 
 static const struct {
@@ -106,6 +110,7 @@ static const struct {
 } paramWarnings[] = {
 	{ "numeric-string", 2, 1 },
 	{ "truncation", 2, 2 },
+	{ "unmapped-char", 2, 1 },
 };
 
 static bool tryProcessParamWarning(char const *flag, uint8_t param, enum WarningState state)
@@ -149,7 +154,7 @@ enum MetaWarningCommand {
 	META_WARNING_DONE = NB_WARNINGS
 };
 
-/* Warnings that probably indicate an error */
+// Warnings that probably indicate an error
 static uint8_t const _wallCommands[] = {
 	WARNING_BACKWARDS_FOR,
 	WARNING_BUILTIN_ARG,
@@ -161,10 +166,11 @@ static uint8_t const _wallCommands[] = {
 	WARNING_NESTED_COMMENT,
 	WARNING_OBSOLETE,
 	WARNING_NUMERIC_STRING_1,
+	WARNING_UNMAPPED_CHAR_1,
 	META_WARNING_DONE
 };
 
-/* Warnings that are less likely to indicate an error */
+// Warnings that are less likely to indicate an error
 static uint8_t const _wextraCommands[] = {
 	WARNING_EMPTY_MACRO_ARG,
 	WARNING_MACRO_SHIFT,
@@ -173,10 +179,12 @@ static uint8_t const _wextraCommands[] = {
 	WARNING_NUMERIC_STRING_2,
 	WARNING_TRUNCATION_1,
 	WARNING_TRUNCATION_2,
+	WARNING_UNMAPPED_CHAR_1,
+	WARNING_UNMAPPED_CHAR_2,
 	META_WARNING_DONE
 };
 
-/* Literally everything. Notably useful for testing */
+// Literally everything. Notably useful for testing
 static uint8_t const _weverythingCommands[] = {
 	WARNING_BACKWARDS_FOR,
 	WARNING_BUILTIN_ARG,
@@ -195,7 +203,9 @@ static uint8_t const _weverythingCommands[] = {
 	WARNING_NUMERIC_STRING_2,
 	WARNING_TRUNCATION_1,
 	WARNING_TRUNCATION_2,
-	/* WARNING_USER, */
+	WARNING_UNMAPPED_CHAR_1,
+	WARNING_UNMAPPED_CHAR_2,
+	// WARNING_USER,
 	META_WARNING_DONE
 };
 
@@ -209,18 +219,18 @@ void processWarningFlag(char *flag)
 {
 	static bool setError = false;
 
-	/* First, try to match against a "meta" warning */
+	// First, try to match against a "meta" warning
 	for (enum WarningID id = META_WARNINGS_START; id < NB_WARNINGS; id++) {
-		/* TODO: improve the matching performance? */
+		// TODO: improve the matching performance?
 		if (!strcmp(flag, warningFlags[id])) {
-			/* We got a match! */
+			// We got a match!
 			if (setError)
 				errx("Cannot make meta warning \"%s\" into an error",
 				     flag);
 
 			for (uint8_t const *ptr = metaWarningCommands[id - META_WARNINGS_START];
 			     *ptr != META_WARNING_DONE; ptr++) {
-				/* Warning flag, set without override */
+				// Warning flag, set without override
 				if (warningStates[*ptr] == WARNING_DEFAULT)
 					warningStates[*ptr] = WARNING_ENABLED;
 			}
@@ -229,31 +239,31 @@ void processWarningFlag(char *flag)
 		}
 	}
 
-	/* If it's not a meta warning, specially check against `-Werror` */
+	// If it's not a meta warning, specially check against `-Werror`
 	if (!strncmp(flag, "error", strlen("error"))) {
 		char *errorFlag = flag + strlen("error");
 
 		switch (*errorFlag) {
 		case '\0':
-			/* `-Werror` */
+			// `-Werror`
 			warningsAreErrors = true;
 			return;
 
 		case '=':
-			/* `-Werror=XXX` */
+			// `-Werror=XXX`
 			setError = true;
-			processWarningFlag(errorFlag + 1); /* Skip the `=` */
+			processWarningFlag(errorFlag + 1); // Skip the `=`
 			setError = false;
 			return;
 
-		/* Otherwise, allow parsing as another flag */
+		// Otherwise, allow parsing as another flag
 		}
 	}
 
-	/* Well, it's either a normal warning or a mistake */
+	// Well, it's either a normal warning or a mistake
 
 	enum WarningState state = setError ? WARNING_ERROR :
-				  /* Not an error, then check if this is a negation */
+				  // Not an error, then check if this is a negation
 				  strncmp(flag, "no-", strlen("no-")) ? WARNING_ENABLED
 								      : WARNING_DISABLED;
 	char const *rootFlag = state == WARNING_DISABLED ? flag + strlen("no-") : flag;
@@ -304,10 +314,10 @@ void processWarningFlag(char *flag)
 		}
 	}
 
-	/* Try to match the flag against a "normal" flag */
+	// Try to match the flag against a "normal" flag
 	for (enum WarningID id = 0; id < NB_PLAIN_WARNINGS; id++) {
 		if (!strcmp(rootFlag, warningFlags[id])) {
-			/* We got a match! */
+			// We got a match!
 			warningStates[id] = state;
 			return;
 		}
@@ -370,7 +380,7 @@ void warning(enum WarningID id, char const *fmt, ...)
 
 	case WARNING_DEFAULT:
 		unreachable_();
-		/* Not reached */
+		// Not reached
 
 	case WARNING_ENABLED:
 		break;

src/check_bison_ver.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 bison -V | awk -v major="$1" -v minor="$2" '
 /^bison.*[0-9]+(\.[0-9]+)(\.[0-9]+)?$/ {
 	match($0, /[0-9]+(\.[0-9]+)(\.[0-9]+)?$/);

src/fix/main.c

@@ -29,7 +29,7 @@
 
 #define BANK_SIZE 0x4000
 
-/* Short options */
+// Short options
 static const char *optstring = "Ccf:i:jk:l:m:n:Op:r:st:Vv";
 
 /*
@@ -191,7 +191,7 @@ static void printAcceptedMBCNames(void)
 
 static uint8_t tpp1Rev[2];
 
-/**
+/*
  * @return False on failure
  */
 static bool readMBCSlice(char const **name, char const *expected)
@@ -837,7 +837,7 @@ static ssize_t writeBytes(int fd, void *buf, size_t len)
 	return total;
 }
 
-/**
+/*
  * @param rom0 A pointer to rom0
  * @param addr What address to check
  * @param fixedByte The fixed byte at the address
@@ -853,7 +853,7 @@ static void overwriteByte(uint8_t *rom0, uint16_t addr, uint8_t fixedByte, char
 	rom0[addr] = fixedByte;
 }
 
-/**
+/*
  * @param rom0 A pointer to rom0
  * @param startAddr What address to begin checking from
  * @param fixed The fixed bytes at the address
@@ -878,7 +878,7 @@ static void overwriteBytes(uint8_t *rom0, uint16_t startAddr, uint8_t const *fix
 	memcpy(&rom0[startAddr], fixed, size);
 }
 
-/**
+/*
  * @param input File descriptor to be used for reading
  * @param output File descriptor to be used for writing, may be equal to `input`
  * @param name The file's name, to be displayed for error output
@@ -1268,12 +1268,12 @@ do { \
 #define SPEC_H TRASH_HEADER_SUM
 #define SPEC_g FIX_GLOBAL_SUM
 #define SPEC_G TRASH_GLOBAL_SUM
-#define overrideSpec(new, bad) \
+#define overrideSpec(cur, bad) \
 do { \
 	if (fixSpec & SPEC_##bad) \
 		fprintf(stderr, \
-			"warning: '" #new "' overriding '" #bad "' in fix spec\n"); \
+			"warning: '" #cur "' overriding '" #bad "' in fix spec\n"); \
-	fixSpec = (fixSpec & ~SPEC_##bad) | SPEC_##new; \
+	fixSpec = (fixSpec & ~SPEC_##bad) | SPEC_##cur; \
 } while (0)
 				case 'l':
 					overrideSpec(l, L);

src/gfx/gb.c

@@ -1,386 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#include <stdint.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-#include "gfx/gb.h"
-
-void transpose_tiles(struct GBImage *gb, int width)
-{
-	uint8_t *newdata;
-	int i;
-	int newbyte;
-
-	newdata = calloc(gb->size, 1);
-	if (!newdata)
-		err("%s: Failed to allocate memory for new data", __func__);
-
-	for (i = 0; i < gb->size; i++) {
-		newbyte = i / (8 * depth) * width * 8 * depth;
-		newbyte = newbyte % gb->size
-			+ 8 * depth * (newbyte / gb->size)
-			+ i % (8 * depth);
-		newdata[newbyte] = gb->data[i];
-	}
-
-	free(gb->data);
-
-	gb->data = newdata;
-}
-
-void raw_to_gb(const struct RawIndexedImage *raw_image, struct GBImage *gb)
-{
-	int x, y, byte;
-	uint8_t index;
-
-	for (y = 0; y < raw_image->height; y++) {
-		for (x = 0; x < raw_image->width; x++) {
-			index = raw_image->data[y][x];
-			index &= (1 << depth) - 1;
-
-			byte = y * depth
-				+ x / 8 * raw_image->height / 8 * 8 * depth;
-			gb->data[byte] |= (index & 1) << (7 - x % 8);
-			if (depth == 2) {
-				gb->data[byte + 1] |=
-					(index >> 1) << (7 - x % 8);
-			}
-		}
-	}
-
-	if (!gb->horizontal)
-		transpose_tiles(gb, raw_image->width / 8);
-}
-
-void output_file(const struct Options *opts, const struct GBImage *gb)
-{
-	FILE *f;
-
-	f = fopen(opts->outfile, "wb");
-	if (!f)
-		err("%s: Opening output file '%s' failed", __func__,
-		    opts->outfile);
-
-	fwrite(gb->data, 1, gb->size - gb->trim * 8 * depth, f);
-
-	fclose(f);
-}
-
-int get_tile_index(uint8_t *tile, uint8_t **tiles, int num_tiles, int tile_size)
-{
-	int i, j;
-
-	for (i = 0; i < num_tiles; i++) {
-		for (j = 0; j < tile_size; j++) {
-			if (tile[j] != tiles[i][j])
-				break;
-		}
-
-		if (j >= tile_size)
-			return i;
-	}
-	return -1;
-}
-
-uint8_t reverse_bits(uint8_t b)
-{
-	uint8_t rev = 0;
-
-	rev |= (b & 0x80) >> 7;
-	rev |= (b & 0x40) >> 5;
-	rev |= (b & 0x20) >> 3;
-	rev |= (b & 0x10) >> 1;
-	rev |= (b & 0x08) << 1;
-	rev |= (b & 0x04) << 3;
-	rev |= (b & 0x02) << 5;
-	rev |= (b & 0x01) << 7;
-	return rev;
-}
-
-void xflip(uint8_t *tile, uint8_t *tile_xflip, int tile_size)
-{
-	int i;
-
-	for (i = 0; i < tile_size; i++)
-		tile_xflip[i] = reverse_bits(tile[i]);
-}
-
-void yflip(uint8_t *tile, uint8_t *tile_yflip, int tile_size)
-{
-	int i;
-
-	for (i = 0; i < tile_size; i++)
-		tile_yflip[i] = tile[(tile_size - i - 1) ^ (depth - 1)];
-}
-
-/*
- * get_mirrored_tile_index looks for `tile` in tile array `tiles`, also
- * checking x-, y-, and xy-mirrored versions of `tile`. If one is found,
- * `*flags` is set according to the type of mirroring and the index of the
- * matched tile is returned. If no match is found, -1 is returned.
- */
-int get_mirrored_tile_index(uint8_t *tile, uint8_t **tiles, int num_tiles,
-			    int tile_size, int *flags)
-{
-	int index;
-	uint8_t *tile_xflip;
-	uint8_t *tile_yflip;
-
-	index = get_tile_index(tile, tiles, num_tiles, tile_size);
-	if (index >= 0) {
-		*flags = 0;
-		return index;
-	}
-
-	tile_yflip = malloc(tile_size);
-	if (!tile_yflip)
-		err("%s: Failed to allocate memory for Y flip of tile",
-		    __func__);
-	yflip(tile, tile_yflip, tile_size);
-	index = get_tile_index(tile_yflip, tiles, num_tiles, tile_size);
-	if (index >= 0) {
-		*flags = YFLIP;
-		free(tile_yflip);
-		return index;
-	}
-
-	tile_xflip = malloc(tile_size);
-	if (!tile_xflip)
-		err("%s: Failed to allocate memory for X flip of tile",
-		    __func__);
-	xflip(tile, tile_xflip, tile_size);
-	index = get_tile_index(tile_xflip, tiles, num_tiles, tile_size);
-	if (index >= 0) {
-		*flags = XFLIP;
-		free(tile_yflip);
-		free(tile_xflip);
-		return index;
-	}
-
-	yflip(tile_xflip, tile_yflip, tile_size);
-	index = get_tile_index(tile_yflip, tiles, num_tiles, tile_size);
-	if (index >= 0)
-		*flags = XFLIP | YFLIP;
-
-	free(tile_yflip);
-	free(tile_xflip);
-	return index;
-}
-
-void create_mapfiles(const struct Options *opts, struct GBImage *gb,
-		     struct Mapfile *tilemap, struct Mapfile *attrmap)
-{
-	int i, j;
-	int gb_i;
-	int tile_size;
-	int max_tiles;
-	int num_tiles;
-	int index;
-	int flags;
-	int gb_size;
-	uint8_t *tile;
-	uint8_t **tiles;
-
-	tile_size = sizeof(*tile) * depth * 8;
-	gb_size = gb->size - (gb->trim * tile_size);
-	max_tiles = gb_size / tile_size;
-
-	/* If the input image doesn't fill the last tile, increase the count. */
-	if (gb_size > max_tiles * tile_size)
-		max_tiles++;
-
-	tiles = calloc(max_tiles, sizeof(*tiles));
-	if (!tiles)
-		err("%s: Failed to allocate memory for tiles", __func__);
-	num_tiles = 0;
-
-	if (*opts->tilemapfile) {
-		tilemap->data = calloc(max_tiles, sizeof(*tilemap->data));
-		if (!tilemap->data)
-			err("%s: Failed to allocate memory for tilemap data",
-			    __func__);
-		tilemap->size = 0;
-	}
-
-	if (*opts->attrmapfile) {
-		attrmap->data = calloc(max_tiles, sizeof(*attrmap->data));
-		if (!attrmap->data)
-			err("%s: Failed to allocate memory for attrmap data",
-			    __func__);
-		attrmap->size = 0;
-	}
-
-	gb_i = 0;
-	while (gb_i < gb_size) {
-		flags = 0;
-		tile = malloc(tile_size);
-		if (!tile)
-			err("%s: Failed to allocate memory for tile",
-			    __func__);
-		/*
-		 * If the input image doesn't fill the last tile,
-		 * `gb_i` will reach `gb_size`.
-		 */
-		for (i = 0; i < tile_size && gb_i < gb_size; i++) {
-			tile[i] = gb->data[gb_i];
-			gb_i++;
-		}
-		if (opts->unique) {
-			if (opts->mirror) {
-				index = get_mirrored_tile_index(tile, tiles,
-								num_tiles,
-								tile_size,
-								&flags);
-			} else {
-				index = get_tile_index(tile, tiles, num_tiles,
-						       tile_size);
-			}
-
-			if (index < 0) {
-				index = num_tiles;
-				tiles[num_tiles] = tile;
-				num_tiles++;
-			} else {
-				free(tile);
-			}
-		} else {
-			index = num_tiles;
-			tiles[num_tiles] = tile;
-			num_tiles++;
-		}
-		if (*opts->tilemapfile) {
-			tilemap->data[tilemap->size] = index;
-			tilemap->size++;
-		}
-		if (*opts->attrmapfile) {
-			attrmap->data[attrmap->size] = flags;
-			attrmap->size++;
-		}
-	}
-
-	if (opts->unique) {
-		free(gb->data);
-		gb->data = malloc(tile_size * num_tiles);
-		if (!gb->data)
-			err("%s: Failed to allocate memory for tile data",
-			    __func__);
-		for (i = 0; i < num_tiles; i++) {
-			tile = tiles[i];
-			for (j = 0; j < tile_size; j++)
-				gb->data[i * tile_size + j] = tile[j];
-		}
-		gb->size = i * tile_size;
-	}
-
-	for (i = 0; i < num_tiles; i++)
-		free(tiles[i]);
-
-	free(tiles);
-}
-
-void output_tilemap_file(const struct Options *opts,
-			 const struct Mapfile *tilemap)
-{
-	FILE *f;
-
-	f = fopen(opts->tilemapfile, "wb");
-	if (!f)
-		err("%s: Opening tilemap file '%s' failed", __func__,
-		    opts->tilemapfile);
-
-	fwrite(tilemap->data, 1, tilemap->size, f);
-	fclose(f);
-
-	if (opts->tilemapout)
-		free(opts->tilemapfile);
-}
-
-void output_attrmap_file(const struct Options *opts,
-			 const struct Mapfile *attrmap)
-{
-	FILE *f;
-
-	f = fopen(opts->attrmapfile, "wb");
-	if (!f)
-		err("%s: Opening attrmap file '%s' failed", __func__,
-		    opts->attrmapfile);
-
-	fwrite(attrmap->data, 1, attrmap->size, f);
-	fclose(f);
-
-	if (opts->attrmapout)
-		free(opts->attrmapfile);
-}
-
-/*
- * based on the Gaussian-like curve used by SameBoy since commit
- * 65dd02cc52f531dbbd3a7e6014e99d5b24e71a4c (Oct 2017)
- * with ties resolved by comparing the difference of the squares.
- */
-static int reverse_curve[] = {
-	0,  0,  1,  1,  2,  2,  3,  3,  3,  3,  4,  4,  4,  4,  4,  4,
-	5,  5,  5,  5,  5,  5,  6,  6,  6,  6,  6,  6,  6,  6,  7,  7,
-	7,  7,  7,  7,  7,  7,  7,  8,  8,  8,  8,  8,  8,  8,  8,  8,
-	9,  9,  9,  9,  9,  9,  9,  9,  9,  9,  10, 10, 10, 10, 10, 10,
-	10, 10, 10, 10, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11,
-	12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 13, 13, 13, 13,
-	13, 13, 13, 13, 13, 13, 13, 13, 14, 14, 14, 14, 14, 14, 14, 14,
-	14, 14, 14, 14, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15,
-	16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 17, 17, 17,
-	17, 17, 17, 17, 17, 17, 17, 17, 17, 18, 18, 18, 18, 18, 18, 18,
-	18, 18, 18, 18, 18, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19, 19,
-	19, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 21, 21, 21, 21,
-	21, 21, 21, 21, 21, 21, 21, 22, 22, 22, 22, 22, 22, 22, 22, 22,
-	22, 23, 23, 23, 23, 23, 23, 23, 23, 23, 24, 24, 24, 24, 24, 24,
-	24, 24, 25, 25, 25, 25, 25, 25, 25, 25, 26, 26, 26, 26, 26, 26,
-	26, 27, 27, 27, 27, 27, 28, 28, 28, 28, 29, 29, 29, 30, 30, 31,
-};
-
-void output_palette_file(const struct Options *opts,
-			 const struct RawIndexedImage *raw_image)
-{
-	FILE *f;
-	int i, color;
-	uint8_t cur_bytes[2];
-
-	f = fopen(opts->palfile, "wb");
-	if (!f)
-		err("%s: Opening palette file '%s' failed", __func__,
-		    opts->palfile);
-
-	for (i = 0; i < raw_image->num_colors; i++) {
-		int r = raw_image->palette[i].red;
-		int g = raw_image->palette[i].green;
-		int b = raw_image->palette[i].blue;
-
-		if (opts->colorcurve) {
-			g = (g * 4 - b) / 3;
-			if (g < 0)
-				g = 0;
-
-			r = reverse_curve[r];
-			g = reverse_curve[g];
-			b = reverse_curve[b];
-		} else {
-			r >>= 3;
-			g >>= 3;
-			b >>= 3;
-		}
-
-		color = b << 10 | g << 5 | r;
-		cur_bytes[0] = color & 0xFF;
-		cur_bytes[1] = color >> 8;
-		fwrite(cur_bytes, 2, 1, f);
-	}
-	fclose(f);
-
-	if (opts->palout)
-		free(opts->palfile);
-}

src/gfx/main.c

@@ -1,358 +0,0 @@
-/*
- * This file is part of RGBDS.
- *
- * Copyright (c) 2013-2018, stag019 and RGBDS contributors.
- *
- * SPDX-License-Identifier: MIT
- */
-
-#include <png.h>
-#include <stdlib.h>
-#include <string.h>
-
-#include "gfx/main.h"
-
-#include "extern/getopt.h"
-#include "version.h"
-
-int depth, colors;
-
-/* Short options */
-static char const *optstring = "Aa:CDd:Ffhmo:Pp:Tt:uVvx:";
-
-/*
- * Equivalent long options
- * Please keep in the same order as short opts
- *
- * Also, make sure long opts don't create ambiguity:
- * A long opt's name should start with the same letter as its short opt,
- * except if it doesn't create any ambiguity (`verbose` versus `version`).
- * This is because long opt matching, even to a single char, is prioritized
- * over short opt matching
- */
-static struct option const longopts[] = {
-	{ "output-attr-map", no_argument,       NULL, 'A' },
-	{ "attr-map",        required_argument, NULL, 'a' },
-	{ "color-curve",     no_argument,       NULL, 'C' },
-	{ "debug",           no_argument,       NULL, 'D' },
-	{ "depth",           required_argument, NULL, 'd' },
-	{ "fix",             no_argument,       NULL, 'f' },
-	{ "fix-and-save",    no_argument,       NULL, 'F' },
-	{ "horizontal",      no_argument,       NULL, 'h' },
-	{ "mirror-tiles",    no_argument,       NULL, 'm' },
-	{ "output",          required_argument, NULL, 'o' },
-	{ "output-palette",  no_argument,       NULL, 'P' },
-	{ "palette",         required_argument, NULL, 'p' },
-	{ "output-tilemap",  no_argument,       NULL, 'T' },
-	{ "tilemap",         required_argument, NULL, 't' },
-	{ "unique-tiles",    no_argument,       NULL, 'u' },
-	{ "version",         no_argument,       NULL, 'V' },
-	{ "verbose",         no_argument,       NULL, 'v' },
-	{ "trim-end",        required_argument, NULL, 'x' },
-	{ NULL,              no_argument,       NULL, 0   }
-};
-
-static void print_usage(void)
-{
-	fputs(
-"Usage: rgbgfx [-CDhmuVv] [-f | -F] [-a <attr_map> | -A] [-d <depth>]\n"
-"              [-o <out_file>] [-p <pal_file> | -P] [-t <tile_map> | -T]\n"
-"              [-x <tiles>] <file>\n"
-"Useful options:\n"
-"    -f, --fix                 make the input image an indexed PNG\n"
-"    -m, --mirror-tiles        optimize out mirrored tiles\n"
-"    -o, --output <path>       set the output binary file\n"
-"    -t, --tilemap <path>      set the output tilemap file\n"
-"    -u, --unique-tiles        optimize out identical tiles\n"
-"    -V, --version             print RGBGFX version and exit\n"
-"\n"
-"For help, use `man rgbgfx' or go to https://rgbds.gbdev.io/docs/\n",
-	      stderr);
-	exit(1);
-}
-
-int main(int argc, char *argv[])
-{
-	int ch, size;
-	struct Options opts = {0};
-	struct ImageOptions png_options = {0};
-	struct RawIndexedImage *raw_image;
-	struct GBImage gb = {0};
-	struct Mapfile tilemap = {0};
-	struct Mapfile attrmap = {0};
-	char *ext;
-
-	opts.tilemapfile = "";
-	opts.attrmapfile = "";
-	opts.palfile = "";
-	opts.outfile = "";
-
-	depth = 2;
-
-	while ((ch = musl_getopt_long_only(argc, argv, optstring, longopts,
-					   NULL)) != -1) {
-		switch (ch) {
-		case 'A':
-			opts.attrmapout = true;
-			break;
-		case 'a':
-			opts.attrmapfile = musl_optarg;
-			break;
-		case 'C':
-			opts.colorcurve = true;
-			break;
-		case 'D':
-			opts.debug = true;
-			break;
-		case 'd':
-			depth = strtoul(musl_optarg, NULL, 0);
-			break;
-		case 'F':
-			opts.hardfix = true;
-			/* fallthrough */
-		case 'f':
-			opts.fix = true;
-			break;
-		case 'h':
-			opts.horizontal = true;
-			break;
-		case 'm':
-			opts.mirror = true;
-			opts.unique = true;
-			break;
-		case 'o':
-			opts.outfile = musl_optarg;
-			break;
-		case 'P':
-			opts.palout = true;
-			break;
-		case 'p':
-			opts.palfile = musl_optarg;
-			break;
-		case 'T':
-			opts.tilemapout = true;
-			break;
-		case 't':
-			opts.tilemapfile = musl_optarg;
-			break;
-		case 'u':
-			opts.unique = true;
-			break;
-		case 'V':
-			printf("rgbgfx %s\n", get_package_version_string());
-			exit(0);
-		case 'v':
-			opts.verbose = true;
-			break;
-		case 'x':
-			opts.trim = strtoul(musl_optarg, NULL, 0);
-			break;
-		default:
-			print_usage();
-			/* NOTREACHED */
-		}
-	}
-	argc -= musl_optind;
-	argv += musl_optind;
-
-	if (argc == 0) {
-		fputs("FATAL: no input files\n", stderr);
-		print_usage();
-	}
-
-#define WARN_MISMATCH(property) \
-	warnx("The PNG's " property \
-	      " setting doesn't match the one defined on the command line")
-
-	opts.infile = argv[argc - 1];
-
-	if (depth != 1 && depth != 2)
-		errx("Depth option must be either 1 or 2.");
-
-	colors = 1 << depth;
-
-	raw_image = input_png_file(&opts, &png_options);
-
-	png_options.tilemapfile = "";
-	png_options.attrmapfile = "";
-	png_options.palfile = "";
-
-	if (png_options.horizontal != opts.horizontal) {
-		if (opts.verbose)
-			WARN_MISMATCH("horizontal");
-
-		if (opts.hardfix)
-			png_options.horizontal = opts.horizontal;
-	}
-
-	if (png_options.horizontal)
-		opts.horizontal = png_options.horizontal;
-
-	if (png_options.trim != opts.trim) {
-		if (opts.verbose)
-			WARN_MISMATCH("trim");
-
-		if (opts.hardfix)
-			png_options.trim = opts.trim;
-	}
-
-	if (png_options.trim)
-		opts.trim = png_options.trim;
-
-	if (raw_image->width % 8) {
-		errx("Input PNG file %s not sized correctly. The image's width must be a multiple of 8.",
-		     opts.infile);
-	}
-	if (raw_image->width / 8 > 1 && raw_image->height % 8) {
-		errx("Input PNG file %s not sized correctly. If the image is more than 1 tile wide, its height must be a multiple of 8.",
-		     opts.infile);
-	}
-
-	if (opts.trim &&
-	    opts.trim > (raw_image->width / 8) * (raw_image->height / 8) - 1) {
-		errx("Trim (%d) for input raw_image file '%s' too large (max: %u)",
-		     opts.trim, opts.infile,
-		     (raw_image->width / 8) * (raw_image->height / 8) - 1);
-	}
-
-	if (strcmp(png_options.tilemapfile, opts.tilemapfile) != 0) {
-		if (opts.verbose)
-			WARN_MISMATCH("tilemap file");
-
-		if (opts.hardfix)
-			png_options.tilemapfile = opts.tilemapfile;
-	}
-	if (!*opts.tilemapfile)
-		opts.tilemapfile = png_options.tilemapfile;
-
-	if (png_options.tilemapout != opts.tilemapout) {
-		if (opts.verbose)
-			WARN_MISMATCH("tilemap file");
-
-		if (opts.hardfix)
-			png_options.tilemapout = opts.tilemapout;
-	}
-	if (png_options.tilemapout)
-		opts.tilemapout = png_options.tilemapout;
-
-	if (strcmp(png_options.attrmapfile, opts.attrmapfile) != 0) {
-		if (opts.verbose)
-			WARN_MISMATCH("attrmap file");
-
-		if (opts.hardfix)
-			png_options.attrmapfile = opts.attrmapfile;
-	}
-	if (!*opts.attrmapfile)
-		opts.attrmapfile = png_options.attrmapfile;
-
-	if (png_options.attrmapout != opts.attrmapout) {
-		if (opts.verbose)
-			WARN_MISMATCH("attrmap file");
-
-		if (opts.hardfix)
-			png_options.attrmapout = opts.attrmapout;
-	}
-	if (png_options.attrmapout)
-		opts.attrmapout = png_options.attrmapout;
-
-	if (strcmp(png_options.palfile, opts.palfile) != 0) {
-		if (opts.verbose)
-			WARN_MISMATCH("palette file");
-
-		if (opts.hardfix)
-			png_options.palfile = opts.palfile;
-	}
-	if (!*opts.palfile)
-		opts.palfile = png_options.palfile;
-
-	if (png_options.palout != opts.palout) {
-		if (opts.verbose)
-			WARN_MISMATCH("palette file");
-
-		if (opts.hardfix)
-			png_options.palout = opts.palout;
-	}
-
-#undef WARN_MISMATCH
-
-	if (png_options.palout)
-		opts.palout = png_options.palout;
-
-	if (!*opts.tilemapfile && opts.tilemapout) {
-		ext = strrchr(opts.infile, '.');
-
-		if (ext != NULL) {
-			size = ext - opts.infile + 9;
-			opts.tilemapfile = malloc(size);
-			strncpy(opts.tilemapfile, opts.infile, size);
-			*strrchr(opts.tilemapfile, '.') = '\0';
-			strcat(opts.tilemapfile, ".tilemap");
-		} else {
-			opts.tilemapfile = malloc(strlen(opts.infile) + 9);
-			strcpy(opts.tilemapfile, opts.infile);
-			strcat(opts.tilemapfile, ".tilemap");
-		}
-	}
-
-	if (!*opts.attrmapfile && opts.attrmapout) {
-		ext = strrchr(opts.infile, '.');
-
-		if (ext != NULL) {
-			size = ext - opts.infile + 9;
-			opts.attrmapfile = malloc(size);
-			strncpy(opts.attrmapfile, opts.infile, size);
-			*strrchr(opts.attrmapfile, '.') = '\0';
-			strcat(opts.attrmapfile, ".attrmap");
-		} else {
-			opts.attrmapfile = malloc(strlen(opts.infile) + 9);
-			strcpy(opts.attrmapfile, opts.infile);
-			strcat(opts.attrmapfile, ".attrmap");
-		}
-	}
-
-	if (!*opts.palfile && opts.palout) {
-		ext = strrchr(opts.infile, '.');
-
-		if (ext != NULL) {
-			size = ext - opts.infile + 5;
-			opts.palfile = malloc(size);
-			strncpy(opts.palfile, opts.infile, size);
-			*strrchr(opts.palfile, '.') = '\0';
-			strcat(opts.palfile, ".pal");
-		} else {
-			opts.palfile = malloc(strlen(opts.infile) + 5);
-			strcpy(opts.palfile, opts.infile);
-			strcat(opts.palfile, ".pal");
-		}
-	}
-
-	gb.size = raw_image->width * raw_image->height * depth / 8;
-	gb.data = calloc(gb.size, 1);
-	gb.trim = opts.trim;
-	gb.horizontal = opts.horizontal;
-
-	if (*opts.outfile || *opts.tilemapfile || *opts.attrmapfile) {
-		raw_to_gb(raw_image, &gb);
-		create_mapfiles(&opts, &gb, &tilemap, &attrmap);
-	}
-
-	if (*opts.outfile)
-		output_file(&opts, &gb);
-
-	if (*opts.tilemapfile)
-		output_tilemap_file(&opts, &tilemap);
-
-	if (*opts.attrmapfile)
-		output_attrmap_file(&opts, &attrmap);
-
-	if (*opts.palfile)
-		output_palette_file(&opts, raw_image);
-
-	if (opts.fix || opts.debug)
-		output_png_file(&opts, &png_options, raw_image);
-
-	destroy_raw_image(&raw_image);
-	free(gb.data);
-
-	return 0;
-}