Reference for the APS5_* environment variables

[fisherjoey]

Problem

main (df16c4c) reads 319 distinct APS5_* names through getenv, on 444 lines in 92 files under core/. A few more go through IsEnvironmentSet, kibSetting and MaskFromEnvironment. By prefix: 123 are APS5_NO_* switches, 40 APS5_TRACE_*, 12 APS5_DUMP_*. 251 are read as presence checks (!= nullptr); the rest take a number or a string.

Two of them are documented: APS5_PIPELINE_STATS in docs/dev/BUILD.md and APS5_COARSE_TIMED_WAITS in TechnicalDebt.md. Code comments are not allowed, so the call site doesn't say what a variable does or what its default is. Finding the right one means reading the code. Examples from our own debugging: the 6144 default of APS5_HOST_IMPORT_MIB, APS5_TEXTURE_CACHE_MIB, and the fact that APS5_DUMP_TARGETS dumps only non-resident targets unless APS5_NO_RESIDENT_TARGETS=1 is set.

Proposal

1. docs/dev/ENVIRONMENT.md: one table per library with name, kind (presence, integer, string), default, source file and a one-line description. The descriptions live in the doc, since they can't go in the code.
2. tools/env_reference.py: lists every APS5_* name the code reads (getenv and the helpers above), with its file and kind. --check compares that list with the table and prints names that are missing from the doc or no longer read.
3. tools/check_conventions.py runs the same check, so a pull request that adds a new getenv("APS5_...") also adds a row, and one that removes the last read removes the row. No new workflow.

The first pull request would add the doc with all current names and the check. If writing ~320 descriptions in one go is too much to review, the first one can cover the generated columns plus descriptions for the driver (libSceAgcDriver), and the rest follow per library.

What we have

A script that produces the name, file:line and kind list from git grep. The descriptions are not written yet. We would write them from the code and mark the ones we can't settle from the code alone for review.

Questions

• Would you take this as a pull request? CONTRIBUTING asks for gaps to go into TechnicalDebt instead of new files; is a separate ENVIRONMENT.md acceptable, or should it be a section of BUILD.md next to APS5_PIPELINE_STATS?
• Is a hard failure in the Conventions check acceptable for a missing row, or should it be a warning?
• Should APS5_* CMake options (APS5_ENABLE_TIMING_LOG, APS5_AGC_CREATE_LOG) stay in BUILD.md only?

AI-assisted: yes