Document more about the RGBDS architecture (#1809)

Author: Rangi42

.editorconfig

@@ -2,7 +2,7 @@
 root = true
 indent_style = tab
 indent_size = tab
-tab_width = 8
+tab_width = 4
 charset = utf-8
 insert_final_newline = true
 trim_trailing_whitespace = true

ARCHITECTURE.md

@@ -51,8 +51,8 @@ but doesn't know that there's someone working on it.
 
 Note that you must contribute all your changes under the MIT License. If you are
 just modifying a file, you don't need to do anything (maybe update the copyright
-years). If you are adding new files, you need to use the `SPDX-License-Identifier: MIT`
-header.
+years). If you are adding new files, you need to use the
+`SPDX-License-Identifier: MIT` header.
 
 1. Fork this repository.
 2. Checkout the `master` branch.
@@ -63,71 +63,97 @@ header.
    new warning (but it may be possible to remove some warning checks if it makes
    the code much easier).
 5. Test your changes by running `./run-tests.sh` in the `test` directory.
-   (You must run `./fetch-test-deps.sh` first; if you forget to, the test suite will fail and remind you mid-way.)
+   (You must run `./fetch-test-deps.sh` first; if you forget to, the test suite
+   will fail and remind you mid-way.)
 5. Format your changes according to `clang-format`, which will reformat the
    coding style according to our standards defined in `.clang-format`.
 6. Create a pull request against the branch `master`.
