diff options
| -rw-r--r-- | doc/STRIPPING.md | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/STRIPPING.md b/doc/STRIPPING.md new file mode 100644 index 0000000..7e69177 --- /dev/null +++ b/doc/STRIPPING.md @@ -0,0 +1,46 @@ +# Build Stripping Rules + +This document outlines the rules for stripping non-essential code from the final binary under the `STRIP_ALL` macro to achieve the <=64k size target. + +## General Principles + +- **Code Reduction:** Any code that is not critical for the demo's core functionality or runtime presentation should be conditionalized under `STRIP_ALL`. +- **Debug Features:** All debugging outputs, logging, and optional features not relevant to the final presentation must be stripped. +- **Configuration:** Minimize code paths related to configuration and argument parsing that are not essential for the demo's execution. +- **Dependencies:** Be mindful of dependencies pulled in by stripped features; their removal might also be necessary. + +## Specific Stripping Targets + +### 1. Debug Outputs & Logging + +- **`printf`, `std::cerr`, `std::cout`:** Wrap all non-essential output statements within `#if !defined(STRIP_ALL)`. This includes: + - Informational messages during initialization. + - Debug logs from various systems (rendering, audio, etc.). + - Error messages that are not critical for runtime stability (e.g., recoverable warnings). + - Assert messages that are covered by runtime checks or are only for development. + +### 2. Command-Line Interface (CLI) Arguments + +- **Optional Flags:** Disable or remove CLI arguments that are purely for debugging or development purposes. This includes, but is not limited to: + - `--seek` (if not part of a required feature). + - Resolution adjustment flags. + - Debug visualization toggles (e.g., `--debug`). + - Verbose logging flags. + +### 3. Debug Fields in Structs + +- **Non-Essential Members:** Remove members from structs that are used solely for debugging or development. Examples include: + - `label` or `name` fields in objects or data structures. + - Pointers or data structures intended only for inspection. + - Temporary variables or buffers used only during development. + +### 4. Dynamic Audio Generation + +- **`generate_tone` and `generate_melody` functions:** These functions are used for runtime audio synthesis. If the final demo relies solely on pre-packaged spectrogram assets and does not require dynamic generation, these functions and their associated global variables (`g_spec_buffer_a`, `g_spec_buffer_b`, `g_melody_data`) should be wrapped in `#if !defined(STRIP_ALL)`. +- **`register_spec_asset` function:** This function is used to load spectrograms from assets. While useful, if all necessary spectrograms are embedded directly or if asset loading is deemed non-critical for the stripped build, consider conditionalizing its calls or the function itself. + +## Implementation Strategy + +- **Iterative Removal:** Apply stripping rules iteratively. After each set of changes, rebuild and test to ensure no regressions. +- **Compiler Warnings:** Pay close attention to compiler warnings, as they can indicate unintended side effects of stripping. +- **Testing:** Ensure that core functionality remains intact after stripping. Existing tests should pass. |