Python bindings for dune-common
===============================

The DUNE Python bindings compile C++ extension modules just in time, the
first time a Python object needs them. These modules are built with CMake
inside a helper DUNE module called dune-py and cached there.

Upstream expects the bindings to be used from a virtual environment. With
the system packages that looks like this:

  python3 -m venv --system-site-packages ~/venv
  . ~/venv/bin/activate
  python3 -c 'from dune.common import FieldVector; print(FieldVector([1, 2]))'

Location of dune-py: $DUNE_PY_DIR/dune-py if DUNE_PY_DIR is set, otherwise
<venv>/.cache/dune-py inside an active virtual environment, otherwise
~/.cache/dune-py. It is safe to remove this directory; it is regenerated
on the next use.

The JIT modules are compiled with the compiler and flags dune-common was
built with (recorded in /usr/lib/python3/dist-packages/dune/data/dune-common.cmake).
If CXXFLAGS is set, upstream's compiler launcher uses it instead of these
flags for modules compiled from then on, e.g. CXXFLAGS="-O3 -DNDEBUG".
Further CMake options for dune-py can be passed in DUNE_CMAKE_FLAGS.

The package depends on python3-dev, i.e. the headers of the default Python
version. To use the bindings with another supported Python 3 version, also
install the matching python3.X-dev package.

Unlike upstream's own setup, configuring dune-py never runs pip in the
active virtual environment (see debian/patches/dune-py-do-not-use-venv.patch).

Other DUNE modules
------------------

dune-py only reads the list of installed DUNE modules when it is
generated. After installing another python3-dune-* package, run

  python3 -m dune configure

once in every virtual environment (or for every DUNE_PY_DIR) where dune-py
already exists. The next use of the bindings then regenerates dune-py with
all installed modules.