-7. Be prepared to get some comments about your code and to modify it. Tip: Use
+7. Check the results of the GitHub Actions CI jobs for your pull request. The
+   "Code format checking" and "Regression testing" jobs should all succeed.
+   The "Diff completeness check" and "Static analysis" jobs should be manually
+   checked, as they may output warnings which do not count as failure errors.
+   The "Code coverage report" provides an
+   [LCOV](https://github.com/linux-test-project/lcov)-generated report which
+   can be downloaded and checked to see if your new code has full test coverage.
+8. Be prepared to get some comments about your code and to modify it. Tip: Use
    `git rebase -i origin/master` to modify chains of commits.
 
 ## Adding a test
 
-The test suite is a little ad-hoc, so the way tests work is different for each program being tested.
+The test suite is a little ad-hoc, so the way tests work is different for each
+program being tested.
 
-Feel free to modify how the test scripts work, if the thing you want to test doesn't fit the existing scheme(s).
+Feel free to modify how the test scripts work, if the thing you want to test
+doesn't fit the existing scheme(s).
 
 ### RGBASM
 
 Each `.asm` file corresponds to one test.
 RGBASM will be invoked on the `.asm` file with all warnings enabled.
 
-If a `.out` file exists, RGBASM's output (`print`, `println`, etc.) must match its contents.
-If a `.err` file exists, RGBASM's error output (`warn`, errors, etc.) must match its contents.
+If a `.out` file exists, RGBASM's output (`print`, `println`, etc.) must match
+its contents.
+If a `.err` file exists, RGBASM's error output (`warn`, errors, etc.) must match
+its contents.
 
-If a `.out.bin` file exists, the object file will be linked, and the generated ROM truncated to the length of the `.out.bin` file.
+If a `.out.bin` file exists, the object file will be linked, and the generated
+ROM truncated to the length of the `.out.bin` file.
 After that, the ROM must match the `.out.bin` file.
 
 ### RGBLINK
 
 Each `.asm` file corresponds to one test, or one *set* of tests.
 
-All tests begin by assembling the `.asm` file into an object file, which will be linked in various ways depending on the test.
+All tests begin by assembling the `.asm` file into an object file, which will be
+linked in various ways depending on the test.
 
 #### Simple tests
 
 These simply check that RGBLINK's output matches some expected output.
 
-A `.out` file **must** exist, and RGBLINK's total output must match that file's contents.
+A `.out` file **must** exist, and RGBLINK's total output must match that file's
+contents.
 
-Additionally, if a `.out.bin` file exists, the `.gb` file generated by RGBLINK must match it.
+Additionally, if a `.out.bin` file exists, the `.gb` file generated by RGBLINK
+must match it.
 
 #### Linker script tests
 
 These allow applying various linker scripts to the same object file.
-If one or more `.link` files exist, whose names start the same as the `.asm` file, then each of those files correspond to one test.
+If one or more `.link` files exist, whose names start the same as the `.asm`
+file, then each of those files correspond to one test.
 
-Each `.link` linker script **must** be accompanied by a `.out` file, and RGBLINK's total output must match that file's contents when passed the corresponding linker script.
+Each `.link` linker script **must** be accompanied by a `.out` file, and
+RGBLINK's total output must match that file's contents when passed the
+corresponding linker script.
 
 #### Variant tests
 
 These allow testing RGBLINK's `-d`, `-t`, and `-w` flags.
-If one or more <code>-<var>&lt;flag&gt;</var>.out</code> or <code>-no-<var>&lt;flag&gt;</var>.out</code> files exist, then each of them corresponds to one test.
+If one or more
+<code>-<var>&lt;flag&gt;</var>.out</code> or <code>-no-<var>&lt;flag&gt;</var>.out</code>
+files exist, then each of them corresponds to one test.
 
-The object file will be linked with and without said flag, respectively; and in each case, RGBLINK's total output must match the `.out` file's contents.
+The object file will be linked with and without said flag, respectively; and in
+each case, RGBLINK's total output must match the `.out` file's contents.
 
 ### RGBFIX
 
 Each `.flags` file corresponds to one test.
 Each one is a text file whose first line contains flags to pass to RGBFIX.
-(There may be more lines, which will be ignored; they can serve as comments to explain what the test is about.)
+(There may be more lines, which will be ignored; they can serve as comments to
+explain what the test is about.)
 
-RGBFIX will be invoked on the `.bin` file if it exists, or else on default-input.bin.
+RGBFIX will be invoked on the `.bin` file if it exists, or else on
+default-input.bin.
 
 If no `.out` file exist, RGBFIX is not expected to output anything.
 If one *does* exist, RGBFIX's output **must** match the `.out` file's contents.
 
-If no `.err` file exists, RGBFIX is simply expected to be able to process the file normally.
-If one *does* exist, RGBFIX's return status is ignored, but its error output **must** match the `.err` file's contents.
+If no `.err` file exists, RGBFIX is simply expected to be able to process the
+file normally.
+If one *does* exist, RGBFIX's return status is ignored, but its error output
+**must** match the `.err` file's contents.
 
 Additionally, if a `.gb` file exists, the output of RGBFIX must match the `.gb`.
 
@@ -139,20 +165,27 @@ There are three kinds of test.
 
 Each `.png` file corresponds to one test.
 RGBGFX will be invoked on the file.
-If a `.flags` file exists, it will be used as part of the RGBGFX invocation (<code>@<var>&lt;file&gt;</var>.flags</code>).
+If a `.flags` file exists, it will be used as part of the RGBGFX invocation
+(<code>@<var>&lt;file&gt;</var>.flags</code>).
 
-If `.out.1bpp`, `.out.2bpp`, `.out.pal`, `.out.tilemap`, `.out.attrmap`, or `.out.palmap` files exist, RGBGFX will create the corresponding kind of output, which must match the file's contents.
+If `.out.1bpp`, `.out.2bpp`, `.out.pal`, `.out.tilemap`, `.out.attrmap`, or
+`.out.palmap` files exist, RGBGFX will create the corresponding kind of output,
+which must match the file's contents.
 Multiple kinds of output may be tested for the same input.
 
-If no `.err` file exists, RGBGFX is simply expected to be able to process the file normally.
-If one *does* exist, RGBGFX's return status is ignored, but its output **must** match the `.err` file's contents.
+If no `.err` file exists, RGBGFX is simply expected to be able to process the
+file normally.
+If one *does* exist, RGBGFX's return status is ignored, but its output **must**
+match the `.err` file's contents.
 
 #### Reverse tests
 
 Each `.1bpp` or `.2bpp` file corresponds to one test.
-RGBGFX will be invoked on the file with `-r 1` for reverse mode, then invoked on the output without `-r 1`.
+RGBGFX will be invoked on the file with `-r 1` for reverse mode, then invoked on
+the output without `-r 1`.
 The round-trip output must match the input file's contents.
-If a `.flags` file exists, it will be used as part of the RGBGFX invocation (<code>@<var>&lt;file&gt;</var>.flags</code>).
+If a `.flags` file exists, it will be used as part of the RGBGFX invocation
+(<code>@<var>&lt;file&gt;</var>.flags</code>).
 
 #### Random seed tests
 
@@ -161,30 +194,41 @@ Each one is a binary RNG file which is passed to the `rgbgfx_test` program.
 
 ### Downstream projects
 
-1. Make sure the downstream project supports <code>make <var>&lt;target&gt;</var> RGBDS=<var>&lt;path/to/RGBDS/&gt;</var></code>.
-   While the test suite supports any Make target name, only [Make](//gnu.org/software/make) is currently supported, and the Makefile must support a `RGBDS` variable to use a non-system RGBDS directory.
-
+1. Make sure the downstream project supports
+   <code>make <var>&lt;target&gt;</var> RGBDS=<var>&lt;path/to/RGBDS/&gt;</var></code>.
+   While the test suite supports any Make target name, only
+   [Make](//gnu.org/software/make) is currently supported, and the Makefile must
+   support a `RGBDS` variable to use a non-system RGBDS directory.
+   
    Also, only projects hosted on GitHub are currently supported.
-2. Add the project to `test/fetch-test-deps.sh`: add a new `action` line at the bottom, following the existing pattern:
+2. Add the project to `test/fetch-test-deps.sh`: add a new `action` line at the
+   bottom, following the existing pattern:
 
    ```sh
    action  <owner>  <repo>  <date of last commit>  <hash of last commit>
    ```
-
-   (The date is used to avoid fetching too much history when cloning the repositories.)
-3. Add the project to `test/run-tests.sh`: add a new `test_downstream` line at the bottom, following the existing pattern:
-
+   
+   (The date is used to avoid fetching too much history when cloning the
+   repositories.)
+3. Add the project to `test/run-tests.sh`: add a new `test_downstream` line at
+   the bottom, following the existing pattern:
+   
    ```sh
    test_downstream  <owner>  <repo>  <makefile target>  <build file>  <sha1 hash of build file>
    ```
 
 ## Container images
 
-The CI will [take care](https://github.com/gbdev/rgbds/blob/master/.github/workflows/build-container.yml) of updating the [rgbds container](https://github.com/gbdev/rgbds/pkgs/container/rgbds) image tagged `master`.
+The CI will
+[take care](https://github.com/gbdev/rgbds/blob/master/.github/workflows/build-container.yml)
+of updating the
+[rgbds container](https://github.com/gbdev/rgbds/pkgs/container/rgbds) image
+tagged `master`.
 
 When a git tag is pushed, the image is also tagged with that tag.
 
-The image can be built locally and pushed to the GitHub container registry by manually running:
+The image can be built locally and pushed to the GitHub container registry by
+manually running:
 
 ```bash
 # e.g. to build and tag as 'master'

CONTRIBUTING.md

@@ -44,5 +44,5 @@ RGBGFX generates palettes using algorithms found in the paper
 ([GitHub](https://github.com/pagination-problem/pagination), MIT license),
 by Aristide Grange, Imed Kacem, and Sébastien Martin.
 
-RGBGFX's color palette was taken from [SameBoy](https://sameboy.github.io), with permission and help
-by [LIJI](https://github.com/LIJI32).
+RGBGFX's color palette was taken from [SameBoy](https://sameboy.github.io), with
+permission and help by [LIJI](https://github.com/LIJI32).

CONTRIBUTORS.md

@@ -12,7 +12,7 @@ RUN apt-get update && \
 RUN ./.github/scripts/install_deps.sh ubuntu-22.04
 RUN make -j CXXFLAGS="-O3 -flto -DNDEBUG -static" PKG_CONFIG="pkg-config --static" Q=
 
-# Create an archive with the compiled executables and all the necessary to install it, 
+# Create an archive with the compiled executables and all the necessary to install it,
 # so it can be copied outside of the container and installed/used in another system
 RUN tar caf rgbds-linux-x86_64.tar.xz --transform='s#.*/##' rgbasm rgblink rgbfix rgbgfx man/* .github/scripts/install.sh
 

Dockerfile

@@ -573,7 +573,7 @@ Flags: See
 ComPLement accumulator
 .Po Sy A
 =
-.Sy ~A 
+.Sy ~A
 .Pc ;
 also called bitwise NOT.
 .Pp