Next: Target options, Up: Compilation model options [Contents][Index]
-s grade--grade gradeSelect the compilation model. The grade should be a ‘.’ separated list in which the first element is a ‘base grade’, and each following element (if any) is a ‘grade modifier’.
The base grade specifies what target language to compile the Mercury program to, and if the compiler can do this in several different ways, selects one of those ways. The available base grades are the following.
This base grade calls for generating idiomatic C, which we call high-level C.
These base grades call for generating assembly-like C code, which we call low-level C. ‘none’ calls for generating standard C without using any GNU C extensions. ‘reg’ and ‘asm_fast’ both call for the use of GNU C’s extension for storing global variables in registers, while ‘asm_fast’ also calls for the use of two GNU C extensions that together allow direct gotos to labels in other functions, even in other modules. In general, the more GNU C extensions are used, the faster the program will be, but some platforms, compilers or compiler versions do not support specific extensions.
This base grade calls for generating C#.
This base grade calls for generating Java.
The default base grade is system dependent, but will be either ‘hlc’ or ‘asm_fast’, as these are the two fastest.
The grade modifiers may be given in any order. Each grade modifier sets one or more compilation model options. The available options each belong to a set of mutually exclusive alternatives governing a single aspect of the compilation model. The set of aspects and their alternatives are as follows. Note that not all grade modifiers are applicable to all grades (most apply only when targeting C), and not all grade modifiers are compatible with each other.
The default is no garbage collection beyond what the target language provides. C# and Java have their own builtin garbage collectors, but C does not. Since garbage collection is essential for all programs other than those with very short runtimes, base grades that target C are usually followed by the ‘.gc’ grade modifier, which calls for the use of the Boehm-Demers-Weiser conservative collector for C.
The default is no profiling. The grade modifier ‘.prof’ calls for gprof-style profiling; the grade modifier ‘.memprof’ calls for profiling of memory usage; while the grade modifier ‘.profdeep’ calls for deep profiling. See Profiling for an explanation of the differences between these forms of profiling, all of which are available only when targeting C.
The default is no trailing. Applications that need trailing should specify the grade modifier ‘.tr’. Trailing is available only when targeting C.
(A trail is a data structure that records changes to a mutable data store during normal execution so that each of those changes can be unwound (undone) when execution backtracks to the point in time before it was made. Mercury normally needs a trail only when executing programs that use constraint solvers. While the act of posting a constraint in such a program is a declarative action, its implementation requires updating a constraint store.)
By default when targeting C, the Mercury ‘float’ type is implemented as an IEEE 754 double-precision floating point number, which occupies 64 bits of space. On platforms whose word size is 32 bits, users whose programs do not require double precision may improve memory consumption and speed by specifying the grade modifier ‘.spf’ (short for single-precision float), which calls for implementing all Mercury floats as IEEE 754 single-precision floating point numbers. Note that on 64 bit platforms, using single-precision floats definitely will not improve memory consumption, and will probably not improve speed. On the other hand, it may simplify the use of C APIs that exclusively use single precision floats.
For target languages other than C, the Mercury ‘float’ type is always implemented as a double-precision floating point number, and the ‘.spf’ modifier is not supported.
When generating low-level C, Mercury implements its own stacks (two of them). The default is to make each stack a fixed size (usually a relatively large size, though the size of each stack can be controlled using runtime options). We make the page(s) at the tops of the stacks inaccessible, so that a stack overflow, instead of accessing and overwriting memory effectively randomly, causes the operating system to send a signal to the program. If not caught and handled, this signal will abort the program, minimizing the damage.
However, for programs for which this is not acceptable, users can specify the ‘.stseg’ grade component. This calls for each stack to be composed of small memory segments chained together in a list. When there is no room in the current segment for a new stack frame, we simply allocate a new segment and add it to the list. This approach has higher overhead, since calls to, and returns from, procedures must execute more code, but it avoids imposing any limit on stack size other than the size of available memory.
When targeting anything other than low-level C, the stack is always managed by the implementation of the target language, so for them, the ‘.stseg’ modifier is neither relevant nor supported.
The default is to generate executables that do not support debugging. However, when generating low-level C code, specifying one of the grade modifiers ‘.debug’ and ‘.decldebug’ will cause the compiler to generate executables that can be debugged using the Mercury debugger ‘mdb’. The difference between them is that the declarative debugging aspects of ‘mdb’ will work only with ‘.decldebug’. The price of this is that ‘.decldebug’ results in significantly larger executable files.
The default is whatever thread support is provided by the target language. When targeting C, thread support can be enabled by specifying the grade modifier ‘.par’. When targeting low-level C, this also enables the use of the parallel conjunction operator ‘&’. Since Mercury implements parallel conjunctions only in low-level C grades with the ‘.par’ grade modifier, in every other situation, the compiler silently converts every occurrence of ‘&’ to a comma, the usual sequential conjunctions operator.
In low-level C grades with the grade modifier ‘.par’, users can enable support for ThreadScope-style thread profiling by also specifying the grade module ‘.threadscope’. The default is no support for thread profiling. Note that form of profiling is experimental, and it is not currently supported.
The default is no support for minimal model evaluation. When targeting low-level C, users can specify the grade modifier ‘.mm’, which enables support for minimal model tabled evaluation of procedures. The grade component ‘.mmsc’ is a synonym for ‘.mm’, standing for minimal model via stack copying, since the standard implementation works by copying stack segments. (The synonym exists because Mercury also has another implementation of minimal model tabling. This other implementation, which is incomplete and was only ever useful for experiments, is based on a completely different implementation technique.)
The default grade is system-dependent;
it is chosen at installation time by ‘configure’,
the auto-configuration script,
but can be overridden if desired
with the environment variable MERCURY_DEFAULT_GRADE.
On any given particular installation,
the Mercury runtime system and Mercury standard library
will be installed in only a subset of the possible grades;
you can find out which grades these are
by invoking the Mercury compiler
with the ‘--output-stdlib-grades’ option.
Attempting to use a grade which has not been installed
will result in an error at link time.
(The error message will typically be something like
‘ld: can't find library for -lmercury’.)
The tables below show the options that are selected by each base grade and grade modifier; they are followed by descriptions of those options.
Options implied.
--target c --high-level-code.
--target c --no-gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels.
--target c --gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels.
--target c --gcc-global-registers --gcc-nonlocal-gotos --asm-labels.
--target csharp --high-level-code.
--target java --high-level-code.
--gc boehm.
--profiling.
--memory-profiling.
--deep-profiling.
--use-trail.
--single-prec-float
--stack-segments
--debug.
--decl-debug.
--parallel.
--threadscope.
Next: Target options, Up: Compilation model options [Contents][Index]