fixmath: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

Fixmath is a header-only C++20 fixed-point arithmetic library. Public headers live in include/fixmath/; fixed.hpp is the main entry point, fixed_impl.inl and fixed_math.inl contain core operations, and the remaining .inl files provide traits, bit utilities, and platform-independent 128-bit helpers. Tests are consolidated in tests/unit_tests.cpp. The tests/CMakeLists.txt project downloads GoogleTest during configuration and builds the FIXMATH_unittests executable. GitHub Actions configuration is under .github/workflows/.

Build, Test, and Development Commands

Run commands from the repository root:

cmake -S tests -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure

The first command configures the test project and fetches GoogleTest, so network access is required on a clean build. The second compiles the C++20 tests. The final command runs all discovered GoogleTest cases and prints failure details. Use a separate build directory (for example, build-release) rather than adding generated files to the source tree.

Format all C++ sources and verify that no formatting changes remain before committing. In PowerShell:

$files = rg --files -g '*.hpp' -g '*.h' -g '*.inl' -g '*.cpp' -g '*.cc' -g '*.cxx'
clang-format -i $files
clang-format --dry-run --Werror $files

The repository .clang-format file is the source of truth. It targets clang-format 19 or a compatible newer version. Keep C and C++ source files encoded as UTF-8 with BOM. Whenever .clang-format changes, first ensure that C and C++ files contain no uncommitted behavioral changes, restore those files to HEAD, and then format the repository again. Do not layer a new formatting configuration over output produced by the previous configuration.

Coding Style & Naming Conventions

Match the surrounding C++ style: tabs for indentation, a maximum line length of 300 characters, braces on the same line as declarations, and snake_case for functions, variables, and implementation headers. Types use descriptive names such as fixed_policy; compile-time constants use UPPER_SNAKE_CASE. Internal helpers currently use the _fm_ prefix. Keep public declarations in .hpp files and template implementations in .inl files. Preserve the MPL 2.0 notice at the top of source files. Use .clang-format for automatic formatting and minimize unrelated changes.