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