Developer Guide

This chapter is for contributors working on Blackchirp’s source tree. It covers the build system, the conventions that hold the C++ code, Python code, and documentation prose together, the C++ application architecture and threading layout, the cross-manager experiment lifecycle, the data-flow pipelines for FTMW and LIF acquisition, the persistence model, the standalone Python analysis module, and the recipes that walk through adding a new driver, a new hardware type, or a new experiment mode.

The chapter has three audiences, served by different sets of pages:

• C++ application contributors are the primary audience. Strong C++ and Qt6 skills (QObject, signal/slot, QThread, QtConcurrent, QSettings, the metaobject system) are assumed; Blackchirp-specific knowledge is not. The Architecture chapter and everything after it are C++-application-specific.

• Python module contributors working on python/blackchirp/ are served by Python Module — the module’s architecture, schema-versioning model, public API surface, and test layout. C++ knowledge is not required.

• Documentation contributors working on doc/source/ are served by Conventions and Style (prose style and the API reference contract) and Build System and Project Layout (the Sphinx + Doxygen + Breathe + nbsphinx pipeline).

Topics that require coordination across multiple files or subsystems are explained here. Topics that are confined to a single class belong in the API reference (or, for Python, on the per-class page under Python Module); topics about operating the program belong in the User Guide.

Pages in this chapter assume the API reference is available alongside them. Where a topic touches a class with its own API page, the developer guide provides a brief orientation and cross-links the API page; the API page carries the per-method contract while this chapter carries the cross-system flow. The contract between source code, the generators that read it (Doxygen for C++, autodoc + napoleon for Python), and the Sphinx pages that surface them is documented in the API reference style section of Conventions and Style.

The pages of this chapter are grouped in the sidebar: Contributing (this overview, prose and API conventions, the build system, packaging, and the Python module), Architecture (the C++ application structure, experiment lifecycle, persistence, crash handling, and the generated API reference), Hardware Subsystem (configuration, runtime, the Python hardware bridge, and vendor libraries), Acquisition Pipelines (the FTMW and LIF data-flow paths), and Extending Blackchirp (the recipes for adding a driver, a hardware type, or an experiment mode).