cuber/AGENTS.md

AGENTS.md

Project Overview

cuber is a simple cube timer application.

Build System

• Generator: Ninja
• CMake minimum: 3.21
• C++ standard: C++23

Commands

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)
• East const (e.g. char const* not const char*)
• <> 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.