.. default-domain:: py
.. py:currentmodule:: mod
.. cpp:namespace:: mod

.. _mod-wrapper:

****************************
The Wrapper Script (``mod``)
****************************

.. program:: mod

The script ``mod`` is a convenience script primarily for starting the Python
interpreter and after its exit execute PostMØD (the summary generator).
The execution can however be customised somewhat, e.g., by running the
interpreter through ``valgrind`` and/or ``gdb``, or switching the interpreter
into interactive mode.

The wrapper script does the following.

#. Clear the folder ``out/``. If it does not exist, if will be created.
   All printing functions in libMØD assumes ``out/`` is created.
#. Create an input Python script (``out/input``) with some
   :ref:`default code <mod-wrapper-preamble>`,
   and then code based on the command line parameters
   (see :option:`-f` and :option:`-e`).
#. Run the Python interpreter on the input script,
   optionally through debugging tools.
#. If the exit code of the executable is not 0, exit with that exit code.
#. If PostMØD is not selected to be run, exit with code 0.
#. Run PostMØD and exit with its exit code.


Usage
#####

.. code-block:: bash

  mod [options]

Meta Options
============

.. option:: --help, -h

  Shows the help output of the script.

.. option:: --version, -v

  Print the version of MØD and exit
  (the version is always printed in the start).

Input Options
=============

.. option:: -f <filename>

  Append ``include("filename")`` to the input script (see :py:func:`include`).
  This option can be repeated to execute multiple files in sequence.

.. option:: -e <code>

  Append the given code (and a line break) to the input script.
  This option can be repeated to execute multiple code snippets in sequence.

.. envvar:: MOD_NO_DEPRECATED

  When this environment variable is set to a non-empty string, then the string
  ``config.common.ignoreDeprecation = False`` is executed first.
  This can be used to force errors when scripts use deprecated functionality.

.. envvar:: MOD_ILP_SOLVER

  When this environment varaible is set to a non-empty string,
  then the string ``config.ilp.solver = "ilpSolver"`` where ``ilpSolver`` is
  the value of the this environment variable.
  Whenever the ``default`` solver is requested, this one will be selected.
  See also
  :cpp:func:`getAvailableILPSolvers`/:py:func:`getAvailableILPSolvers`.

Execution Customization
=======================

.. option:: -i

  Use interactive mode for the Python interpreter (i.e., pass ``-i`` as
  additional argument to the interpreter), but disable the log. If ``ipython3``
  is available it will be used as interpreter, otherwise ``python3`` is used.
  See also :envvar:`MOD_PYTHON` and :envvar:`MOD_IPYTHON`.

.. option:: -q

  Use quiet mode. Certain messages are not printed.

.. envvar:: MOD_PYTHON

  Set this environment variable to the executable to start in non-interactive
  mode. If not set ``python3`` will be used.

.. envvar:: MOD_IPYTHON

  Set this environment variable to the executable to start in interactive
  mode (when :option:`-i` is given).
  If not set ``ipython3`` will be used, if it can be found, otherwise
  ``python3`` will be used.


Post-processing Options
=======================

.. option:: --nopost

  Do not run PostMØD after the selected executable has finished.

.. option:: -j <N>

  Give ``-j <N>`` to :ref:`PostMØD <mod_post>` (if executed).
  
.. option:: clean

  Do not run anything, but remove the ``out`` and ``summary`` folders.

Debugging Options
=================

.. option:: --profile

  Run the interpreter through `Valgrind <http://valgrind.org/>`_
  with ``--tool=callgrind``.
  This option takes precedence over the ``memcheck`` option.

.. option:: --memcheck

  Run the interpreter through `Valgrind <http://valgrind.org/>`_ with
  standard options for memory check.
  If ``--debug`` is given as well, the options ``--vgdb=yes --vgdb-error=0``
  are also given to ``valgrind`` such that ``gdb`` can be connected.

.. option:: --vgArgs <args>

  If either :option:`--profile` or :option:`--memcheck` is used, this inserts
  ``<args>`` as an extra argument for ``valgrind``.

.. option:: --debug

  Run the interpreter through `GDB <http://www.gnu.org/software/gdb/>`_.
  If :option:`--memcheck` is given as well, this is not the case, but GDB can
  then be connected to the process by the following steps:
  
  1. Run ``gdb python3`` (substitute ``python3`` for your Python interpreter).
  2. In the GDB prompt, run ``target remote | vgdb``
  3. In the GDB prompt, run ``continue``


.. _mod-wrapper-preamble:

PyMØD Preamble
##############

When the wrapper script creates the input script, it will start with a small
preamble of useful code before the user-defined code.
The complete code, including the preamble, given to the Python interpereter can
be seen in ``out/input`` after execution of the wrapper script.
The preamble has the following effects.

* Setting ``RTLD_GLOBAL`` in the interpreters ``dlopen`` flags (see
  :ref:`creatingPyMODExt`)
* ``import mod`` and ``from mod import *``
* Defining the following function both in global scope and in the ``mod``
  module.

  .. py:function:: include(fName, checkDup=True, putDup=True, skipDup=True) 
  
	Include the file ``fName`` in somewhat the same way that the ``#include``
	directive in the C/C++ preprocessor includes files. Paths are handled
	relatively using the functions :py:func:`prefixFilename`,
	:py:func:`pushFilePrefix`, and :py:func:`popFilePrefix`.
    
	:param str fName: the file to be included.
	:param bool checkDup: check if the file has already been included before
		(with ``putDup=True``)
	:param bool putDup: remember that this file has been included in subsequent
		calls.
	:param bool skipDup: skip inclusion instead of exiting if the file has
		already been included before (with ``putDup=True``)


Plugins (Loading of Additional Modules)
#######################################

It can be useful to always import additional modules when using MØD.
This can be achieved by writing a file in the following format::

  name: <module name>
  path: <Python import path>

When ``mod`` uses such a file, it will append ``<Python import path>`` to
``PYTHONPATH``,
and insert both ``import <module name>`` and ``from <module name> import *``
into the :ref:`preamble <mod-wrapper-preamble>`.
The plugin specification file must be placed in a directory that is also
mentioned in the following environment variable.

.. envvar:: MOD_PLUGIN_PATH

  A colon separated list of paths to search for plugins. Non-directory paths
  are skipped.
  All files (non-recursively) in each specified directory are checked for
  plugin information.