diff options
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. |