Sara/clay
1
0
Fork 0
mirror of https://github.com/nicbarker/clay.git synced 2025-09-18 12:36:17 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improved by Claude.ai

Browse source
This commit is contained in:
Orwa Diraneyya 2025-08-11 13:14:16 +02:00
parent 76dab1290a
commit 0e82579926
No known key found for this signature in database
GPG key ID: 32848D26CC4A4324
1 changed files with 73 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

128
examples/README.md
View file

@ -1,93 +1,80 @@
# Building the Examples # 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) - **CMake** (version 3.25 or newer recommended)
- **C Compiler with WASM support** (GCC, Clang, or MSVC) - **C compiler with WebAssembly support** (GCC, Clang, or MSVC)
- **Specific SDKs or Libraries** for some examples: - **Platform-specific dependencies** for certain examples:
- [Playdate SDK](https://play.date/dev/) for Playdate 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
1. **Clone the repository:**
```sh ```sh
git clone https://github.com/nicbarker/clay.git git clone https://github.com/nicbarker/clay.git
cd clay cd clay
``` ```
--- 2. **Build all examples (except Playdate):**
## 3. Build All Examples (except Playdate)
To build all examples (except the Playdate example which is not built by default):
```sh ```sh
cmake -B cmake-build cmake -B cmake-build
cmake --build cmake-build cmake --build cmake-build
``` ```
--- ## Selective Building
## 4. Build Other Examples For more control over which examples to build, use these CMake options:
If you want more control over which examples you want to build, you can use the following `cmake` options, which can be combined together: | CMake Option | Description |
You can selectively build a subset of the examples:
| `cmake` Option | Explanation |
|---|---| |---|---|
| No options | Builds all examples except the Playdate examples | | (no options) | Builds all examples except Playdate |
| `-DCLAY_INCLUDE_ALL_EXAMPLES=OFF` | Does not build any examples unless told to through other options below | | `-DCLAY_INCLUDE_ALL_EXAMPLES=OFF` | Builds no examples unless specified |
| `-DCLAY_INCLUDE_DEMOS=ON` | Builds video demo and website | | `-DCLAY_INCLUDE_DEMOS=ON` | Builds video demo and website |
| `-DCLAY_INCLUDE_CPP_EXAMPLE=ON` | Builds C++ example | | `-DCLAY_INCLUDE_CPP_EXAMPLE=ON` | Builds C++ example |
| `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` | Builds raylib examples | | `-DCLAY_INCLUDE_RAYLIB_EXAMPLES=ON` | Builds Raylib examples |
| `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` | Builds SDL2 examples | | `-DCLAY_INCLUDE_SDL2_EXAMPLES=ON` | Builds SDL2 examples |
| `-DCLAY_INCLUDE_SDL3_EXAMPLES=ON` | Builds SDL3 examples | | `-DCLAY_INCLUDE_SDL3_EXAMPLES=ON` | Builds SDL3 examples |
| `-DCLAY_INCLUDE_WIN32_GDI_EXAMPLES=ON` | Builds Win32 GDI examples | | `-DCLAY_INCLUDE_WIN32_GDI_EXAMPLES=ON` | Builds Win32 GDI examples |
| `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` | Builds Sokol examples | | `-DCLAY_INCLUDE_SOKOL_EXAMPLES=ON` | Builds Sokol examples |
| `-DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON` | Builds Playdate 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 -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_PLAYDATE_EXAMPLES=ON -B cmake-build
cmake --build 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` | | Raylib 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` | | SDL2 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` | | Sokol 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` | | Terminal demos only | `cmake -DCLAY_INCLUDE_ALL_EXAMPLES=OFF -DCLAY_INCLUDE_DEMOS=ON -B cmake-build` |
> [!IMPORTANT] ## Platform-Specific Instructions
> The Playdate examples equires the [Playdate SDK](https://play.date/dev/) to be installed.
--- ### Playdate Examples
## 5. Playdate Examples > **Note:** The [Playdate SDK](https://play.date/dev/) must be installed before building Playdate examples.
The output `.pdx` file will be at:
The compiled `.pdx` file will be located at:
``` ```
cmake-build/examples/playdate-project-example/clay_playdate_example.pdx cmake-build/examples/playdate-project-example/clay_playdate_example.pdx
``` ```
You can open this file using the Playdate simulator. Open this file in the Playdate simulator to run it.
### Building for the Playdate Hardware
Replace `/path/to/PlaydateSDK` with your Playdate SDK path:
**Building for Playdate hardware:**
```sh ```sh
cmake -DTOOLCHAIN=armgcc \ cmake -DTOOLCHAIN=armgcc \
-DCMAKE_TOOLCHAIN_FILE=/path/to/PlaydateSDK/C_API/buildsupport/arm.cmake \ -DCMAKE_TOOLCHAIN_FILE=/path/to/PlaydateSDK/C_API/buildsupport/arm.cmake \
@ -97,50 +84,57 @@ cmake -DTOOLCHAIN=armgcc \
cmake --build cmake-release-playdate 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 ```sh
cd examples/clay-official-website cd examples/clay-official-website
./build.sh ./build.sh
``` ```
> [!WARNING] **macOS WebAssembly Build Issues:**
> If you are on Mac OS X and see the following error: If you encounter this error on macOS:
> ```logs ```
> error: unable to create target: 'No available targets are compatible with triple "wasm32"' 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: **Solution 1 (Recommended):** Install LLVM via Homebrew:
```sh
brew install llvm
export PATH="/opt/homebrew/bin:$PATH"
```
**Solution 2:** Use Emscripten (requires modifying the `build.sh` script):
```sh
brew install emscripten
```
**Viewing the WebAssembly example:**
1. The build creates files in `./build/clay/`:
- `build/clay/index.html` - `build/clay/index.html`
- `build/clay/index.wasm` - `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. 2. Serve the `build` folder using a web server (the files won't work when opened directly in a browser)
Using vscode, open the `build` directory in own's workspace then use the Live Preview extension. 3. Navigate to `index.html` in your browser
--- **Using VS Code:** Open the `build` directory and use the Live Preview extension to serve the files.
## 7. Running Examples ## Running Examples
After building, the examples can be found in their respective subfolders within the output folder `cmake-build/examples`: After building, find executables in their respective subfolders within `cmake-build/examples`:
```sh ```sh
./cmake-build/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. If an executable is missing, run `make` in the respective example subfolder.
--- ## Additional Notes
## Note - Dependencies like Raylib, Sokol, stb, and termbox2 are automatically fetched by CMake
- For example-specific instructions, check the README files in individual `examples/` folders
- Many examples automatically fetch dependencies using CMake's `FetchContent` – no manual installs needed for Raylib, Sokol, stb, or termbox2. - Most examples work out of the box once built, with no additional setup required
- For example-specific instructions, check the README files inside each `examples/` folder.
---