.. _DunePythonCommonMacros:

DunePythonCommonMacros
======================

.. cmake_module::

   This module is the main entry point for the python extension of the Dune cmake
   build system. It handles the detection of the python installation, defines installation
   rules for python packages in Dune modules and provides virtual environments to
   run python code from cmake.

   If you want to use Dune modules that provide Python functionality, you should be aware
   of some facts:

   * CMake looks for your python interpreter during configure. If you want to have it
     work with a virtual environment, you should activate your virtualenv before configure.
   * Each module has an additional target :code:`make install_python`, that installs python packages
     defined in the Dune module. You can customize the install location with
     :ref:`DUNE_PYTHON_INSTALL_LOCATION`. This is also included in :code:`make install`.
   * There is additional functionality, that automatically sets up a virtual environment
     at configure time, you can read more at :ref:`DunePythonVirtualenv`.

   After the module :code:`DunePythonCommonMacros` is run (which happens automatically when
   configuring dune-common) the following python-related variables will be set and available
   for use in downstream modules:

   * All variables set by :code:`FindPythonInterp.cmake` and :code:`FindPythonLibs.cmake`
   * :code:`DUNE_PYTHON_SYSTEM_IS_VIRTUALENV`: True if the given system interpreter resides in
     virtual environment.

   For documentation on how to customize the build process, check the input variable
   reference for any variables prefixed with :code:`DUNE_PYTHON`. To learn how to write build
   system code for Dune modules shipping python, have a look at the command reference for
   commands prefixed :code:`dune_python`.

