DunePythonInstallPackage
------------------------

Helpers for configuring and installing Python packages from the DUNE build
system.

.. cmake:command:: dune_python_configure_dependencies

  Install dependencies of a Python package at configure time.

  .. code-block:: cmake

    dune_python_configure_dependencies(
      PATH <path>
      [RESULT <var>]
      [INSTALL_CONCRETE_DEPENDENCIES <value>]
    )

  ``PATH``
    Path to the package source directory containing a valid ``setup.py`` file.
    Relative paths are evaluated with respect to ``CMAKE_CURRENT_SOURCE_DIR``.

  ``RESULT``
    Variable receiving the result of dependency configuration. A non-zero value
    indicates failure.

  ``INSTALL_CONCRETE_DEPENDENCIES``
    Force installation of the concrete dependencies listed in
    ``requirements.txt``.

  Dependencies are extracted from ``setup.py`` and ``requirements.txt``.
  Failure during dependency installation does not trigger a fatal CMake error,
  but it is reflected in ``RESULT``.

.. cmake:command:: dune_link_dune_py

  Generate metadata that lets an installed Python package interact with
  dune-py.

  .. code-block:: cmake

    dune_link_dune_py(
      PATH <path>
      INSTALL_TARGET <target>
      [CMAKE_METADATA_FLAGS <flags...>]
    )

  ``PATH``
    Absolute path to the Python package source tree where metadata should be
    generated.

  ``INSTALL_TARGET``
    Name of the target that generates the package metadata and triggers dune-py
    module configuration during installation.

  ``CMAKE_METADATA_FLAGS``
    Extra CMake flags written into the metadata file as ``flag:=value`` pairs.

  The generated metadata is installed together with the package and is used by
  the Python bindings to transport CMake-side build information into the
  installed package. A module ``dune-mymodule`` providing the package
  ``dune.mymodule`` would typically use
  ``dune/mymodule/metadata.cmake`` as the metadata file path.

.. cmake:command:: dune_python_configure_package

  Configure installation of a Python package at configure time.

  .. code-block:: cmake

    dune_python_configure_package(
      PATH <path>
      [INSTALL_TARGET <target>]
      [RESULT <var>]
      [ADDITIONAL_PIP_PARAMS <param>...]
      [INSTALL_CONCRETE_DEPENDENCIES]
    )

  ``PATH``
    Path to the Python package. Relative paths are evaluated with respect to
    ``CMAKE_CURRENT_SOURCE_DIR``.

  ``INSTALL_TARGET``
    Target that installs the package into the configured install directory.

  ``RESULT``
    Variable receiving the result of package configuration.

  ``ADDITIONAL_PIP_PARAMS``
    Extra arguments appended to any ``pip install`` invocation.

  ``INSTALL_CONCRETE_DEPENDENCIES``
    Forwarded to :cmake:command:`dune_python_configure_dependencies()`.

  The package is installed to ``DUNE_PYTHON_INSTALL_LOCATION`` during
  ``make install_python`` and ``make install``. A wheel is also placed into the
  DUNE wheelhouse so installed and non-installed module stacks can be mixed.

.. cmake:command:: dune_python_configure_bindings

  Convenience wrapper for configuring a Python package together with its
  dune-py metadata.

  .. code-block:: cmake

    dune_python_configure_bindings(
      PATH <path>
      [PACKAGENAME <name>]
      [ADDITIONAL_PIP_PARAMS <param>...]
      [CMAKE_METADATA_FLAGS <flags...>]
      [REQUIRED]
    )

  ``PATH``
    Relative path to the Python package source directory.

  ``PACKAGENAME``
    Name of the Python package.

  ``ADDITIONAL_PIP_PARAMS``
    Extra arguments appended to any ``pip install`` invocation.

  ``CMAKE_METADATA_FLAGS``
    Extra metadata flags written into the generated metadata file.

  ``REQUIRED``
    Fail with a CMake error if the package cannot be installed. By default only
    a warning is emitted.

  This command combines
  :cmake:command:`dune_python_configure_dependencies()`,
  :cmake:command:`dune_link_dune_py()`, and
  :cmake:command:`dune_python_configure_package()`. It also ensures that a
  ``setup.py`` file is available, either directly from the source tree, from a
  configured ``setup.py.in``, or from a generated template.

.. cmake:variable:: DUNE_PYTHON_ADDITIONAL_PIP_PARAMS

  Additional pip flags used globally for the current build. This can be used,
  for example, to point pip to alternative package indices in restricted
  environments.