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