11. Debugging and Troubleshooting

Build failures

  • confirm feature flags in CMake configure output

  • verify optional dependencies are either present or disabled

  • reconfigure from clean build directory when toggling major options

Python import/runtime issues

  • ensure PYTHONPATH=<build-dir>/bindings/python for local extension tests

  • verify native module _dtl was rebuilt for current Python version

  • check mismatch between wrapper assumptions and native signatures

C ABI runtime issues

  • validate handle magic/validity checks first

  • inspect backend availability decision branches

  • verify destroy paths for partial-initialization failures

Fortran interop issues

  • confirm bind(c) signatures match C ABI prototypes exactly

  • check c_ptr and scalar type compatibility

  • reproduce with fortran_basic_test before broader debugging

Documentation issues

  • Doxygen param warnings usually indicate signature/comment drift

  • missing toctree entries hide docs pages from site navigation

  • run docs build locally before opening PR

Escalation path for hard regressions

  1. isolate minimal reproducer

  2. identify last known good commit

  3. classify by layer (core, C ABI, Python, Fortran, docs)

  4. add regression test before final fix