From 70c64867baa30c83334559d3023153dfe3f9ff79 Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 9 Feb 2026 10:43:11 +0100 Subject: docs: Simplify all design docs (50% reduction, 1687 lines removed) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consolidated and streamlined all documentation: **Merged:** - PROCEDURAL.md → deleted (content in ASSET_SYSTEM.md) - FETCH_DEPS.md → BUILD.md (dependencies section) **Simplified (line reductions):** - HOWTO.md: 468→219 (53%) - CONTRIBUTING.md: 453→173 (62%) - SPECTRAL_BRUSH_EDITOR.md: 497→195 (61%) - SEQUENCE.md: 355→197 (45%) - CONTEXT_MAINTENANCE.md: 332→200 (40%) - test_demo_README.md: 273→122 (55%) - ASSET_SYSTEM.md: 271→108 (60%) - MASKING_SYSTEM.md: 240→125 (48%) - 3D.md: 196→118 (40%) - TRACKER.md: 124→76 (39%) - SCENE_FORMAT.md: 59→49 (17%) - BUILD.md: 83→69 (17%) **Total:** 3344→1657 lines (50.4% reduction) **Changes:** - Removed verbose examples, redundant explanations, unimplemented features - Moved detailed task plans to TODO.md (single source of truth) - Consolidated coding style rules - Kept essential APIs, syntax references, technical details **PROJECT_CONTEXT.md:** - Added "Design Docs Quick Reference" with 2-3 line summaries - Removed duplicate task entries - All design docs now loaded on-demand via Read tool Result: Context memory files reduced from 31.6k to ~15k tokens. --- doc/BUILD.md | 105 ++++++++++++++++++++++++++--------------------------------- 1 file changed, 46 insertions(+), 59 deletions(-) (limited to 'doc/BUILD.md') diff --git a/doc/BUILD.md b/doc/BUILD.md index e78aa91..1f65122 100644 --- a/doc/BUILD.md +++ b/doc/BUILD.md @@ -1,82 +1,69 @@ # Build Instructions -Debug build: +## Quick Start + +```bash +# Development build cmake -S . -B build -cmake --build build +cmake --build build -j4 -Size-optimized build: +# Size-optimized build cmake -S . -B build -DDEMO_SIZE_OPT=ON -cmake --build build - -## Windows Cross-Compilation (from macOS) - -Requires `mingw-w64` and `wine-stable` (for testing). +cmake --build build -j4 -1. Fetch Windows binaries: - ```bash - ./scripts/fetch_win_deps.sh - ``` - -2. Build for Windows: - ```bash - ./scripts/build_win.sh - ``` - This will produce `build_win/demo64k_packed.exe`. +# Final stripped build +cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON +cmake --build build_final -j4 +``` -3. Run with Wine: - ```bash - ./scripts/run_win.sh - ``` +## Build Modes -# Building the Project with Xcode +| Mode | Flags | Use Case | +|------|-------|----------| +| Debug | `-DCMAKE_BUILD_TYPE=Debug` | Development, full error checking + debug features | +| STRIP_ALL | `-DDEMO_STRIP_ALL=ON` | Release candidate, full error checking, no debug features (~64k target) | +| FINAL_STRIP | `-DDEMO_FINAL_STRIP=ON` | Final release, no error checking, absolute minimum size | -This document provides instructions for building the 64k Demo project using Xcode on macOS. +## Dependencies -## Prerequisites +Install via Homebrew (macOS): +```bash +brew install wgpu-native +``` -- **Xcode:** Ensure you have Xcode installed. You can download it from the Mac App Store. -- **CMake:** This project uses CMake as its build system. Ensure CMake is installed on your system. +Or use project init script: +```bash +./scripts/project_init.sh +``` -## Build Steps +Required libraries: +- **miniaudio** (single header, auto-fetched by init script) +- **wgpu-native** (WebGPU implementation) +- **glfw3webgpu** (GLFW surface helper, auto-fetched) +- **UPX** (executable packer, optional for Linux/Windows) -1. **Open Terminal:** Navigate to the root directory of the project (`/Users/skal/demo`). +## Windows Cross-Compilation (macOS) -2. **Create Build Directory:** It is recommended to build out-of-source. Create a build directory: - ```bash - mkdir build - cd build - ``` +Requires `mingw-w64` and `wine-stable`. -3. **Configure with CMake for Xcode:** Generate the Xcode project files using CMake. For Xcode, you typically specify the generator as `Xcode`. - ```bash - cmake .. -G "Xcode" - ``` - This command will configure the project and create an `.xcodeproj` file within the `build` directory. +```bash +# Fetch Windows dependencies +./scripts/fetch_win_deps.sh -4. **Open Xcode Project:** Open the generated `.xcodeproj` file in Xcode: - ```bash - open YourProjectName.xcodeproj - ``` - (Replace `YourProjectName.xcodeproj` with the actual name of the generated project file, usually `demo.xcodeproj` or similar). +# Build for Windows +./scripts/build_win.sh -5. **Build and Run in Xcode:** - * Select your desired target (e.g., `demo64k`, `test_3d_render`). - * Choose a build scheme (e.g., `Debug` or `Release`) - * Click the "Run" button (or press `Cmd+R`) to build and launch the application. +# Test with Wine +./scripts/run_win.sh +``` -## GPU Performance Capture (Future Task) +Produces `build_win/demo64k_packed.exe`. -To enable future GPU performance analysis, a conditional compilation macro `ENABLE_GPU_PERF_CAPTURE` can be defined. This can be controlled via CMake build types or specific flags when configuring the project: +## Xcode Build (macOS) ```bash -# Example of defining the macro via CMake (add to CMakeLists.txt) -# if (MY_GPU_PERF_BUILD) -# target_compile_definitions(demo64k PRIVATE ENABLE_GPU_PERF_CAPTURE=1) -# endif +cmake -S . -B build -G "Xcode" +open build/demo.xcodeproj ``` -This macro can then be used within the code (e.g., in `gpu.h` or `platform.h`) to conditionally compile performance monitoring or capture code. - -## Shader Performance Analysis Task - -For detailed shader performance analysis on macOS, **Xcode's Metal debugger** is the recommended tool. A task has been added to `TODO.md` to integrate this into our workflow for future optimization efforts. +Use Xcode Metal debugger for shader performance analysis. -- cgit v1.2.3