\input texinfo @setfilename mercury_user_guide.info @settitle The Mercury User's Guide @ignore @ifinfo @format START-INFO-DIR-ENTRY * Mercury: (mercury). The Mercury User's Guide. END-INFO-DIR-ENTRY @end format @end ifinfo @end ignore @c @smallbook @c @cropmarks @finalout @setchapternewpage off @ifinfo This file documents the Mercury implementation. Copyright (C) 1995 University of Melbourne. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @ignore Permission is granted to process this file through Tex and print the results, provided the printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. @end ifinfo @titlepage @c @finalout @title The Mercury User's Guide @author Fergus Henderson @author Thomas Conway @author Zoltan Somogyi @author Peter Ross @page @vskip 0pt plus 1filll Copyright @copyright{} 1995 University of Melbourne. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. @end titlepage @page @ifinfo @node Top,,, (mercury) @top The Mercury User's Guide This guide describes the compilation environment of Mercury --- how to build and debug Mercury programs. @menu * Introduction:: General overview * Filenames:: File naming conventions * Using mc:: Compiling and linking programs with the Mercury compiler * Using Prolog:: Building and debugging Mercury programs with Prolog * Using Mmake:: ``Mercury Make'', a tool for building Mercury programs * Profiling:: The Mercury profiler @samp{mprof}, a tool for analyzing program performance * Invocation:: List of options for the Mercury compiler * Environment:: Environment variables used by the compiler and utilities * C compilers:: How to use a C compiler other than GNU C @end menu @end ifinfo @node Introduction @chapter Introduction This document describes the compilation environment of Mercury. It describes how to use @samp{mc}, the Mercury compiler; how to use @samp{mmake}, the ``Mercury make'' program, a tool built on top of ordinary or GNU make to simplify the handling of Mercury programs; and how to use Prolog to debug Mercury programs. We strongly recommend that programmers use @samp{mmake} rather than invoking @samp{mc} directly, because @samp{mmake} is generally easier to use and avoids unnecessary recompilation. Since the Mercury implementation is essentially a native-code compiler which happens to compile via GNU C, not an interpreter, debugging of compiled Mercury programs would require a dedicated Mercury debugger program - or at least some significant extensions to gdb. It would also require the Mercury compiler to arrange for the object code to contain suitable debugging information. Although it is possible to debug the intermediate C code, this is not productive, since the intermediate C code is extremely low-level and bears little resemblance to the source code. As an alternative, Mercury programmers may wish to use a Prolog system to execute their Mercury programs in order to gain access to this facility. The feasibility of this technique is dependent upon the program being written in the intersection of the Prolog and Mercury languages, which is possible because the two languages have almost the same syntax. The Mercury implementation allows you to run a Mercury program using NU-Prolog or SICStus Prolog (@pxref{Using Prolog}). @node Filenames @chapter File naming conventions Mercury source files should be named @file{*.m}. Each Mercury source file must contain a single Mercury module whose name should be the same as the filename without the @samp{.m} extension. Files ending in @file{.int} and @file{.int2} are interface files; these are generated automatically by the compiler, using the @samp{--make-interface} option. (The @file{.int} files are for direct dependencies, while the @file{.int2} files are a shorter version used for indirect dependencies.) Since the interface of a module changes less often than its implementation, the @file{.int} and @file{.int2} files will remain unchanged on many compilations. To avoid unnecessary recompilations of the clients of the module, the timestamps on the @file{.int} and @file{.int2} files are updated only if their contents change. A @file{.date} file associated with the module is used as a date stamp; it is used when deciding whether the interface files need to be regenerated. Files ending in @file{.d} are automatically-generated Makefile fragments which contain the dependencies for a module. Files ending in @file{.dep} are automatically-generated Makefile fragments which contain the rules for an entire program. In the source code for the Mercury runtime library, we use a few files ending in @file{.mod}; these are preprocessed using the perl script @samp{mod2c} to produce C files. Originally the Mercury compiler also produced @file{.mod} files, but now we compile directly to C. As usual, @file{.c} files are C source code, @file{.o} files are object code, @file{.no} files are NU-Prolog object code, and @file{.ql} files are SICStus Prolog object code. @node Using mc @chapter Using the Mercury compiler Following a long Unix tradition, the Mercury compiler is called @samp{mc}. Some of its options (e.g. @samp{-c}, @samp{-o}, and @samp{-I}) have a similar meaning to that in other Unix compilers. Arguments to @samp{mc} that name Mercury source files may omit the @samp{.m} suffix. To compile a program which consists of just a single module, use the command @example mc @var{module}.m @end example Unlike traditional Unix compilers, however, @samp{mc} will put the executable into a file called @file{@var{module}}, not @file{a.out}. To compile a module to object code without creating an executable, use the command @example mc -c @var{module}.m @end example @samp{mc} will put the object code into a file called @file{@var{module}.o}. It also will leave the intermediate C code in a file called @file{@var{module}.c}. Before you can compile a module, you must make the interface files for the modules that it imports (directly or indirectly). You can create the interface files for one or more modules using the command @example mc -i @var{module1}.m @var{module2}.m ... @end example Given that you have made all the interface files, one way to create an executable for a multi-module program is to compile all the modules at the same time using the command @example mc @var{module1}.m @var{module2}.m ... @end example This will by default put the resulting executable in @file{@var{module1}}, but you can use the @samp{-o @var{filename}} option to specify a different name for the output file, if you so desire. The other way to create an executable for a multi-module program is to compile each module separately using @samp{mc -c}, and then link the resulting object files together. The linking is a two stage process. First, you must create and compile an @emph{initialization file}, which is a C source file containing calls to automatically generated initialization functions contained in the C code of the modules of the program: @example c2init @var{module1}.c @var{module2}.c ... > @var{main_module}_init.c, mgnuc -c @var{main_module}_init.c @end example The @samp{c2init} command line must contain the name of the C file of every module in the program. The order of the arguments is not important. The @samp{mgnuc} command is the Mercury GNU C compiler; it is a shell script that invokes the GNU C compiler @samp{gcc} @c (or some other C compiler if GNU C is not available) with the options appropriate for compiling the C programs generated by Mercury. You then link the object code of each module with the object code of the initialization file to yield the executable: @example ml -o @var{main_module} @var{module1}.o @var{module2}.o ... @var{main_module}_init.o @end example @samp{ml}, the Mercury linker, is another shell script that invokes a C compiler with options appropriate for Mercury, this time for linking. @samp{ml} also pipes any error messages from the linker through @samp{mdemangle}, the Mercury symbol demangler, so that error messages refer to predicate names in the Mercury source code rather than to the names used in the intermediate C code. The above command puts the executable in the file @file{@var{main_module}}. The same command line without the @samp{-o} option would put the executable into the file @file{a.out}. @samp{mc} and @samp{ml} both accept a @samp{-v} (verbose) option. You can use that option to see what is actually going on. For the full set of options of @samp{mc}, see @ref{Invocation}. Once you have created an executable for a Mercury program, you can go ahead and execute it. You may however wish to specify certain options to the Mercury runtime system. The Mercury runtime accepts options via the @samp{MERCURY_OPTIONS} environment variable. Setting @samp{MERCURY_OPTIONS} to @samp{-h} will list the available options. The most useful of these are the options that set the size of the stacks. The det stack and the nondet stack are allocated fixed sizes at program start-up. The default size is 512k for the det stack and 128k for the nondet stack, but these can be overridden with the @samp{-sd} and @samp{-sn} options, whose arguments are the desired sizes of the det and nondet stacks respectively, in units of kilobytes. On operating systems that provide the appropriate support, the Mercury runtime will ensure that stack overflow is trapped by the virtual memory system. With conservative garbage collection (the default), the heap will start out with a zero size, and will be dynamically expanded as needed, When not using conservative garbage collection, the heap has a fixed size like the stacks. The default size is 4 Mb, but this can be overridden with the @samp{-sh} option. @node Using Prolog @chapter Using Prolog Since the current Mercury implementation does not yet provide any useful support for debugging, we recommend that you use a Prolog system for debugging your Mercury programs. However, there is no point in using a Prolog debugger to track down a bug that can be detected statically by the Mercury compiler. The command @example mc -e @var{module1}.m ... @end example causes the Mercury compiler to perform all its syntactic and semantic checks on the named modules, but not to generate any code. In our experience, omitting that step is not wise. If you do omit it, you often waste a lot of time debugging problems that the compiler could have detected for you. @menu * Using NU-Prolog:: Building and debugging Mercury programs with NU-Prolog * Using SICStus:: Building and debugging Mercury programs with SICStus Prolog * Prolog hazards:: The hazards of executing Mercury programs using Prolog @end menu @node Using NU-Prolog @section Using NU-Prolog You can compile a Mercury source module using NU-Prolog via the command @example mnc @var{module1}.m ... @end example @samp{mnc} is the Mercury variant of @samp{nc}, the NU-Prolog compiler. It adapts @code{nc} to compile Mercury programs, e.g. by defining do-nothing predicates for the various Mercury declarations (which are executed by @code{nc}). Some invocations of @samp{mnc} will result in warnings such as @example Warning: main is a system predicate. It shouldn't be used as a non-terminal. @end example Such warnings should be ignored. @samp{mnc} compiles the modules it is given into NU-Prolog bytecode, stored in files with a @file{.no} suffix. You can link these together using the command @example mnl -o @var{main_module} @var{module1}.no ... @end example Ignore any warnings such as @example Warning: main/2 redefined Warning: solutions/2 redefined Warning: !/0 redefined @end example @samp{mnl}, the Mercury NU-Prolog linker, will put the executable (actually a shell script invoking a save file) into the file @file{@var{main_module}.nu}. This can be executed normally using @example ./@var{main_module}.nu @var{arguments} @end example Alternatively, one can execute such programs using @samp{mnp}, the Mercury version of np, the NU-Prolog interpreter. The command @example mnp @end example will start up the Mercury NU-Prolog interpreter. Inside the interpreter, you can load your source files with a normal consulting command such as @example ['@var{module}.m']. @end example You can also use the @file{--debug} option to @samp{mnl} when linking. This will produce an executable whose entry point is the NU-Prolog interpreter, rather than main/2 in your program. In both cases, you can start executing your program by typing @example r("@var{program-name} @var{arguments}"). @end example at the prompt of the NU-Prolog interpreter. All the NU-Prolog debugging commands work as usual. The most useful ones are the @code{trace} and @code{spy} commands at the main prompt to turn on complete or selective tracing respectively, and the @code{l} (leap), @code{s} (skip), and @code{r} (redo) commands of the tracer. For more information, see the NU-Prolog documentation. By default the debugger only displays the top levels of terms; you can use the @samp{|} command to enter an interactive term browser. (Within the term browser, type @samp{h.} for help.) Also note that in the debugger, we use a version of @code{error/1} which fails rather than aborting after printing the "Software Error:" message. This makes debugging easier, but will of course change the behaviour after an error occurs. @node Using SICStus @section Using SICStus Prolog Using SICStus Prolog is similar to using NU-Prolog, except that the commands to use are @samp{msc}, @samp{msl}, and @samp{msp} rather than @samp{mnc}, @samp{mnl}, and @samp{mnp}. Due to shortcomings in SICStus Prolog (in particular, the lack of backslash escapes in character strings), you need to use @samp{sicstus_conv} to convert Mercury @samp{.m} files to the @samp{.pl} files that SICStus Prolog expects before you can load them into the interpreter. The command to use is just @example sicstus_conv @var{module}.m @end example By default, @samp{msc} compiles files to machine code using SICStus Prolog's @samp{fastcode} mode. If space is more important than speed, you can use the @samp{--mode compactcode} option, which instructs @code{msc} to use SICStus Prolog's @samp{compactcode} mode, which compiles files to a bytecode format. @node Prolog hazards @section Hazards of using Prolog There are some Mercury programs which are not valid Prolog programs. In particular, Mercury will always reorder goals to ensure that they are mode-correct (or report a mode error if it cannot do so), but Prolog systems will not always do so, and will sometimes just silently give the wrong result. For example, in Mercury the following predicate will usually succeed, whereas in Prolog it will always fail. @example :- pred p(list(int)::in, list(int)::out) is semidet. p(L0, L) :- L \= [], q(L0, L). :- pred q(list(int)::in, list(int)::out) is det. @end example The reason is that in Mercury, the test @samp{L \= []} is reordered to after the call to @code{q/2}, but in Prolog, it executes even though @code{L} is not bound, and consequently the test always fails. NU-Prolog has logical alternatives to the non-logical Prolog operations, and since Mercury supports both syntaxes, you can use NU-Prolog's logical alternatives to avoid this problem. However, during the development of the Mercury compiler we had to abandon their use for efficiency reasons. Another hazard is that NU-Prolog does not have a garbage collector. @node Using Mmake @chapter Using Mmake Mmake, short for ``Mercury Make'', is a tool for building Mercury programs that is built on top of ordinary or GNU Make @footnote{ We aim to eventually add support for ordinary ``Make'' programs, but currently only GNU Make is supported.}. With Mmake, building even a complicated Mercury program consisting of a number of modules is as simple as @example mmake @var{main-module}.depend mmake @var{main-module} @end example Mmake only recompiles those files that need to be recompiled, based on automatically generated dependency information. Most of the dependencies are stored in @file{.d} files that are automatically recomputed every time you recompile, so they are never out-of-date. A little bit of the dependency information is stored in @file{.dep} files which are more expensive to recompute. The @samp{mmake @var{main-module}.depend} command which recreates the @file{@var{main-module}.dep} file needs to be repeated only when you add or remove a module from your program, and there is no danger of getting an inconsistent executable if you forget this step --- instead you will get a compile or link error. @samp{mmake} allows you to build more than one program in the same directory. Each program must have its own @file{.dep} file, and therefore you must run @samp{mmake @var{program}.depend} for each program. If there is a file called @samp{Mmake} in the current directory, Mmake will include that file in its automatically-generated Makefile. The @samp{Mmake} file can override the default values of various variables used by Mmake's builtin rules, or it can add additional rules, dependencies, and actions. Mmake's builtin rules are defined by the file @file{@var{prefix}/lib/mercury/mmake/Mmake.rules} (where @var{prefix} is @file{/usr/local/mercury-@var{version}} by default, and @var{version} is the version number, e.g. @samp{0.6}), as well as the rules in the automatically-generated @file{.dep} files. These rules define the following targets: @table @file @item @var{main-module}.depend Creates the file @file{@var{main-module}.dep} from @file{@var{main-module}.m} and the modules it imports. This step must be performed first. @item @var{main-module}.ints Ensure that the interface files for @var{main-module} and its imported modules are up-to-date. (If the underlying @samp{make} program does not handle transitive dependencies, this step may be necessary before attempting to make @file{@var{main-module}} or @file{@var{main-module}.check}; if the underlying @samp{make} is GNU Make, this step should not be necessary.) @item @var{main-module}.check Perform semantic checking on @var{main-module} and its imported modules. Error messages are placed in @file{.err} files. @item @var{main-module} Compiles and links @var{main-module} using the Mercury compiler. Error messages are placed in @file{.err2} files. @item @var{main-module}.split Compiles and links @var{main-module} using the Mercury compiler, with the @samp{--split-c-files} option enabled. @xref{Output-level (LLDS->C) optimization options} for more information about @samp{--split-c-files}. @item @var{main-module}.nu Compiles and links @var{main-module} using NU-Prolog. @item @var{main-module}.nu.debug Compiles and links @var{main-module} using NU-Prolog. The resulting executable will start up in the NU-Prolog interpreter rather than calling main/2. @item @var{main-module}.sicstus Compiles and links @var{main-module} using SICStus Prolog. @item @var{main-module}.sicstus.debug Compiles and links @var{main-module} using SICStus Prolog. The resulting executable will start up in the SICStus Prolog interpreter rather than calling main/2. @item @var{main-module}.clean Removes the automatically generated files that contain the compiled code of the program and the error messages produced by the compiler. Specifically, this will remove all the @samp{.c}, @samp{.s}, @samp{.o}, @samp{.no}, @samp{.ql}, @samp{.err}, and @samp{.err2} files belonging to the named @var{main-module} or its imported modules. @item @var{main-module}.realclean Removes all the automatically generated files. In addition to the files removed by @var{main-module}.clean, this removes the @samp{.date}, @samp{.int}, @samp{.int2}, @samp{.d}, and @samp{.dep} belonging to one of the modules of the program, and also the various possible executables for the program --- @samp{@var{main-module}}, @samp{@var{main-module}.nu}, @samp{@var{main-module}.nu.save}, @samp{@var{main-module}.nu.debug}, @samp{@var{main-module}.nu.debug.save}, @samp{@var{main-module}.sicstus}, and @samp{@var{main-module}.sicstus.debug}. @item clean This makes @samp{@var{main-module}.clean} for every @var{main-module} for which there is a @file{@var{main-module}.dep} file in the current directory. @item realclean This makes @samp{@var{main-module}.realclean} for every @var{main-module} for which there is a @file{@var{main-module}.dep} file in the current directory. @end table The variables used by the builtin rules are defined in @file{@var{prefix}/lib/mercury/mmake/Mmake.vars}. @c --------------------------------------------------------------------------- @node Profiling @chapter Profiling @menu * Profiling introduction:: What is profiling useful for? * Building profiled applications:: How to enable profiling. * Creating the profile:: How to create profile data. * Displaying the profile:: How to display the profile data. * Analysis of results:: How to interpret the output. @end menu @node Profiling introduction @section Introduction The Mercury profiler @samp{mprof} is a tool which can be used to analyze a Mercury program's performance, so that the programmer can determine which predicates are taking up a disproportionate amount of the execution time. To obtain the best trade-off between productivity and efficiency, programmers should not spend too much time optimizing their code until they know which parts of the code are really taking up most of the time. Only once the code has been profiled should the programmer consider making optimizations that would improve efficiency at the expense of readability or ease of maintenance. A good profiler is a tool that should be part of every software engineer's toolkit. @node Building profiled applications @section Building profiled applications To enable profiling, your program must be built in a @samp{.prof} grade. For example, if the default grade on your system is @samp{asm_fast.gc}, then to compile with profiling enabled, use grade @samp{asm_fast.gc.prof}. You can do this by setting the @samp{GRADE} variable in your Mmake file, e.g. by adding the line @samp{GRADE=asm_fast.gc.prof}. @xref{Compilation model options} for more information about the different grades. Enabling profiling has several effects. Firstly, it causes the compiler to generate slightly modified code which counts the number of times each predicate is called, and for every predicate call, records the caller and callee. Secondly, your program will be linked with versions of the library and runtime that were compiled with profiling enabled. (It also has the effect for each source file the compiler generates the static call graph for that file in @samp{@var{module}.prof}.) @node Creating the profile @section Creating the profile The next step is to run your program. The profiling version of your program will collect profiling information during execution, and save this information in the files @samp{Prof.Counts}, @samp{Prof.Decls}, and @samp{Prof.CallPair}. (@samp{Prof.Decl} contains the names of the predicates and their associated addresses, @samp{Prof.CallPair} records the number of times each predicate was called by each different caller, and @samp{Prof.Counts} records the number of times that execution was in each predicate when a profiling interrupt occurred.) It would be nice if there was a way to combine profiling data from multiple runs of the same program, but unfortunately there is not yet any way to do that. Due to a known timing-related bug in our code, you may occasionally get segmentation violations when running your program with profiling enabled. If this happens, just run it again --- the problem does not occur frequently. This bug will hopefully be fixed soon. @node Displaying the profile @section Displaying the profile To display the profile, just type @samp{mprof}. This will read the @file{Prof.*} files and display the flat profile in a nice human-readable format. If you also want to see the call graph profile, which takes a lot longer to generate, type @samp{mprof -c}. Note that @samp{mprof} can take quite a while to execute, and will usually produce quite a lot of output, so you will usually want to redirect the output into a file with a command such as @samp{mprof > mprof.out}. @node Analysis of results @section Analysis of results The profile output consists of three major sections. These are named the call graph profile, the flat profile and the alphabetic listing. The call graph profile presents the local call graph of each predicate. For each predicate it shows the parents (callers) and children (callees) of that predicate, and shows the execution time and call counts for each parent and child. It is sorted on the total amount of time spent in the predicate and all of its descendents (i.e. all of the predicates that it calls, directly or indirectly.) The flat profile presents the just execution time spent in each predicate. It does not count the time spent in descendents of a predicate. The alphabetic listing just lists the predicates in alphabetical order, along with their index number in the call graph profile, so that you can quickly find the entry for a particular predicate in the call graph profile. The profiler works by interrupting the program at frequent intervals, and each time recording the currently active predicate and its caller. It uses these counts to determine the proportion of the total time spent in each predicate. This means that the figures calculated for these times are only a statistical approximation to the real values, and so they should be treated with some caution. The time spent in a predicate and its descendents is calculated by propagating the times up the call graph, assuming that each call to a predicate from a particular caller takes the same amount of time. This assumption is usually reasonable, but again the results should be treated with caution. Note that any time spent in a C function (e.g. time spent in @samp{GC_malloc()}, which does memory allocation and garbage collection) is credited to the predicate that called that C function. Here is a small portion of the call graph profile from an example program. @example called/total parents index %time self descendents called+self name index called/total children [1] 100.0 0.00 0.75 0 call_engine_label [1] 0.00 0.75 1/1 do_interpreter [3] ----------------------------------------------- 0.00 0.75 1/1 do_interpreter [3] [2] 100.0 0.00 0.75 1 io__run/0(0) [2] 0.00 0.00 1/1 io__init_state/2(0) [11] 0.00 0.74 1/1 main/2(0) [4] ----------------------------------------------- 0.00 0.75 1/1 call_engine_label [1] [3] 100.0 0.00 0.75 1 do_interpreter [3] 0.00 0.75 1/1 io__run/0(0) [2] ----------------------------------------------- 0.00 0.74 1/1 io__run/0(0) [2] [4] 99.9 0.00 0.74 1 main/2(0) [4] 0.00 0.74 1/1 sort/2(0) [5] 0.00 0.00 1/1 print_list/3(0) [16] 0.00 0.00 1/10 io__write_string/3(0) [18] ----------------------------------------------- 0.00 0.74 1/1 main/2(0) [4] [5] 99.9 0.00 0.74 1 sort/2(0) [5] 0.05 0.65 1/1 list__perm/2(0) [6] 0.00 0.09 40320/40320 sorted/1(0) [10] ----------------------------------------------- 8 list__perm/2(0) [6] 0.05 0.65 1/1 sort/2(0) [5] [6] 86.6 0.05 0.65 1+8 list__perm/2(0) [6] 0.00 0.60 5914/5914 list__insert/3(2) [7] 8 list__perm/2(0) [6] ----------------------------------------------- 0.00 0.60 5914/5914 list__perm/2(0) [6] [7] 80.0 0.00 0.60 5914 list__insert/3(2) [7] 0.60 0.60 5914/5914 list__delete/3(3) [8] ----------------------------------------------- 40319 list__delete/3(3) [8] 0.60 0.60 5914/5914 list__insert/3(2) [7] [8] 80.0 0.60 0.60 5914+40319 list__delete/3(3) [8] 40319 list__delete/3(3) [8] ----------------------------------------------- 0.00 0.00 3/69283 tree234__set/4(0) [15] 0.09 0.09 69280/69283 sorted/1(0) [10] [9] 13.3 0.10 0.10 69283 compare/3(0) [9] 0.00 0.00 3/3 __Compare___io__stream/0(0) [20] 0.00 0.00 69280/69280 builtin_compare_int/3(0) [27] ----------------------------------------------- 0.00 0.09 40320/40320 sort/2(0) [5] [10] 13.3 0.00 0.09 40320 sorted/1(0) [10] 0.09 0.09 69280/69283 compare/3(0) [9] ----------------------------------------------- @end example The first entry is @samp{call_engine_label} and its parent is @samp{}, meaning that it is the root of the call graph. (The first three entries, @samp{call_engine_label}, @samp{do_interpreter}, and @samp{io__run/0} are all part of the Mercury runtime; @samp{main/2} is the entry point to the user's program.) Each entry of the call graph profile consists of three sections, the parent predicates, the current predicate and the children predicates. Reading across from the left, for the current predicate the fields are: @itemize @bullet @item The unique index number for the current predicate. (The index numbers are used only to make it easier to find a particular entry in the call graph.) @item The percentage of total execution time spent in the current predicate and all its descendents. As noted above, this is only a statistical approximation. @item The ``self'' time: the time spent executing code that is part of current predicate. As noted above, this is only a statistical approximation. @item The descendent time: the time spent in the current predicate and all its descendents. As noted above, this is only a statistical approximation. @item The number of times a predicate is called. If a predicate is (directly) recursive, this column will contain the number of calls from other predicates, a plus sign, and then the number of recursive calls. These numbers are exact, not approximate. @item The name of the predicate followed by its index number. @end itemize The predicate names are not just followed by their arity but also by their mode in brackets. A mode of zero corresponds to the first mode declaration of that predicate in the source code. For example, @samp{list__delete/3(3)} corresponds to the @samp{(out, out, in)} mode of @samp{list__delete/3}. Now for the parent and child predicates the self and descendent time have slightly different meanings. For the parent predicates the self and descendent time represent the proportion of the current predicate's self and descendent time due to that parent. These times are obtained using the assumption that each call contributes equally to the total time of the current predicate. @c XXX is that really true? Do we really make that assumption? @node Invocation @chapter Invocation This section contains a brief description of all the options available for @samp{mc}, the Mercury compiler. Sometimes this list is a little out-of-date; use @samp{mc --help} to get the most up-to-date list. @menu * Invocation overview:: * Verbosity options:: * Warning options:: * Output options:: * Auxiliary output options:: * Compilation model options:: * Code generation options:: * Optimization options:: * Link options:: * Miscellaneous options:: @end menu @node Invocation overview @section Invocation overview @code{mc} is invoked as @example mc [@var{options}] @var{modules} @end example For module names, the trailing @file{.m} is optional. Options are either short (single-letter) options preceded by a single @samp{-}, or long options preceded by @samp{--}. Options are case-sensitive. We call options that do not take arguments @dfn{flags}. Single-letter flags may be grouped with a single @samp{-}, e.g. @samp{-vVc}. Single-letter flags may be negated by appending another trailing @samp{-}, e.g. @samp{-v-}. Long flags may be negated by preceding them with @samp{no-}, e.g. @samp{--no-verbose}. @node Warning options @section Warning options @table @code @item -w @itemx --inhibit-warnings Disable all warning messages. @sp 1 @item --halt-at-warn. This option causes the compiler to treat all warnings as if they were errors. This means that if any warning is issued, the compiler will not generate code --- instead, it will return a non-zero exit status. @sp 1 @item --halt-at-syntax-error. This option causes the compiler to halt immediately after syntax checking and not do any semantic checking if it finds any syntax errors in the program. @sp 1 @item --no-warn-singleton-variables Don't warn about variables which only occur once. @sp 1 @item --no-warn-missing-det-decls For predicates that are local to a module (those that are not exported), don't issue a warning if the @samp{pred} or @samp{mode} declaration does not have a determinism annotation. Use this option if you want the compiler to perform automatic determinism inference for non-exported predicates. @sp 1 @item --no-warn-det-decls-too-lax Don't warn about determinism declarations which could have been stricter. @sp 1 @item --no-warn-nothing-exported Don't warn about modules whose interface sections have no exported predicates, modes or types. @sp 1 @item --warn-unused-args Warn about predicate arguments which are not used. @end table @node Verbosity options @section Verbosity options @table @code @item -v @itemx --verbose Output progress messages at each stage in the compilation. @sp 1 @item -V @itemx --very_verbose Output very verbose progress messages. @sp 1 @item -E @itemx --verbose-error-messages Explain error messages. Asks the compiler to give you a more detailed explanation of any errors it finds in your program. @sp 1 @item -S @itemx --statistics Output messages about the compiler's time/space usage. At the moment this option implies @samp{--no-trad-passes}, so you get information at the boundaries between phases of the compiler. @sp 1 @item -T @itemx --debug-types Output detailed debugging traces of the type checking. @sp 1 @item -N @itemx --debug-modes Output detailed debugging traces of the mode checking. @sp 1 @item --debug-detism Output detailed debugging traces of deterministic analysis. @sp 1 @item --debug-opt Output detailed debugging traces of the optimization process. @sp 1 @item --debug-vn Output detailed debugging traces of the value numbering optimization pass. The different bits in the number argument of this option control the printing of different types of tracing messages. @end table @node Output options @section Output options These options are mutually exclusive. If more than one of these options is specified, only the first in this list will apply. If none of these options are specified, the default action is to compile and link the modules named on the command line to produce an executable. @table @code @item -M @itemx --generate-dependencies Output ``Make''-style dependencies for the module and all of its dependencies to @file{@var{module}.dep}. @sp 1 @item -i @itemx --make-interface Write the module interface to @file{@var{module}.int}. Also write the short interface to @file{@var{module}.int2}. @sp 1 @item -G @itemx --convert-to-goedel Convert the Mercury code to Goedel. Output to file @file{@var{module}.loc}. The translation is not perfect; some Mercury constructs cannot be easily translated into Goedel. @sp 1 @item -P @itemx --pretty-print @itemx --convert-to-mercury Convert to Mercury. Output to file @file{@var{module}.ugly}. This option acts as a Mercury ugly-printer. (It would be a pretty-printer, except that comments are stripped and nested if-then-elses are indented too much --- so the result is rather ugly.) @sp 1 @item --typecheck-only Just check the syntax and type-correctness of the code. Don't invoke the mode analysis and later passes of the compiler. When converting Prolog code to Mercury, it can sometimes be useful to get the types right first and worry about modes second; this option supports that approach. @sp 1 @item -e @itemx --errorcheck-only Check the module for errors, but do not generate any code. @sp 1 @item -C @itemx --compile-to-c @itemx --compile-to-C Generate C code in @file{@var{module}.c}, but not object code. @sp 1 @item -c @itemx --compile-only Generate C code in @file{@var{module}.c} and object code in @file{@var{module}.o} but do not attempt to link the named modules. @end table @node Auxiliary output options @section Auxiliary output options @table @code @item --auto-comments Output comments in the @file{@var{module}.c} file. This is primarily useful for trying to understand how the generated C code relates to the source code, e.g. in order to debug the compiler. The code may be easier to understand if you also use the @samp{--no-llds-optimize} option. @sp 1 @item -n @itemx --line-numbers Output source line numbers in the generated code. Only works with the @samp{--convert-to-goedel} and @samp{--convert-to-mercury} options. @sp 1 @item --show-dependency-graph Write out the dependency graph to @var{module}.dependency_graph. @sp 1 @item -d @var{stage} @itemx --dump-hlds @var{stage} Dump the HLDS (intermediate representation) after the specified stage number or stage name to @file{@var{module}.hlds_dump.@var{num}-@var{name}}. Stage numbers range from 1 to 99; not all stage numbers are valid. The special stage name @samp{all} causes the dumping of all stages. Multiple dump options accumulate. @sp 1 @item -D @itemx --verbose-dump-hlds With @samp{--dump-hlds}, dumps some additional info. @end table @node Compilation model options @section Compilation model options The following compilation options affect the generated code in such a way that the entire program must be compiled with the same setting of these options, and it must be linked to a version of the Mercury library which has been compiled with the same setting. Rather than setting them individually, you must specify them all at once by selecting a particular compilation model ("grade"). @table @asis @item @code{-s @var{grade}} @itemx @code{--grade @var{grade}} Select the compilation model. The @var{grade} should be one of @samp{debug}, @samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump}, @samp{fast}, @samp{asm_fast}, or one of those with @samp{.gc}, @samp{.prof} or @samp{.gc.prof} appended. The default grade is system-dependent; it is chosen at installation time by @samp{configure}, the auto-configuration script, but can be overridden with the @samp{MERCURY_DEFAULT_GRADE} environment variable if desired. Depending on your particular installation, only a subset of these possible grades will have been installed. Attempting to use a grade which has not been installed will result in an error at link time. The following table shows the options that are selected by each grade; it is followed by descriptions of those options. @table @asis @item @var{Grade} @var{Options implied}. @item @samp{debug} @code{--debug --no-c-optimize}. @item @samp{none} None. @item @samp{reg} @code{--gcc-global-registers}. @item @samp{jump} @code{--gcc-nonlocal gotos}. @item @samp{fast} @code{--gcc-global-registers --asm-labels}. @item @samp{asm_jump} @code{--gcc-global-registers --asm-labels}. @item @samp{asm_fast} @code{--gcc-global-registers --gcc-nonlocal_gotos --asm-labels}. @item Any of the above followed by @samp{.gc} As above, plus @code{--conservative-gc}. @item Any of the above followed by @samp{.prof} As above, plus @code{--profiling}. @end table @sp 1 Reminder: the following optimizations should not be set individually. Instead, you should use the @samp{--grade} option to change the setting of these options. @sp 1 @item @code{--gcc-global-registers} (grades: reg, fast, asm_fast) @itemx @code{--no-gcc-global-registers} (grades: debug, none, jump, asm_jump) Specify whether or not to use GNU C's global register variables extension. @sp 1 @item @code{--gcc-non-local-gotos} (grades: jump, fast, asm_jump, asm_fast) @item @code{--no-gcc-non-local-gotos} (grades: debug, none, reg) Specify whether or not to use GNU C's ``labels as values'' extension. @sp 1 @item @code{--asm-labels} (grades: asm_jump, asm_fast) @itemx @code{--no-asm-labels} (grades: debug, none, reg, jump, fast) Specify whether or not to use GNU C's asm extensions for inline assembler labels. @sp 1 @item @code{--gc @{none, conservative, accurate@}} @itemx @code{--garbage-collection @{none, conservative, accurate@}} Specify which method of garbage collection to use. @samp{.gc} grades use @samp{--gc conservative}, other grades use @samp{--gc none}. @samp{accurate} is not yet implemented. @sp 1 @item @code{--tags @{none, low, high@}} (This option is not intended for general use.) Specify whether to use the low bits or the high bits of each word as tag bits (default: low). @sp 1 @item @code{--num-tag-bits @var{n}} (This option is not intended for general use.) Use @var{n} tag bits. This option is required if you specify @samp{--tags high}. With @samp{--tags low}, the default number of tag bits to use is determined by the auto-configuration script. @sp 1 @item @code{--have-delay-slot} (This option is not intended for general use.) Assume that branch instructions have a delay slot. @sp 1 @item @code{--num-real-r-regs @var{n}} (This option is not intended for general use.) Assume r1 up to r@var{n} are real general purpose registers. @sp 1 @item @code{--num-real-f-regs @var{n}} (This option is not intended for general use.) Assume f1 up to f@var{n} are real floating point registers. @sp 1 @item @code{--num-real-r-temps @var{n}} (This option is not intended for general use.) Assume that @var{n} non-float temporaries will fit into real machine registers. @sp 1 @item @code{--num-real-f-temps @var{n}} (This option is not intended for general use.) Assume that @var{n} float temporaries will fit into real machine registers. @sp 1 @item @code{--profiling} (grades: any grade ending in @samp{.prof}) Enable profiling. Insert profiling hooks in the generated code, and also output some profiling information (the static call graph) to the file @samp{@var{module}.prof}. @xref{Profiling}. @item @code{--debug} (grades: debug) Enable debugging. Pass the @samp{-g} flag to the C compiler, instead of @samp{-DSPEED}, to enable debugging of the generated C code. This option also implies @samp{--no-c-optimize}. Debugging support is currently extremely primitive - this option is probably not useful to anyone except the Mercury implementors. We recommend that you use instead use `mnp' or `msp'. @xref{Using Prolog} for details. @sp 1 @item @code{--args @{old, compact@}} @item @code{--arg-convention @{old, compact@}} (This option is not intended for general use.) Use the specified argument passing convention in the generated low-level C code. With the @samp{simple} convention, the @var{n}th argument is passed in or out using register r@var{n}. With the @samp{compact} convention, the @var{n}th input argument is passed using register r@var{n} and the @var{n}th output argument is returned using register r@var{n}. The @samp{compact} convention generally leads to more efficient code. However, currently only the @samp{simple} convention is supported. @end table @node Code generation options @section Code generation options @table @code @item --no-trad-passes The default @samp{--trad-passes} completely processes each predicate before going on to the next predicate. This option tells the compiler to complete each phase of code generation on all predicates before going on the next phase on all predicates. @c @sp 1 @c @item --no-polymorphism @c Don't handle polymorphic types. @c (Generates slightly more efficient code, but stops @c polymorphism from working except in special cases.) @sp 1 @item --no-reclaim-heap-on-nondet-failure Don't reclaim heap on backtracking in nondet code. @sp 1 @item --no-reclaim-heap-on-semidet-failure Don't reclaim heap on backtracking in semidet code. @sp 1 @item --use-macro-for-redo-fail Emit the fail or redo macro instead of a branch to the fail or redo code in the runtime system. @sp 1 @item --cc @var{compiler-name} Specify which C compiler to use. @sp 1 @item --c-include-directory @var{dir} Specify the directory containing the Mercury C header files. @sp 1 @item --cflags @var{options} Specify options to be passed to the C compiler. @end table @node Optimization options @section Optimization options @menu * Selecting an optimization level:: * High-level (HLDS->HLDS) optimization options:: * Medium-level (HLDS->LLDS) optimization options:: * Low-level (LLDS->LLDS) optimization options:: * Output-level (LLDS->C) optimization options:: @end menu @node Selecting an optimization level @subsection Selecting an optimization level @table @code @item -O @var{n} @itemx --opt-level @var{n} @itemx --optimization-level @var{n} Set optimization level to @var{n}. Optimimization level 0 means no optimization while optimimization level 5 means full optimization. @item --opt-space @item --optimize-space Turn on optimizations that reduce code size and turn off optimizations that significantly increase code size. @end table @node High-level (HLDS->HLDS) optimization options @subsection High-level (HLDS->HLDS) optimization options These optimizations are high-level transformations on our HLDS (high-level data structure). @table @code @item --no-inlining Disable all forms of inlining. @item --no-inline-simple Disable the inlining of simple procedures. @item --no-inline-single-use Disable the inlining of procedures called only once. @item --inline-threshold @var{threshold} Inline a procedure if its size (measured roughly in terms of the number of connectives in its internal form), multiplied by the number of times it is called, is below the given threshold. @sp 1 @item --no-common-struct Disable optimization of common term structures. @sp 1 @item --no-common-goal Disable optimization of common goals. At the moment this optimization detects only common deconstruction unifications. Disabling this optimization reduces the class of predicates that the compiler considers to be deterministic. @c @item --constraint-propagation @c Enable the constraint propagation transformation. @c @sp 1 @c @item --prev-code @c Migrate into the start of branched goals. @sp 1 @item --no-follow-code Don't migrate builtin goals into branched goals. @sp 1 @item --no-optimize-unused-args Don't remove unused predicate arguments. The compiler will generate less efficient code for polymorphic predicates. @sp 1 @item --no-optimize-higher-order Don't specialize calls to higher-order predicates where the higher-order arguments are known. @sp 1 @item --optimize-dead-procs. Enable dead predicate elimination. @sp 1 @item --excess-assign Remove excess assignment unifications. @c @sp 1 @c @item --no-specialize @c Disable the specialization of procedures. @end table @node Medium-level (HLDS->LLDS) optimization options @subsection Medium-level (HLDS->LLDS) optimization options These optimizations are applied during the process of generating low-level intermediate code from our high-level data structure. @table @code @item --no-static-ground-terms Disable the optimization of constructing constant ground terms at compile time and storing them as static constants. @sp 1 @item --no-smart-indexing Generate switches as a simple if-then-else chains; disable string hashing and integer table-lookup indexing. @sp 1 @item --dense-switch-req-density @var{percentage} The jump table generated for an atomic switch must have at least this percentage of full slots (default: 25). @sp 1 @item --dense-switch-size @var{size} The jump table generated for an atomic switch must have at least this many entries (default: 4). @sp 1 @item --lookup-switch-req-density @var{percentage} The lookup tables generated for an atomic switch in which all the outputs are constant terms must have at least this percentage of full slots (default: 25). @sp 1 @item --lookup-switch-size @var{size} The lookup tables generated for an atomic switch in which all the outputs are constant terms must have at least this many entries (default: 4). @sp 1 @item --string-switch-size @var{size} The hash table generated for a string switch must have at least this many entries (default: 8). @sp 1 @item --tag-switch-size @var{size} The number of alternatives in a tag switch must be at least this number (default: 8). @sp 1 @item --no-middle-rec Disable the middle recursion optimization. @sp 1 @item --no-simple-neg Don't generate simplified code for simple negations. @sp 1 @item --no-follow-vars Don't optimize the assignment of registers in branched goals. @end table @node Low-level (LLDS->LLDS) optimization options @subsection Low-level (LLDS->LLDS) optimization options These optimizations are transformations that are applied to our low-level intermediate code before emitting C code. @table @code @item --no-llds-optimize Disable the low-level optimization passes. @sp 1 @item --no-optimize-peep Disable local peephole optimizations. @sp 1 @item --no-optimize-jumps Disable elimination of jumps to jumps. @sp 1 @item --no-optimize-fulljumps Disable elimination of jumps to ordinary code. @sp 1 @item --no-optimize-labels Disable elimination of dead labels and code. @sp 1 @item --optimize-dups Enable elimination of duplicate code. @c @sp 1 @c @item --optimize-copyprop @c Enable the copy propagation optimization. @sp 1 @item --optimize-value-number Perform value numbering on extended basic blocks. @c @sp 1 @c @item --pred-value-number @c Extend value numbering to whole predicates, rather than just basic blocks. @sp 1 @item --no-optimize-frames Disable stack frame optimizations. @sp 1 @item --no-optimize-delay-slot Disable branch delay slot optimizations. @sp 1 @item --optimize-repeat @var{n} Iterate most optimizations at most @var{n} times (default: 3). @sp 1 @item --optimize-vnrepeat @var{n} Iterate value numbering at most @var{n} times (default: 1). @end table @node Output-level (LLDS->C) optimization options @subsection Output-level (LLDS->C) optimization options These optimizations are applied during the process of generating C intermediate code from our low-level data structure. @table @code @item --no-emit-c-loops Use only gotos -- don't emit C loop constructs. @sp 1 @item --procs-per-c-function @var{n} Don't put the code for more than @var{n} Mercury procedures in a single C function. The default value of @var{n} is one. Increasing @var{n} can produce slightly more efficient code, but makes compilation slower. Setting @var{n} to the special value zero has the effect of putting all the procedures in a single function, which produces the most efficient code but tends to severely stress the C compiler. @sp 1 @item --split-c-files Generate each C function in its own C file, so that the linker will optimize away unused code. This has the same effect as @samp{--optimize-dead-procs}, except that it works globally at link time, rather than over a single module, so it does a much better job of eliminating unused procedures. This option significantly increases compilation time, link time, and intermediate disk space requirements, but in return reduces the size of the final executable, typically by about 10-20%. This option is only useful with @samp{--procs-per-c-function 1}. @sp 1 @item --no-c-optimize Don't enable the C compiler's optimizations. @end table @node Miscellaneous options @section Miscellaneous options @table @code @item -b @var{builtin} @itemx --builtin-module @var{builtin} Use @var{builtin} instead of @samp{mercury_builtin} as the module which always gets automatically imported. @sp 1 @item -I @var{dir} @itemx --search-directory @var{dir} Append @var{dir} to the list of directories to be searched for imported modules. @sp 1 @item -? @item -h @itemx --help Print a usage message. @c @item -H @var{n} @c @itemx --heap-space @var{n} @c Pre-allocate @var{n} kilobytes of heap space. @c This option is now obsolete. In the past it was used to avoid @c NU-Prolog's "Panic: growing stacks has required shifting the heap" @c message. @end table @node Link options @section Link options @table @code @sp 1 @item -o @var{filename} @itemx --output-file @var{filename} Specify the name of the final executable. (The default executable name is the same as the name of the first module on the command line, but without the @samp{.m} extension.) @sp 1 @item --link-flags @var{options} Specify options to be passed to @samp{ml}, the Mercury linker. @sp 1 @item -L @var{directory} @item --library-directory @var{directory} Append @var{dir} to the list of directories in which to search for libraries. @item -l @var{library} @item --library @var{library} Link with the specified library. @item --link-object @var{object} Link with the specified object file. @end table @node Environment @chapter Environment variables The shell scripts in the Mercury compilation environment will use the following environment variables if they are set. There should be little need to use these, because the default values will generally work fine. @table @code @item MERCURY_DEFAULT_GRADE The default grade to use if no @samp{--grade} option is specified. @sp 1 @item MERCURY_OPTIONS A list of options for the Mercury runtime that gets linked into every Mercury program. Options are available to set the size of the different memory areas, and to enable various debugging traces. Set @samp{MERCURY_OPTIONS} to @samp{-h} for help. @sp 1 @item MERCURY_C_INCL_DIR Directory for the Mercury C header files (@file{*.h}). @sp 1 @item MERCURY_INT_DIR Directory for the Mercury library interface files (@file{*.int} and @file{*.int2}). @sp 1 @item MERCURY_NC_BUILTIN Filename of the Mercury `nc'-compatibility file (nc_builtin.nl). @sp 1 @item MERCURY_C_LIB_DIR Base directory containing the Mercury libraries (@file{libmer.a} and possibly @file{libmer.so}) for each configuration and grade. The libraries for each configuration and grade should be in the subdirectory @var{config}/@var{grade} of @code{$MERCURY_C_LIB_DIR}. @sp 1 @item MERCURY_NONSHARED_LIB_DIR For IRIX 5, this environment variable can be used to specify a directory containing a version of libgcc.a which has been compiled with @samp{-mno-abicalls}. See the file @samp{README.IRIX-5} in the Mercury source distribution. @sp 1 @item MERCURY_MOD_LIB_DIR The directory containing the .init files in the Mercury library. They are used to create the initialization file @file{*_init.c}. @sp 1 @item MERCURY_MOD_LIB_MODS The names of the .init files in the Mercury library. @sp 1 @item MERCURY_NU_LIB_DIR Directory for the NU-Prolog object files (@file{*.no}) for the NU-Prolog Mercury library. @sp 1 @item MERCURY_NU_LIB_OBJS List of the NU-Prolog object files (@file{*.no}) for the Mercury library. @sp 1 @item MERCURY_COMPILER Filename of the Mercury Compiler. @sp 1 @item MERCURY_INTERPRETER Filename of the Mercury Interpreter. @sp 1 @item MERCURY_MKINIT Filename of the program to create the @file{*_init.c} file. @end table @node C compilers @chapter Using a different C compiler The Mercury compiler takes special advantage of certain extensions provided by GNU C to generate much more efficient code. We therefore recommend that you use GNU C for compiling Mercury programs. However, if for some reason you wish to use another compiler, it is possible to do so. Here's what you need to do. @itemize @bullet @item You must specify the name of the new compiler. You can do this either by setting the @samp{MERCURY_C_COMPILER} environment variable, by adding a line @samp{MGNUC=MERCURY_C_COMPILER=@dots{} mgnuc} to your @samp{Mmake} file, or by using the @samp{--cc} option to @samp{mc}. You may need to specify some option(s) to the C compiler to ensure that it uses an ANSI preprocessor (e.g. if you are using the DEC Alpha/OSF 3.2 C compiler, you would need to pass @samp{--cc="cc -std"} to @samp{mc} so that it will pass the @samp{-std} option to @samp{cc}). @item You must use the grade @samp{none} or @samp{none.gc}. You can specify the grade in one of three ways: by setting the @samp{MERCURY_DEFAULT_GRADE} environment variable, by adding a line @samp{GRADE=@dots{}} to your @samp{Mmake} file, or by using the @samp{--grade} option to @samp{mc}. (You will also need to install those grades of the Mercury library, if you have not already done so.) @item If your compiler is particularly strict in enforcing ANSI compliance, you may also need to compile the Mercury code with @samp{--no-static-ground-terms}. @end itemize @contents @bye