docs: document the settings-icons switches and icon caches

BUILDING.md: the plug-in's ADRENO_PIPELINE and ADRENO_SETTINGS_ICONS
build switches (0 or 1; unset or 0 leaves the build unchanged) and the
suites that test the latter. RUNNING.md: a plug-in that changes icon
rendering needs IconServices' store, the user icon caches and the
Dock's icon cache renamed aside from the single-user shell before the
boot continues, and the order that does it with deploy-guest-plugin.py
and guest-console.py under one owner; ADRENO_IB_CS_SAMPLERS stays off
without the boot-arg adreno_cs_samplers=1, which cycle.py cannot add
yet.

docs/BUILDING.md

@@ -158,6 +158,17 @@ host test harness (`regtest`). Optional environment variables:
 
 - `ADRENO_LENIENT=1` drops a pass the encoder refuses instead of failing the
   command buffer. Use it for deployment; the tests use the strict default.
+- `ADRENO_PIPELINE=1` builds for the desktop AdrenoX2's IB pipeline (IOSurface
+  shadows wait for the GPU). The deployed plug-ins use it with `ADRENO_LENIENT=1`.
+- `ADRENO_SETTINGS_ICONS=1` encodes the CoreImage kernels of the icons inside
+  System Settings panes: sampled sRGB and grey+alpha textures, and multi-input
+  kernels once AdrenoX2 publishes `AdrenoIBComputeSamplers` (its
+  `ADRENO_IB_CS_SAMPLERS`, opted in with the guest boot-arg
+  `adreno_cs_samplers=1`). `tools/test-adreno-settings-icons.py` and
+  `tools/test-adreno-settings-ci-encoding.py` test it.
+
+`ADRENO_PIPELINE` and `ADRENO_SETTINGS_ICONS` take 0 or 1; 0 or unset leaves the
+build byte for byte as without them.
 - `ADRENO_SHADER_CACHE_PACK=<file>` links a precompiled shader pack into the
   bundle.
 - `ADRENO_COMPILER_RUNTIME=<dir>` bundles the air2ir3 runtime

docs/RUNNING.md

@@ -200,6 +200,21 @@ python3 tools/deploy-guest-plugin.py --device udp://<interface> \
 The tool checks every file against its expected base before writing anything,
 keeps backups, and can put them back with `--restore`.
 
+A plug-in that changes how icons render has no visible effect until the icons
+already rendered are dropped: IconServices keeps them in
+`/Library/Caches/com.apple.iconservices.store` and in each user's cache folder
+(`com.apple.iconservices`, `com.apple.iconservicesagent`), and the Dock keeps its
+own `com.apple.dock.iconcache` there. Rename them aside from the single-user
+shell, after the install and before the boot continues: run the tool without
+`--continue-boot`, rename the caches with `tools/guest-console.py --run` under the
+same `--owner`, then run the tool again with `--continue-boot` (it finds the files
+installed and only continues the boot).
+
+The kext side of the icons inside System Settings panes, `ADRENO_IB_CS_SAMPLERS`
+in the desktop AdrenoX2 profiles, is off unless the guest boots with
+`adreno_cs_samplers=1`. `tools/cycle.py` has no option that adds that boot-arg
+yet.
+
 ## Exit codes
 
 A boot reports why the guest stopped: