Skip to content

AGENTS.md

Latest commit

 

History

History
50 lines (44 loc) · 3.4 KB

AGENTS.md

File metadata and controls

50 lines (44 loc) · 3.4 KB
Raw

TrenchBroom Coding Agent Guidance

Project structure

  • The project contains several applications under /app. The main application target is TrenchBroom.
  • Most code lives in libraries under /lib.
  • Each application target and library target has its own CMakeLists.txt file.
  • Shared CMake utilities are in /cmake.
  • Each library usually has a LibTest target for its tests, for example TbMdlLibTest.
  • Some libraries also have a TestUtilsLib target for shared test helpers, and some of those have a matching TestUtilsLibTest target.

Build and test

  • TrenchBroom uses CMake as its build system.
  • In Visual Studio Code, prefer CMake Tools for builds.
  • Build the narrowest relevant target instead of building the whole workspace when possible.
  • For library changes, prefer the corresponding LibTest target to validate the change.
  • Always build the relevant test target before running tests.
  • Tests use Catch2.
  • If VS Code test discovery is unavailable, run the built test executable directly from the build tree, for example build/lib/TbMdlLib/test/TbMdlLibTest.
  • Use --list-tests to discover available tests and Catch2 filters to run a focused subset.
  • Use Build.md for platform-specific setup and dependency details.

Code coverage

  • Enable coverage instrumentation: Pass -DTB_ENABLE_GCOV=1 for gcov-compatible coverage (works with GCC or Clang) or -DTB_ENABLE_LCOV=1 for LLVM source-based coverage (Clang only).
  • Generate coverage data:
    • For gcov: Build and run tests normally. .gcno and .gcda files are automatically generated in the build tree.
    • For LLVM/lcov: Run tests with LLVM_PROFILE_FILE=default.profraw <test-executable> to generate .profraw profile data.
  • Analyze coverage: Use coverage tools to identify uncovered code paths, untested branches, and low-coverage functions.
  • Guide test improvements: When reviewing or creating tests, examine coverage reports to identify and address gaps:
    • Suggest new tests for uncovered code paths or error conditions.
    • Improve existing tests to cover branch conditions not yet exercised.
    • Identify edge cases or exception handling that lack test coverage.
  • Reference coverage in commit messages: When submitting test improvements motivated by coverage analysis, mention that coverage-guided testing was used to identify gaps.

Test structure

  • For each compilation unit, tests are usually in one file named tst_.cpp.
  • Prefer one test case per class.
  • Prefer one section per member function.
  • For free functions, prefer one test case per file and one section per function.

Code style

  • Format changes with clang-format. The repository style is defined in /.clang-format.
  • Respect the existing include ordering rules from /.clang-format. In particular, Qt headers must come first.
  • Follow the surrounding file's style and patterns unless there is a clear reason not to.

Git History

  • Keep the git history as clean as possible.
  • Avoid unnecessary churn, including changing the same code multiple times in a branch when a cleaner edit is possible.
  • Prefer changes that read like a clean transformation from the original state to the desired result.
  • When creating a series of commits, keep each commit coherent, buildable, and with the relevant tests passing when practical.
  • When asked to write commit messages, explain why the change was made in the context of a feature or bug fix, not just what changed.