From 293a3819c48372dc26421058dea569898f68399f Mon Sep 17 00:00:00 2001 From: Orwa Diraneyya <107997002+diraneyya@users.noreply.github.com> Date: Mon, 11 Aug 2025 12:19:54 +0200 Subject: [PATCH 1/3] Added instructions for building examples The bulk of the instructions were generated using GitHub copilot which were tested and edited manually by me. --- examples/README.md | 132 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 examples/README.md diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..816c0ee --- /dev/null +++ b/examples/README.md @@ -0,0 +1,132 @@ +# Building the Examples + +This guide describes how to build and run the examples in this project. + +--- + +## 1. Prerequisites + +- **CMake** (3.25 or newer recommended) +- **C Compiler with Wasm32-target support** (GCC, Clang, or MSVC) +- **Specific SDKs or Libraries** for some examples: + - [Playdate SDK](https://play.date/dev/) for Playdate examples + - Raylib, Sokol, stb, termbox2: fetched automatically by CMake + +--- + +## 2. Clone the Repository + +```sh +git clone https://github.com/nicbarker/clay.git +cd clay +``` + +--- + +## 3. Build All Examples + +To build all examples (except Playdate by default): + +```sh +cmake -DCLAY_INCLUDE_ALL_EXAMPLES=ON -B cmake-build-debug +cmake --build cmake-build-debug +``` + +--- + +## 4. Build Specific Example Sets + +You can selectively enable examples: + +- **Raylib Examples:** + `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` +- **SDL2 Example:** + `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` +- **Sokol Examples:** + `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` +- **Terminal Examples:** + `-DCLAY_INCLUDE_DEMOS=ON` + +Example (for Raylib only): + +```sh +cmake -DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON -B cmake-build-raylib +cmake --build cmake-build-raylib +``` + +--- + +## 5. Building the Playdate Example + +**Requires the [Playdate SDK](https://play.date/dev/) to be installed.** + +To build for the Playdate simulator: + +```sh +cmake -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON -B cmake-build-playdate +cmake --build cmake-build-playdate +``` + +The output `.pdx` file will be: +``` +examples/playdate-project-example/clay_playdate_example.pdx +``` +You can open this file using the Playdate simulator. + +**To build for Playdate hardware:** +Replace `/path/to/PlaydateSDK` with your Playdate SDK path. + +```sh +cmake -DTOOLCHAIN=armgcc \ + -DCMAKE_TOOLCHAIN_FILE=/path/to/PlaydateSDK/C_API/buildsupport/arm.cmake \ + -DCLAY_INCLUDE_ALL_EXAMPLES=OFF \ + -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON \ + -B cmake-build-release +cmake --build cmake-build-release +``` + +--- + +## 6. Building the Web Example (WASM) + +To build the official website demo as a WebAssembly app: + +```sh +cd examples/clay-official-website +./build.sh +``` + +> [!WARNING] +> If you are on Mac OS X and see the following error: +> ```logs +> error: unable to create target: 'No available targets are compatible with triple "wasm32"' +> ``` +> ... then you may need to install `llvm` using homebrew and add it to your PATH, resulting in it being used instead of `clang` which comes bundled with Mac OS X (which does not support WASM). An alternative is using `emscripten` but this requires modifying the `build.sh` script. + +Resulting files are found in the `./build/clay` subfolder: +- `build/clay/index.html` +- `build/clay/index.wasm` + +In order to view the page correctly, you will need to serve the `build` folder via a webserver, and then navigate to `index.html` in a web browser. + +Using vscode, open the `build` directory in own's workspace then use the Live Preview extension. + +--- + +## 7. Running Examples + +After building, executables are found in `cmake-build-*` directories or in their respective subfolders. +Run them directly, e.g.: + +```sh +./cmake-build-debug/examples/introducing-clay-video-demo/clay_examples_introducing_clay_video_demo +``` + +--- + +## Note + +- Many examples automatically fetch dependencies using CMake's `FetchContent` – no manual installs needed for Raylib, Sokol, stb, or termbox2. +- For example-specific instructions, check the README files inside each `examples/` folder. + +--- From 76dab1290a2120e32a7e529f0b9abedc0b9ec062 Mon Sep 17 00:00:00 2001 From: Orwa Diraneyya <107997002+diraneyya@users.noreply.github.com> Date: Mon, 11 Aug 2025 12:42:05 +0200 Subject: [PATCH 2/3] Fixed a possible ambiguity --- examples/README.md | 94 ++++++++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 40 deletions(-) diff --git a/examples/README.md b/examples/README.md index 816c0ee..f55ce7b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -7,10 +7,10 @@ This guide describes how to build and run the examples in this project. ## 1. Prerequisites - **CMake** (3.25 or newer recommended) -- **C Compiler with Wasm32-target support** (GCC, Clang, or MSVC) +- **C Compiler with WASM support** (GCC, Clang, or MSVC) - **Specific SDKs or Libraries** for some examples: - [Playdate SDK](https://play.date/dev/) for Playdate examples - - Raylib, Sokol, stb, termbox2: fetched automatically by CMake + - Raylib, Sokol, stb, termbox2: which are fetched automatically by CMake --- @@ -23,73 +23,85 @@ cd clay --- -## 3. Build All Examples +## 3. Build All Examples (except Playdate) -To build all examples (except Playdate by default): +To build all examples (except the Playdate example which is not built by default): ```sh -cmake -DCLAY_INCLUDE_ALL_EXAMPLES=ON -B cmake-build-debug -cmake --build cmake-build-debug +cmake -B cmake-build +cmake --build cmake-build ``` --- -## 4. Build Specific Example Sets +## 4. Build Other Examples -You can selectively enable examples: +If you want more control over which examples you want to build, you can use the following `cmake` options, which can be combined together: -- **Raylib Examples:** - `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` -- **SDL2 Example:** - `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` -- **Sokol Examples:** - `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` -- **Terminal Examples:** - `-DCLAY_INCLUDE_DEMOS=ON` +You can selectively build a subset of the examples: -Example (for Raylib only): +| `cmake` Option | Explanation | +|---|---| +| No options | Builds all examples except the Playdate examples | +| `-DCLAY_INCLUDE_ALL_EXAMPLES=OFF` | Does not build any examples unless told to through other options below | +| `-DCLAY_INCLUDE_DEMOS=ON` | Builds video demo and website | +| `-DCLAY_INCLUDE_CPP_EXAMPLE=ON` | Builds C++ example | +| `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` | Builds raylib examples | +| `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` | Builds SDL 2 examples | +| `-DCLAY_INCLUDE_SDL3_EXAMPLES=ON` | Builds SDL 3 examples | +| `-DCLAY_INCLUDE_WIN32_GDI_EXAMPLES=ON` | Builds Win32 GDI examples | +| `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` | Builds Sokol examples | +| `-DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON` | Builds Playdate examples | -```sh -cmake -DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON -B cmake-build-raylib -cmake --build cmake-build-raylib +For example, to building the Playdate examples only we can use: + +```bash +cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON -B cmake-build +cmake --build cmake-build ``` +Alternatively, here are some cmake invocations to build a specific set of examples: + +| Build intention | `cmake` Options | +|---|---| +| Raylib Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON -B cmake-build` | +| SDL2 Example Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SDL2_EXAMPLES=ON -B cmake-build` | +| Sokol Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SOKOL_EXAMPLES=ON-B cmake-build` | +| Terminal Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_DEMOS=ON-B cmake-build` | + +> [!IMPORTANT] +> The Playdate examples equires the [Playdate SDK](https://play.date/dev/) to be installed. + --- -## 5. Building the Playdate Example +## 5. Playdate Examples -**Requires the [Playdate SDK](https://play.date/dev/) to be installed.** +The output `.pdx` file will be at: -To build for the Playdate simulator: - -```sh -cmake -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON -B cmake-build-playdate -cmake --build cmake-build-playdate +``` +cmake-build/examples/playdate-project-example/clay_playdate_example.pdx ``` -The output `.pdx` file will be: -``` -examples/playdate-project-example/clay_playdate_example.pdx -``` You can open this file using the Playdate simulator. -**To build for Playdate hardware:** -Replace `/path/to/PlaydateSDK` with your Playdate SDK path. +### Building for the Playdate Hardware + +Replace `/path/to/PlaydateSDK` with your Playdate SDK path: ```sh cmake -DTOOLCHAIN=armgcc \ -DCMAKE_TOOLCHAIN_FILE=/path/to/PlaydateSDK/C_API/buildsupport/arm.cmake \ -DCLAY_INCLUDE_ALL_EXAMPLES=OFF \ -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON \ - -B cmake-build-release -cmake --build cmake-build-release + -B cmake-release-playdate +cmake --build cmake-release-playdate ``` --- -## 6. Building the Web Example (WASM) +## 6. Web Example -To build the official website demo as a WebAssembly app: +To build the official website demo as a WebAssembly app, in order for you to be able to view it in the browser. An additional step is needed: ```sh cd examples/clay-official-website @@ -104,6 +116,7 @@ cd examples/clay-official-website > ... then you may need to install `llvm` using homebrew and add it to your PATH, resulting in it being used instead of `clang` which comes bundled with Mac OS X (which does not support WASM). An alternative is using `emscripten` but this requires modifying the `build.sh` script. Resulting files are found in the `./build/clay` subfolder: + - `build/clay/index.html` - `build/clay/index.wasm` @@ -115,13 +128,14 @@ Using vscode, open the `build` directory in own's workspace then use the Live Pr ## 7. Running Examples -After building, executables are found in `cmake-build-*` directories or in their respective subfolders. -Run them directly, e.g.: +After building, the examples can be found in their respective subfolders within the output folder `cmake-build/examples`: ```sh -./cmake-build-debug/examples/introducing-clay-video-demo/clay_examples_introducing_clay_video_demo +./cmake-build/examples/introducing-clay-video-demo/clay_examples_introducing_clay_video_demo ``` +If the executable is missing, run the command `make` in the respective subfolder. + --- ## Note From 0e82579926d681505ddafa87c841484183da3230 Mon Sep 17 00:00:00 2001 From: Orwa Diraneyya Date: Mon, 11 Aug 2025 13:14:16 +0200 Subject: [PATCH 3/3] Improved by Claude.ai --- examples/README.md | 152 ++++++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 79 deletions(-) diff --git a/examples/README.md b/examples/README.md index f55ce7b..6fe960e 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,93 +1,80 @@ # Building the Examples -This guide describes how to build and run the examples in this project. +This guide explains how to build and run the examples in this project. ---- +## Prerequisites -## 1. Prerequisites +Before building the examples, ensure you have: -- **CMake** (3.25 or newer recommended) -- **C Compiler with WASM support** (GCC, Clang, or MSVC) -- **Specific SDKs or Libraries** for some examples: +- **CMake** (version 3.25 or newer recommended) +- **C compiler with WebAssembly support** (GCC, Clang, or MSVC) +- **Platform-specific dependencies** for certain examples: - [Playdate SDK](https://play.date/dev/) for Playdate examples - - Raylib, Sokol, stb, termbox2: which are fetched automatically by CMake ---- +Most dependencies (Raylib, Sokol, stb, termbox2) are automatically downloaded by CMake. -## 2. Clone the Repository +## Quick Start -```sh -git clone https://github.com/nicbarker/clay.git -cd clay -``` +1. **Clone the repository:** + ```sh + git clone https://github.com/nicbarker/clay.git + cd clay + ``` ---- +2. **Build all examples (except Playdate):** + ```sh + cmake -B cmake-build + cmake --build cmake-build + ``` -## 3. Build All Examples (except Playdate) +## Selective Building -To build all examples (except the Playdate example which is not built by default): +For more control over which examples to build, use these CMake options: -```sh -cmake -B cmake-build -cmake --build cmake-build -``` - ---- - -## 4. Build Other Examples - -If you want more control over which examples you want to build, you can use the following `cmake` options, which can be combined together: - -You can selectively build a subset of the examples: - -| `cmake` Option | Explanation | +| CMake Option | Description | |---|---| -| No options | Builds all examples except the Playdate examples | -| `-DCLAY_INCLUDE_ALL_EXAMPLES=OFF` | Does not build any examples unless told to through other options below | +| (no options) | Builds all examples except Playdate | +| `-DCLAY_INCLUDE_ALL_EXAMPLES=OFF` | Builds no examples unless specified | | `-DCLAY_INCLUDE_DEMOS=ON` | Builds video demo and website | | `-DCLAY_INCLUDE_CPP_EXAMPLE=ON` | Builds C++ example | -| `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` | Builds raylib examples | -| `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` | Builds SDL 2 examples | -| `-DCLAY_INCLUDE_SDL3_EXAMPLES=ON` | Builds SDL 3 examples | +| `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` | Builds Raylib examples | +| `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` | Builds SDL2 examples | +| `-DCLAY_INCLUDE_SDL3_EXAMPLES=ON` | Builds SDL3 examples | | `-DCLAY_INCLUDE_WIN32_GDI_EXAMPLES=ON` | Builds Win32 GDI examples | | `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` | Builds Sokol examples | | `-DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON` | Builds Playdate examples | -For example, to building the Playdate examples only we can use: +### Example Commands -```bash +**Build only Playdate examples:** +```sh cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON -B cmake-build cmake --build cmake-build ``` -Alternatively, here are some cmake invocations to build a specific set of examples: +**Build specific example types:** -| Build intention | `cmake` Options | +| Example Type | Command | |---|---| -| Raylib Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON -B cmake-build` | -| SDL2 Example Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SDL2_EXAMPLES=ON -B cmake-build` | -| Sokol Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SOKOL_EXAMPLES=ON-B cmake-build` | -| Terminal Examples Only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_DEMOS=ON-B cmake-build` | +| Raylib only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON -B cmake-build` | +| SDL2 only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SDL2_EXAMPLES=ON -B cmake-build` | +| Sokol only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_SOKOL_EXAMPLES=ON -B cmake-build` | +| Terminal demos only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_DEMOS=ON -B cmake-build` | -> [!IMPORTANT] -> The Playdate examples equires the [Playdate SDK](https://play.date/dev/) to be installed. +## Platform-Specific Instructions ---- +### Playdate Examples -## 5. Playdate Examples - -The output `.pdx` file will be at: +> **Note:** The [Playdate SDK](https://play.date/dev/) must be installed before building Playdate examples. +The compiled `.pdx` file will be located at: ``` cmake-build/examples/playdate-project-example/clay_playdate_example.pdx ``` -You can open this file using the Playdate simulator. - -### Building for the Playdate Hardware - -Replace `/path/to/PlaydateSDK` with your Playdate SDK path: +Open this file in the Playdate simulator to run it. +**Building for Playdate hardware:** ```sh cmake -DTOOLCHAIN=armgcc \ -DCMAKE_TOOLCHAIN_FILE=/path/to/PlaydateSDK/C_API/buildsupport/arm.cmake \ @@ -97,50 +84,57 @@ cmake -DTOOLCHAIN=armgcc \ cmake --build cmake-release-playdate ``` ---- +Replace `/path/to/PlaydateSDK` with your actual Playdate SDK installation path. -## 6. Web Example +### WebAssembly Example -To build the official website demo as a WebAssembly app, in order for you to be able to view it in the browser. An additional step is needed: +To build the official website demo for browsers: ```sh cd examples/clay-official-website ./build.sh ``` -> [!WARNING] -> If you are on Mac OS X and see the following error: -> ```logs -> error: unable to create target: 'No available targets are compatible with triple "wasm32"' -> ``` -> ... then you may need to install `llvm` using homebrew and add it to your PATH, resulting in it being used instead of `clang` which comes bundled with Mac OS X (which does not support WASM). An alternative is using `emscripten` but this requires modifying the `build.sh` script. +**macOS WebAssembly Build Issues:** +If you encounter this error on macOS: +``` +error: unable to create target: 'No available targets are compatible with triple "wasm32"' +``` -Resulting files are found in the `./build/clay` subfolder: +**Solution 1 (Recommended):** Install LLVM via Homebrew: +```sh +brew install llvm +export PATH="/opt/homebrew/bin:$PATH" +``` -- `build/clay/index.html` -- `build/clay/index.wasm` +**Solution 2:** Use Emscripten (requires modifying the `build.sh` script): +```sh +brew install emscripten +``` -In order to view the page correctly, you will need to serve the `build` folder via a webserver, and then navigate to `index.html` in a web browser. +**Viewing the WebAssembly example:** +1. The build creates files in `./build/clay/`: + - `build/clay/index.html` + - `build/clay/index.wasm` -Using vscode, open the `build` directory in own's workspace then use the Live Preview extension. +2. Serve the `build` folder using a web server (the files won't work when opened directly in a browser) ---- +3. Navigate to `index.html` in your browser -## 7. Running Examples +**Using VS Code:** Open the `build` directory and use the Live Preview extension to serve the files. -After building, the examples can be found in their respective subfolders within the output folder `cmake-build/examples`: +## Running Examples + +After building, find executables in their respective subfolders within `cmake-build/examples`: ```sh ./cmake-build/examples/introducing-clay-video-demo/clay_examples_introducing_clay_video_demo ``` -If the executable is missing, run the command `make` in the respective subfolder. +If an executable is missing, run `make` in the respective example subfolder. ---- +## Additional Notes -## Note - -- Many examples automatically fetch dependencies using CMake's `FetchContent` – no manual installs needed for Raylib, Sokol, stb, or termbox2. -- For example-specific instructions, check the README files inside each `examples/` folder. - ---- +- Dependencies like Raylib, Sokol, stb, and termbox2 are automatically fetched by CMake +- For example-specific instructions, check the README files in individual `examples/` folders +- Most examples work out of the box once built, with no additional setup required \ No newline at end of file