docs: Merge Xcode build instructions and GPU performance capture details into BUILD.md

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/BUILD.md b/doc/BUILD.md
index 3a581b1..e78aa91 100644
--- a/doc/BUILD.md
+++ b/doc/BUILD.md
@@ -27,3 +27,56 @@ Requires `mingw-w64` and `wine-stable` (for testing).
    ```bash
    ./scripts/run_win.sh
    ```
+
+# Building the Project with Xcode
+
+This document provides instructions for building the 64k Demo project using Xcode on macOS.
+
+## Prerequisites
+
+- **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.
+
+## Build Steps
+
+1.  **Open Terminal:** Navigate to the root directory of the project (`/Users/skal/demo`).
+
+2.  **Create Build Directory:** It is recommended to build out-of-source. Create a build directory:
+    ```bash
+    mkdir build
+    cd build
+    ```
+
+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.
+
+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).
+
+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.
+
+## GPU Performance Capture (Future Task)
+
+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:
+
+```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
+```
+
+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.