10.3 Environment variables affecting the Mercury runtime system

MERCURY_OPTIONS

A list of options for the Mercury runtime system, which gets linked into every Mercury program. The options given in this environment variable apply to every program; the options given in an environment variable whose name is of the form MERCURY_OPTIONS_progname apply only to programs named progname. Note that progname does not include the .exe extension on those systems (e.g. Windows) that use it. Options may also be set for a particular executable at compile time by passing ‘--runtime-flags’ options to the invocations of ‘ml’ and ‘c2init’ which create that executable. These options are processed first, followed by those in MERCURY_OPTIONS, with the options in MERCURY_OPTIONS_progname being processed last.

The Mercury runtime system accepts the following options.

-C size

Tells the runtime system to optimize the locations of the starts of the various data areas for a primary data cache of size kilobytes. The optimization consists of arranging the starts of the areas to differ as much as possible modulo this size.

-D debugger

Enables execution tracing of the program, via the internal debugger if debugger is ‘i’ and via the external debugger if debugger is ‘e’. (The mdb script works by including ‘-Di’ in MERCURY_OPTIONS.) The external debugger is not yet available.

-p

Disables profiling. This only has an effect if the executable was built in a profiling grade.

-P num

Tells the runtime system to create num threads for executing Mercury code if the program was built in a parallel low-level C grade. The Mercury runtime attempts to automatically determine this value if support is available from the operating system. If it cannot or support is unavailable it defaults to ‘1’.

--max-engines num

Tells the runtime system to allow a maximum of num POSIX threads, each with its own Mercury engine. This only affects programs in low-level C parallel grades.

--max-contexts-per-thread num

Tells the runtime system to create at most num contexts per POSIX thread for parallel execution. Each context created requires a set of stacks, setting this value too high can consume excess memory. This only has an effect if the executable was built in a low-level C parallel grade.

--thread-pinning

Request that the runtime system attempts to pin Mercury engines (POSIX threads) to CPU cores/hardware threads. This only has an effect if the executable was built in a parallel low-level C grade. This is disabled by default but may be enabled by default in the future.

-T time-method

If the executable was compiled in a grade that includes time profiling, this option specifies what time is counted in the profile. time-method must have one of the following values:

‘r’

Profile real (elapsed) time (using ITIMER_REAL).

‘p’

Profile user time plus system time (using ITIMER_PROF). This is the default.

‘v’

Profile user time (using ITIMER_VIRTUAL).

Currently, only the ‘-Tr’ option works on Cygwin; on that platform it is the default.

--heap-size size

Sets the size of the heap to size kilobytes.

--heap-size-kwords size

Sets the size of the heap to size kilobytes multiplied by the word size in bytes.

--detstack-size size

Sets the size of the det stack to size kilobytes.

--detstack-size-kwords size

Sets the size of the det stack to size kilobytes multiplied by the word size in bytes.

--nondetstack-size size

Sets the size of the nondet stack to size kilobytes.

--nondetstack-size-kwords size

Sets the size of the nondet stack to size kilobytes multiplied by the word size in bytes.

--small-detstack-size size

Sets the size of the det stack used for executing parallel conjunctions to size kilobytes. The regular det stack size must be equal or greater.

--small-detstack-size-kwords size

Sets the size of the det stack used for executing parallel conjunctions to size kilobytes multiplied by the word size in bytes. The regular det stack size must be equal or greater.

--small-nondetstack-size size

Sets the size of the nondet stack for executing parallel computations to size kilobytes. The regular nondet stack size must be equal or greater.

--small-nondetstack-size-kwords size

Sets the size of the nondet stack for executing parallel computations to size kilobytes multiplied by the word size in bytes. The regular nondet stack size must be equal or greater.

--solutions-heap-size size

Sets the size of the solutions heap to size kilobytes.

--solutions-heap-size-kwords size

Sets the size of the solutions heap to size kilobytes multiplied by the word size in bytes.

--trail-segment-size size

Sets the size of each trail segment to be size kilobytes. This option is ignored in grades that do not use a trail.

--trail-segment-size-kwords size

Set the size of each trail segment to be size kilobytes multiplied by the words size in bytes. This option is ignored in grades that do not use trail.

--genstack-size size

Sets the size of the generator stack to size kilobytes.

--genstack-size-kwords size

Sets the size of the generator stack to size kilobytes multiplied by the word size in bytes.

--cutstack-size size

Sets the size of the cut stack to size kilobytes.

--cutstack-size-kwords size

