Wheel Staging Area Internals#

Understanding the staging area helps when debugging import failures or building custom wheels.

When CMake configures the project with ENABLE_PYTHON_FDB_INTERFACE=ON, it creates build/pyfdb-python-package-staging/ with the following layout:

pyfdb-python-package-staging/
├── pyfdb/                         ← symlink → fdb/src/pyfdb/   (live source)
│   ├── bindings/
│   │   ├── __init__.py            ← from src/pyfdb/bindings/ (via symlink)
│   │   └── _pyfdb_bindings.cpython-<tag>.so   ← compiled extension
│   └── ...
├── setup.py                       ← generated from cmake/pyfdb_setup.py.in
├── setup.cfg                      ← generated from cmake/pyfdb_setup.cfg.in
├── README.md                      ← copied at build time
└── LICENSE                        ← copied at build time

Key points:

  • The pyfdb/ symlink means edits to the Python source in the repository take effect immediately after an editable install — no rebuild or reinstall needed.

  • pyfdb/bindings/ is a proper subpackage of pyfdb (it has an __init__.py), importable as pyfdb.bindings. It is not re-exported by pyfdb/__init__.py — it is an internal extension for developers who need the raw C++ types directly.

  • The .so is regenerated by Ninja whenever bindings.cc or its dependencies change. Re-running ninja is sufficient — no pip install is required after a C++ rebuild.