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)
├── pyfdb_bindings/
│   ├── __init__.py          ← copied at build time by CMake POST_BUILD
│   └── 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 Python package (it has an __init__.py), allowing from pyfdb_bindings import pyfdb_bindings to resolve the compiled extension as a submodule. Without __init__.py the import would fall back to namespace-package semantics, which is fragile with tools like setuptools.

  • 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.