Sets the size of the cut stack to size kilobytes multiplied by the word size in bytes.

--pnegstack-size size

Sets the size of the pneg stack to size kilobytes.

--pnegstack-size-kwords size

Sets the size of the pneg stack to size kilobytes multiplied by the word size in bytes.

-i filename

--mdb-in filename

Read debugger input from the file or device specified by filename, rather than from standard input.

-o filename

--mdb-out filename

Print debugger output to the file or device specified by filename, rather than to standard output.

-e filename

--mdb-err filename

Print debugger error messages to the file or device specified by filename, rather than to standard error.

-m filename

--mdb-tty filename

Redirect all three debugger I/O streams — input, output, and error messages — to the file or device specified by filename.

--debug-threads

Output information to the standard error stream about the locking and unlocking occurring in each module which has been compiled with the C macro symbol ‘MR_DEBUG_THREADS’ defined.

--tabling-statistics

Prints statistics about tabling when the program terminates.

--mem-usage-report prefix

Print a report about the memory usage of the program when the program terminates. The report is printed to a new file named .mem_usage_reportN for the lowest value of N (up to 99) which doesn’t overwrite an existing file. Note that this capability is not supported on all operating systems.

--trace-count

When the program terminates, generate a trace counts file listing all the debugger events the program executed, if the program actually executed any debugger events. If MERCURY_OPTIONS includes the ‘--trace-count-output-file filename’ option, then the trace counts are put into the file filename. If MERCURY_OPTIONS includes the ‘--trace-count-summary-file basename’ option, then the trace counts are put either in the file basename (if it does not exist), or in basename.N for the lowest value of the integer N which doesn’t overwrite an existing file. (There is a limit on the value of N; see the option ‘--trace-count-summary-max’ below.) If neither option is specified, then the output will be written to a file with the prefix ‘.mercury_trace_counts’ and a unique suffix. Specifying both options is an error.

--coverage-test

Act as the ‘--trace-count’ option, except include all debugger events in the output, even the ones that were not executed.

--trace-count-if-exec prog

Act as the ‘--trace-count’ option, but only if the executable is named prog (excluding any .exe extension on Windows). This is to allow the collection of trace count information from only one Mercury program even if several Mercury programs are executed with the same setting of MERCURY_OPTIONS.

--coverage-test-if-exec prog

Act as the ‘--coverage-test’ option, but only if the executable is named prog (excluding any .exe extension on Windows). This is to allow the collection of coverage test information from only one Mercury program even if several Mercury programs are executed with the same setting of MERCURY_OPTIONS.

--trace-count-output-file filename

Documented alongside the ‘--trace-count’ option.

--trace-count-summary-file basename

Documented alongside the ‘--trace-count’ option.

--trace-count-summary-max N

If MERCURY_OPTIONS includes both the ‘--trace-count option’ (or one of the other options that imply ‘--trace-count’) and the ‘--trace-count-summary-file basename’ option, then the generated program will put the generated trace counts either in basename (if it does not exist), or in basename.N for the lowest value of the integer N which doesn’t overwrite an existing file. The ‘--trace-count-summary-max’ option specifies the maximum value of this N. When this maximum is reached, the program will invoke the ‘mtc_union’ program to summarize basename, basename.1, … basename.N into a single file basename, and delete the rest. By imposing a limit on the total number (and hence indirectly on the total size) of these trace count files, this mechanism allows the gathering of trace count information from a large number of program runs. The default maximum value of N is 20.

--deep-std-name

This option, which is meaningful only in deep profiling grades, asks deep profiling data to be stored in files named Deep.data and Deep.procrep. The default is that the runtime system puts such data into files whose names follow the pattern progname_on_date_at_time.data and progname_on_date_at_time.procrep respectively.

--boehm-gc-free-space-divisor N

This option sets the value of the free space divisor in the Boehm garbage collector to N. It is meaningful only when using the Boehm garbage collector. The default value is 3. Increasing its value will reduce heap space but increase collection time. See the Boehm GC documentation for details.

--boehm-gc-calc-time

This option enables code in the Boehm garbage collector to calculate the time spent doing garbage collection so far. Its only effect is to enable the ‘report_stats’ predicate in the ‘benchmarking’ module of the standard library to report this information.

--fp-rounding-mode mode

Set the rounding mode for floating point operations to mode. Recognised modes are ‘downward’, ‘upward’, ‘to_nearest’ and ‘toward_zero’. Exactly what modes are available and even if it is possible to set the rounding mode is system dependent.