.. _DunePythonVirtualenv:

DunePythonVirtualenv
====================

.. cmake_module::

   This module manages the creation of virtual python environment during
   configuration. Execution of this module must be explicitly enabled by
   setting the variable :ref:`DUNE_PYTHON_VIRTUALENV_SETUP`. Note that some
   downstream modules will require you to set this variable. The purpose
   of this virtual environment is to be able to run python code from cmake
   in situations such as python-based code generation, running postprocessing
   in python during testing etc.

   Although designed for internal use, this virtualenv can also be manually
   inspected. A symlink to the activation script is placed in the top level
   build directory of all Dune modules in the stack. To directly execute a
   command in the virtualenv, you can use the script :code:`run-in-dune-env <command>`,
   which is also placed into every build directory.

   All packages installed with :ref:`dune_python_install_package` are automatically
   installed into the virtualenv.

   After execution of this module, the following are available for use in
   downstream modules:

   * :code:`DUNE_PYTHON_VIRTUALENV_PATH` The path of the virtual environment
   * :code:`DUNE_PYTHON_VIRTUALENV_EXECUTABLE` The python interpreter in the virtual environment

   By default, the created virtualenv resides in the first non-installed Dune module of
   the module stack (if no installation is performed: dune-common). Be aware
   that mixing installed and non-installed modules may result in a situation,
   where multiple such environments are created, although only one should.
   You can change this behavior by either specifying a fixed path for the virtualenv
   using :ref:`DUNE_PYTHON_VIRTUALENV_PATH` or by enabling
   :ref:`DUNE_PYTHON_EXTERNAL_VIRTUALENV_FOR_ABSOLUTE_BUILDDIR` if you are using an
   absolute build directory with dunecontrol. Note that this flag is enabled by default
   starting from Dune 2.7.

