6. The Wrapper Script¶

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/lldb, 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 default code, and then code based on the command line parameters (see -f and -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.

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.

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¶: Do not print messages from the wrapper script and the include() function. This does not influence the library.

MOD_PYTHON¶: Set this environment variable to the executable to start in non-interactive mode. If not set it will use a Python interpreter appropriate for the compiled bindings. This interpreter was found during configuration of the build system. When executing the wrapper script the exact command can be seen in the output.

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 it will fall back to standard Python interpreter as if -i was not given.

Warning

The standard ipython3 may not be appropriate for the compiled bindings, which may result in a crash during import of the mod module.

MOD_DEBUGGER¶: Set this environmentt variable to the executable to use with --debug is given and --memcheck is not given. When not set the string gdb --args or lldb -- is used, if GDB or LLDB is available.

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 a debugger (e.g. GDB or LLDB) can be attached.

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

--debug¶

Run the interpreter through GDB, or LLDB. If MOD_DEBUGGER it set, then this string is prepended to form a complete command, otherwise if gdb is available, then gdb --args is preprended, otherwise if lldb``is available, then ``lldb -- is prepended, otherwise the script stops with an error.

If --memcheck is given as well, then it takes preceedence, but it will add extra flags to start a gdbserver. This will make Valgrind wait for a debugger to be attached. Valgrind will print instructions for how to attach GDB.

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.