6. The Wrapper Script (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.

  1. Clear the folder out/. If it does not exist, if will be created. All printing functions in libMØD assumes out/ is created.

  2. Create an input Python script (out/input) with some default code, and then code based on the command line parameters (see -f and -e).

  3. Run the Python interpreter on the input script, optionally through debugging tools.

  4. If the exit code of the executable is not 0, exit with that exit code.

  5. If PostMØD is not selected to be run, exit with code 0.

  6. Run PostMØD and exit with its exit code.

6.1. Usage

mod [options]

6.1.1. Meta Options

--help, -h

Shows the help output of the script.

--version, -v

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

6.1.2. Input Options

-f <filename>

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

-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.

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.

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 getAvailableILPSolvers()/getAvailableILPSolvers().

6.1.3. Execution Customization

-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 MOD_PYTHON and MOD_IPYTHON.

-q

Use quiet mode. Certain messages are not printed.

MOD_PYTHON

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

MOD_IPYTHON

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

6.1.4. Post-processing Options

--nopost

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

-j <N>

Give -j <N> to PostMØD (if executed).

clean

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

6.1.5. Debugging Options

--profile

Run the interpreter through Valgrind with --tool=callgrind. This option takes precedence over the memcheck option.

--memcheck

Run the interpreter through Valgrind 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.

--vgArgs <args>

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

--debug

Run the interpreter through GDB. If --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

6.2. 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 Creating a Python Extension)

  • import mod and from mod import *

  • Defining the following function both in global scope and in the mod module.

    mod.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 prefixFilename(), pushFilePrefix(), and popFilePrefix().

    Parameters

    • fName (str) – the file to be included.

    • checkDup (bool) – check if the file has already been included before (with putDup=True)

    • putDup (bool) – remember that this file has been included in subsequent calls.

    • skipDup (bool) – skip inclusion instead of exiting if the file has already been included before (with putDup=True)

6.3. 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 preamble. The plugin specification file must be placed in a directory that is also mentioned in the following environment variable.

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.