diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-09 10:43:11 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-09 10:43:11 +0100 |
| commit | 70c64867baa30c83334559d3023153dfe3f9ff79 (patch) | |
| tree | fa1353eca8f32334286aa4a9fc9c9461a5e56d8b /doc/BUILD.md | |
| parent | e952a9d0866a5a2a5f9da72ccbb40e2184da8a6f (diff) | |
docs: Simplify all design docs (50% reduction, 1687 lines removed)
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.
Diffstat (limited to 'doc/BUILD.md')
| -rw-r--r-- | doc/BUILD.md | 105 |
1 files changed, 46 insertions, 59 deletions
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. |
