# AGENTS.md

## Project Overview

`cuber` is a simple cube timer application.

## Build System

- **Generator:** Ninja
- **CMake minimum:** 3.21
- **C++ standard:** C++23

### Commands

  ```sh
  cmake -S . -B build -GNinja
  ninja -C build
  ./build/cuber
  ```

### Dependencies

Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
These scripts use `FetchContent` under the hood to download and build
libraries automatically. They are shared with the `nerv` project.

To add a new dependency:

1. Copy the corresponding `Find<name>.cmake` from `nerv/deps/`
2. Add `find_package(<name> REQUIRED)` to `CMakeLists.txt`
3. Link with `<name>::<name>` in `target_link_libraries()`

### CMake Module Path

`deps/` is added to `CMAKE_MODULE_PATH` so `find_package()` resolves
to the custom scripts instead of system-installed packages.

## Coding Conventions

- **Language:** C++23
- **Trailing return type** for function signatures
- **4-space indentation**
- **No semicolons after closing braces** for namespaces/classes
- `auto` for obvious types (e.g. `auto main(...) -> int`)
- `<>` includes only for system headers (std, OS, etc.)
- `""` includes for third-party dependencies (e.g. `fmt`, `nlohmann/json`)
- **Naming:** `snake_case` for variables, functions, and classes
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
- Include order:
  1. C++ standard library headers (`<chrono>`, `<vector>`, etc.)
  2. *(blank line)*
  3. C standard library headers (`<stdlib.h>`, `<string.h>`, etc.)
  4. *(blank line)*
  5. OS-specific headers (Windows API, POSIX, etc.)
  6. *(blank line)*
  7. Third-party dependencies (`"fmt/core.h"`, etc.)
  8. *(blank line)*
  9. Local/project headers

## Shell Scripts

- Always use `#!/bin/sh` shebang for shell scripts
- Scripts must be POSIX compliant (no bashisms)
- When providing commands to users:
  - Windows/PowerShell: use `` ` `` for line continuation
  - Unix/Linux/macOS: use `\` for line continuation

## Commit Messages

- Follow the 50/72 rule:
  - Subject line: max 50 characters
  - Body lines: wrapped at 72 characters
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`, etc.)
- Separate subject from body with a blank line

Example:

  ```
  feat: add stopwatch timer

  Replace Hello World with a live stopwatch that prints elapsed time
  in HH:MM:SS.mmm format, updating every 10ms with color output.
  ```

## Source Layout

```
cuber/
  CMakeLists.txt      # Build configuration
  cuber.cpp           # Entry point
  cbt/                # Project namespace
    opengl/           # OpenGL abstraction layer
      context.hpp     # OpenGL context RAII wrapper
      context.cpp     # Context implementation
      buffer.hpp      # Buffer resource (VBO, EBO, UBO, SSBO)
      buffer.cpp      # Buffer implementation
      texture.hpp     # Texture resource
      texture.cpp     # Texture implementation
      descriptor.hpp  # Descriptor set (Vulkan-style binding)
      descriptor.cpp  # Descriptor implementation
  deps/               # Custom Find*.cmake scripts
    Findfmt.cmake     # fmt library
```

## Platform Support

The `nerv` project supports Windows, Linux, Emscripten, and Android via
`Platform.cmake` and `Flags.cmake`. These can be added to `cuber/deps/`
when cross-platform support is needed.