mirror of
https://github.com/Mercury-Language/mercury.git
synced 2026-04-21 12:23:44 +00:00
99ae820a1d
Estimated hours taken: 0.25 doc/user/guide.texi Document that -I options may need to be added to MGNUCFLAGS if inter-module optimization is being used on a library which uses the C interface.
2843 lines
101 KiB
Plaintext
2843 lines
101 KiB
Plaintext
\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-1998 The 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
|
|
@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-1998 The 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 mmc:: Compiling and linking programs with the Mercury compiler
|
|
* Running:: Execution of programs built with the Mercury compiler
|
|
* Using Prolog:: Building and debugging Mercury programs with Prolog
|
|
* Using Mmake:: ``Mercury Make'', a tool for building Mercury programs
|
|
* Libraries:: Creating and using libraries of Mercury modules
|
|
* 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{mmc}, 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{mmc} 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 must be named @file{*.m}.
|
|
Each Mercury source file should contain a single Mercury module
|
|
whose module name should be the same as the filename without
|
|
the @samp{.m} extension.
|
|
|
|
The Mercury implementation uses a variety of intermediate files, which
|
|
are described below. But all you really need to know is how to name
|
|
source files. For historical reasons, the default behaviour is for
|
|
intermediate files to be created in the current directory, but if you
|
|
use the @samp{--use-subdirs} option to @samp{mmc} or @samp{mmake}, all
|
|
these intermediate files will be created in a @file{Mercury}
|
|
subdirectory, where you can happily ignore them.
|
|
Thus you may wish to skip the rest of this chapter.
|
|
|
|
In cases where the source file name and module name don't match,
|
|
the names for intermediate files are based on the name of the
|
|
module from which they are derived, not on the source file name.
|
|
|
|
Files ending in @file{.int}, @file{.int0}, @file{.int2} and @file{.int3}
|
|
are interface files; these are generated automatically by the compiler,
|
|
using the @samp{--make-interface} (or @samp{--make-int}),
|
|
@samp{--make-private-interface} (or @samp{--make-priv-int}),
|
|
@samp{--make-short-interface} (or @samp{--make-short-int}) options.
|
|
Files ending in @file{.opt} are
|
|
interface files used in inter-module optimization,
|
|
and are created using the @samp{--make-optimization-interface}
|
|
(or @samp{--make-opt-int}) option.
|
|
Similarly, files ending in @file{.trans_opt} are interface files used in
|
|
transitive inter-module optimization, and are created using the
|
|
@samp{--make-transitive-optimization-interface}
|
|
(or @samp{--make-trans-opt-int}) option.
|
|
|
|
Since the interface of a module changes less often than its implementation,
|
|
the @file{.int}, @file{.int0}, @file{.int2}, @file{.int3}, @file{.opt},
|
|
and @file{.trans_opt} files will remain unchanged on many compilations.
|
|
To avoid unnecessary recompilations of the clients of the module,
|
|
the timestamps on the these files are updated only if their contents change.
|
|
@file{.date}, @file{.date0}, @file{.date3}, @file{.optdate},
|
|
and @file{.trans_opt_date}
|
|
files associated with the module are used as date stamps;
|
|
they are 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.
|
|
|
|
As usual, @file{.c} files are C source code,
|
|
@file{.h} files are C header files,
|
|
@file{.o} files are object code,
|
|
@file{.no} files are NU-Prolog object code, and
|
|
@file{.ql} files are SICStus Prolog object code.
|
|
In addition, @file{.pic_o} files are object code files
|
|
that contain position-independent code (PIC).
|
|
|
|
@node Using mmc
|
|
@chapter Using the Mercury compiler
|
|
|
|
Following a long Unix tradition,
|
|
the Mercury compiler is called @samp{mmc}
|
|
(for ``Melbourne Mercury Compiler'').
|
|
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{mmc} may be either file names (ending in @samp{.m}),
|
|
or module names. For a module name such as @samp{foo.bar.baz},
|
|
the compiler will look for the source in files @file{foo.bar.baz.m},
|
|
@file{bar.baz.m}, and @file{baz.m}, in that order.
|
|
|
|
To compile a program which consists of just a single source file,
|
|
use the command
|
|
|
|
@example
|
|
mmc @var{filename}.m
|
|
@end example
|
|
|
|
Unlike traditional Unix compilers, however,
|
|
@samp{mmc} will put the executable into a file called @file{@var{filename}},
|
|
not @file{a.out}.
|
|
|
|
For programs that consist of more than one source file, we @emph{strongly}
|
|
recommend that you use Mmake (@pxref{Using Mmake}). Mmake will perform
|
|
all the steps listed below, using automatic dependency analysis
|
|
to ensure that things are done in the right order, and that
|
|
steps are not repeated unnecessarily.
|
|
If you use Mmake, then you don't need to understand the details
|
|
of how the Mercury implementation goes about building programs.
|
|
Thus you may wish to skip the rest of this chapter.
|
|
|
|
To compile a source file to object code without creating an executable,
|
|
use the command
|
|
|
|
@example
|
|
mmc -c @var{filename}.m
|
|
@end example
|
|
|
|
@samp{mmc} will put the object code into a file called @file{@var{module}.o},
|
|
where @var{module} is the name of the Mercury module defined in
|
|
@file{@var{filename}.m}.
|
|
It also will leave the intermediate C code in a file called
|
|
@file{@var{module}.c}.
|
|
If the source file contains nested modules, then each sub-module will get
|
|
compiled to separate C and object files.
|
|
|
|
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 source files
|
|
using the following commands:
|
|
|
|
@example
|
|
mmc --make-short-int @var{filename1}.m @var{filename2}.m ...
|
|
mmc --make-priv-int @var{filename1}.m @var{filename2}.m ...
|
|
mmc --make-int @var{filename1}.m @var{filename2}.m ...
|
|
@end example
|
|
|
|
If you are going to compile with @samp{--intermodule-optimization} enabled,
|
|
then you also need to create the optimization interface files.
|
|
|
|
@example
|
|
mmc --make-opt-int @var{filename1}.m @var{filename2}.m ...
|
|
@end example
|
|
|
|
If you are going to compile with @samp{--transitive-intermodule-optimization}
|
|
enabled, then you also need to create the transitive optimization files.
|
|
|
|
@example
|
|
mmc --make-trans-opt @var{filename1}.m @var{filename2}.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
|
|
mmc @var{filename1}.m @var{filename2}.m ...
|
|
@end example
|
|
|
|
This will by default put the resulting executable in @file{@var{filename1}},
|
|
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{mmc -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 and function names from
|
|
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{mmc} 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{mmc}, see @ref{Invocation}.
|
|
|
|
@node Running
|
|
@chapter Running programs
|
|
|
|
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
|
|
mmc -e @var{filename1}.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 with SICStus Prolog
|
|
* Controlling printout:: Controlling display of large terms during debugging
|
|
* 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 file using NU-Prolog via the command
|
|
|
|
@example
|
|
mnc @var{filename1}.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{filename1}.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{filename}.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.)
|
|
See @ref{Controlling printout} for more information on controlling the
|
|
printout of terms.
|
|
|
|
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{filename}.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 Controlling printout
|
|
@section Controlling printout of large terms
|
|
|
|
You can control the printout of terms shown as the results of queries,
|
|
and as shown by the debugger, to a great extent. At the coarsest level,
|
|
you can limit the depth to which terms are shown, and the number of
|
|
arguments of terms (and the number of elements of lists) to be shown.
|
|
Further, you can ``hide'' some of the arguments of a term, based upon the
|
|
functor of that term. And finally, you can write your own code to print
|
|
out certain kinds of terms in a more convenient manner.
|
|
|
|
@menu
|
|
* Limiting size:: Limiting Print Depth and Length
|
|
* Hiding terms:: Hiding terms and subterms based upon term functor
|
|
* Customization:: Customizing printout by writing your own printout code
|
|
@end menu
|
|
|
|
@node Limiting size
|
|
@subsection Limiting print depth and length
|
|
|
|
You can limit the depth to which terms will be printed. When a term to
|
|
be printed appears at the depth limit, only its name and arity will be
|
|
shown, enclosed in angle brackets, for example @samp{<foo/3>}.
|
|
|
|
You can also control the number of arguments of terms, and the lengths
|
|
of lists, to be shown. When this length limit is reached, an ellipsis
|
|
mark (@samp{...}) will be printed.
|
|
|
|
The following predicates control the print depth and length limits.
|
|
|
|
@example
|
|
set_print_depth(@var{Depth})
|
|
@end example
|
|
Sets the print depth limit to @var{Depth}. If @var{Depth} is less than 0, the
|
|
print depth is unlimited. The default print depth limit is 2.
|
|
|
|
@example
|
|
print_depth(@var{Depth})
|
|
@end example
|
|
Unifies @var{Depth} with the current print depth limit.
|
|
|
|
@example
|
|
set_print_length(@var{Length})
|
|
@end example
|
|
Sets the print length limit to @var{Length}. If @var{Length} is less
|
|
than 0, the print length is unlimited.
|
|
|
|
@example
|
|
print_length(@var{Length})
|
|
@end example
|
|
Unifies @var{Length} with the current print length limit.
|
|
|
|
|
|
@node Hiding terms
|
|
@subsection Hiding terms and subterms
|
|
|
|
Sometimes you will have terms which appear frequently during debugging
|
|
and which tend to fill up the screen with lots of uninteresting text,
|
|
even with depth limits in force. In such cases, you may want to hide
|
|
terms based upon their functor, regardless of their print depth. You
|
|
may also occasionally want to hide just a few of the arguments of a
|
|
term. These predicates allow you to do that.
|
|
|
|
Note that if the @emph{top level} functor of the term to be printed is
|
|
hidden, its first level arguments will be shown anyway. This is to
|
|
avoid answer substitutions being wholly hidden, and to make it easier to
|
|
use the subterm viewing facility of the SICStus Prolog debugger (using
|
|
the @key{^} command) to view parts of a term.
|
|
|
|
|
|
@example
|
|
hide(@var{Spec})
|
|
hide(@var{Spec, Args})
|
|
@end example
|
|
Allows you to elide certain arguments of certain terms, or whole terms,
|
|
based on the functor. @var{Spec} specifies a functor; it must be either
|
|
a @var{Name}@code{/}@var{Arity} term, or just a functor name (in which
|
|
case all arities are specified). @var{Args} specifies which arguments
|
|
of such terms should be hidden. If given, @var{Args} must be a single
|
|
integer or a list of integers specifying which arguments to hide.
|
|
Hidden arguments will be printed as just a hash (@samp{#}) character.
|
|
Alternatively, @var{Args} may be the atom @code{term}, in which case
|
|
only the name and arity of the term are written within angle brackets,
|
|
(e.g., @samp{<foo/3>}). If Args is not specified, it defaults to
|
|
@code{term}.
|
|
|
|
Hidden arguments are cumulative. That is, new arguments to be hidden are
|
|
added to the set of arguments already hidden. For example, if you hide
|
|
argument 3 of all terms with functor name @samp{foo}, and then hide
|
|
argument 1 of terms with functor @samp{foo/3}, then for @samp{foo/3}
|
|
terms, arguments 1 and 3 will be hidden, while for all other terms with
|
|
functor name @samp{foo}, only argument 3 will be hidden.
|
|
|
|
@example
|
|
show
|
|
Show(@var{Spec})
|
|
show(@var{Spec, Args})
|
|
@end example
|
|
Undoes the effect of hiding some arguments of terms or whole terms.
|
|
@var{Spec} specifies a functor; it must be either a
|
|
@var{Name}@code{/}@var{Arity} term, or just a functor name (in which
|
|
case all arities are specified). @var{Args} specifies which arguments
|
|
to stop hiding; it must be a list of argument numbers or a single
|
|
argument number. Alternatively, it may be the atom @code{term},
|
|
indicating that no arguments should be hidden (the whole term should be
|
|
shown). @var{Args} defaults to @code{term}. The predicate
|
|
@code{show/0} reenables showing all arguments of all terms.
|
|
|
|
Note that these predicates will not affect the depth limit of printing.
|
|
Even if you ask to show a term in full, if it appears at the depth limit of
|
|
the term being printed, its arguments will not be shown. If it appears
|
|
below the depth limit, you won't see it at all.
|
|
|
|
You may use the @code{hide/1,2} and @code{show/2} predicates in concert
|
|
to hide most of the arguments of a term by first hiding all arguments,
|
|
and then explicitly showing the few of interest.
|
|
|
|
@example
|
|
hidden(@var{Spec, Args})
|
|
@end example
|
|
@var{Spec} is a @var{Name}@code{/}@var{Arity} term, and @var{Args} is a
|
|
list of the argument numbers of terms with that @var{Name} and
|
|
@var{Arity} which are hidden, or the atom @code{term} if the entire term
|
|
is hidden. @var{Arity} may be the atom @code{all}, indicating that the
|
|
specified arguments are hidden for all terms with that @var{Name} and
|
|
any arity. This predicate may be used to backtrack through all the
|
|
predicates which are hidden or have any arguments hidden.
|
|
|
|
|
|
@node Customization
|
|
@subsection Customization of printout
|
|
|
|
Occasionally you will have a term that is important to understand during
|
|
debugging but is shown in an inconvenient manner or may be difficult to
|
|
understand as printed. Traditionally in Prolog, you can define clauses
|
|
for the predicate @code{portray/1} to specify special code to print such
|
|
a term. Unfortunately, this won't work very well with the other
|
|
features of Mercury's printout system. For this you will need to define
|
|
clauses for the predicate @code{portray_term/3}:
|
|
|
|
@example
|
|
portray_term(@var{Term, DepthLimit, Precedence})
|
|
@end example
|
|
Like the standard Prolog @code{portray/1} hook predicate, this code
|
|
should either fail without printing anything, or succeed after printing
|
|
out Term as the user would like to see it printed. @var{DepthLimit}, if
|
|
greater than or equal to -1, is the number of levels of the subterms of
|
|
@var{Term} that should be printed without being elided. If it is -1,
|
|
then @var{Term} should probably not be printed; only a marker indicating
|
|
what sort of term it is. The standard @code{print_term/3} code will
|
|
print the name and arity of the functor enclosed in angle brackets
|
|
(e.g., <foo/3>) if @code{portray_term/3} fails at this depth level. Be
|
|
careful, though: if @var{DepthLimit} is less than -1, then there should
|
|
be no depth limit. @var{Precedence} is the precedence of the context in
|
|
which the term will be printed; if you wish to write a term with
|
|
operators, then you should parenthesize the printout if @var{Precedence}
|
|
is smaller than the precedence of that operator.
|
|
|
|
In printing subterms, you should call @code{print_term/3}, described
|
|
below. Note that the @var{DepthLimit} argument passed to portray_term/3 is
|
|
the depth limit for the @emph{subterms} of @var{Term}, so you should
|
|
usually pass this value to @code{print_term/3} for printing subterms
|
|
without decrementing it. Note also that @var{Term} will always be bound
|
|
when @code{portray_term/3} is called, so you needn't worry about
|
|
checking for unbound variables.
|
|
|
|
Mercury already supplies special-purpose printout code to print out
|
|
lists of character codes as double-quoted strings, and to print out maps
|
|
as @var{Key}@code{->}@var{Value} pairs, surrounded by @samp{MAP@{@}}.
|
|
This code appears in the file @file{portray.nl} in the Mercury library,
|
|
and may serve as a useful example of how to write customized printing
|
|
code.
|
|
|
|
@example
|
|
print_term(@var{Term, DepthLimit, Precedence})
|
|
@end example
|
|
Print out @var{Term} to the current output stream, limiting print depth
|
|
to @var{DepthLimit}, and parenthesizing the term if its principle
|
|
functor is an operator with precedence greater than @var{Precedence}.
|
|
@code{print_term/3} also respects the current set of hidden functors,
|
|
and uses the user-supplied @code{portray_term/3} hook predicate when it
|
|
succeeds.
|
|
|
|
|
|
|
|
|
|
@node Prolog hazards
|
|
@section Hazards of using Prolog
|
|
|
|
There are some Mercury programs which are not valid Prolog programs.
|
|
Programs which make use of the more advanced features of Mercury will
|
|
not work with NU-Prolog or SICStus Prolog.
|
|
In particular, Mercury programs that use functions will generally not
|
|
be valid Prolog programs (with the exception that the basic arithmetic
|
|
functions such as @samp{+}, @samp{-}, etc., will work fine if you use
|
|
Prolog's @samp{is} predicate).
|
|
Also the use of features such as type classes, lambda expressions,
|
|
non-trivial use of the module system, etc. will cause problems.
|
|
|
|
Also, 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 might 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} or @samp{Mmakefile} 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{.err} files.
|
|
|
|
@item @var{main-module}.split
|
|
Compiles and links @var{main-module} using the Mercury compiler,
|
|
with the Mercury compiler's @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 lib@var{main-module}
|
|
Builds a library whose top-level module is @var{main-module}.
|
|
This will build a static object library, a shared object library
|
|
(for platforms that support it), and the necessary interface files.
|
|
@xref{Libraries} for more information.
|
|
|
|
@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}, and @samp{.err} files
|
|
belonging to the named @var{main-module} or its imported modules.
|
|
|
|
@item @var{main-module}.change_clean
|
|
Removes files that need updating when changing compilation model
|
|
(@pxref{Compilation model options}) or
|
|
when enabling inter-module optimization.
|
|
Specifically, this will remove all the @samp{.c}, @samp{.s}, @samp{.o},
|
|
@samp{.dep} and executable 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{.int}, @samp{.int0}, @samp{.int2},
|
|
@samp{.int3}, @samp{.opt}, @samp{.trans_opt},
|
|
@samp{.date}, @samp{.date0}, @samp{.date3}, @samp{.optdate},
|
|
@samp{.trans_opt_date},
|
|
@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 (and their default values) are
|
|
defined in the file @file{@var{prefix}/lib/mercury/mmake/Mmake.vars}, however
|
|
these may be overridden by user @samp{Mmake} files. Some of the more
|
|
useful variables are:
|
|
|
|
@table @code
|
|
|
|
@item MAIN_TARGET
|
|
The name of the default target to create if @samp{mmake} is invoked with
|
|
any target explicitly named on the command line.
|
|
|
|
@item MC
|
|
The executable that invokes the Mercury compiler.
|
|
|
|
@item MCFLAGS and EXTRA_MCFLAGS
|
|
Flags to pass to the Mercury compiler.
|
|
|
|
@item MGNUC
|
|
The executable that invokes the C compiler.
|
|
|
|
@item MGNUCFLAGS and EXTRA_MGNUCFLAGS
|
|
Flags to pass to the C compiler.
|
|
|
|
@item ML
|
|
The executable that invokes the linker.
|
|
|
|
@item MLFLAGS and EXTRA_MLFLAGS
|
|
Flags to pass to the linker.
|
|
|
|
@item MLLIBS
|
|
A list of @samp{-l} options specifying libraries used by the program
|
|
(or library) that you are building. @xref{Using libraries}.
|
|
|
|
@item MLOBJS
|
|
A list of extra object files to link into any programs or libraries
|
|
that you are building.
|
|
@end table
|
|
|
|
Other variables also exist - see
|
|
@file{@var{prefix}/lib/mercury/mmake/Mmake.vars} for a complete list.
|
|
|
|
If you wish to temporarily change the flags passed to an executable,
|
|
rather than setting the various @samp{FLAGS} variables directly, one can
|
|
supply a @samp{EXTRA_} variable. When defining a @samp{FLAGS} option
|
|
directly (in your own @samp{Mmake} file), it is recommended you include
|
|
the @samp{EXTRA_} version at the end. This is particularly intended for
|
|
use where a shell script needs to call mmake and add an extra parameter,
|
|
without interfering with the flag settings in the @samp{Mmake} file.
|
|
|
|
@example
|
|
MCFLAGS = -O6 $(EXTRA_MCFLAGS)
|
|
@end example
|
|
|
|
Note that since Mmake is built on top of Make or GNU Make,
|
|
you can make use of the features supported by the underlying Make.
|
|
In particular, GNU Make has support for running jobs in parallel,
|
|
which is very useful if you have a machine with more than one CPU.
|
|
|
|
@node Libraries
|
|
@chapter Libraries
|
|
|
|
Often you will want to use a particular set of Mercury modules
|
|
in more than one program. The Mercury implementation
|
|
includes support for developing libraries, i.e. sets of Mercury modules
|
|
intended for reuse. It allows separate compilation of libraries
|
|
and, on many platforms, it supports shared object libraries.
|
|
|
|
@menu
|
|
* Writing libraries::
|
|
* Building libraries::
|
|
* Installing libraries::
|
|
* Using libraries::
|
|
@end menu
|
|
|
|
@node Writing libraries
|
|
@section Writing libraries
|
|
|
|
A Mercury library is identified by a top-level module,
|
|
which should contain all of the modules in that library as sub-modules.
|
|
It may be as simple as this @file{mypackage.m} file:
|
|
|
|
@example
|
|
:- module mypackage.
|
|
:- interface
|
|
:- include_module foo, bar, baz.
|
|
@end example
|
|
|
|
@noindent
|
|
This defines a module @samp{mypackage} containing
|
|
sub-modules @samp{mypackage:foo}, @samp{mypackage:bar},
|
|
and @samp{mypackage:baz}.
|
|
|
|
It is also possible to build libraries of unrelated
|
|
modules, so long as the top-level module imports all
|
|
the necessary modules. For example:
|
|
|
|
@example
|
|
:- module blah.
|
|
:- import_module fee, fie, foe, fum.
|
|
@end example
|
|
|
|
@noindent
|
|
This example defines a module @samp{blah}, which has
|
|
no functionality of its own, and which is just used
|
|
for grouping the unrelated modules @samp{fee},
|
|
@samp{fie}, @samp{foe}, and @samp{fum}.
|
|
|
|
Generally it is better style for each library to consist
|
|
of a single module which encapsulates its sub-modules,
|
|
as in the first example, rather than just a group of
|
|
unrelated modules, as in the second example.
|
|
|
|
@node Building libraries
|
|
@section Building libraries
|
|
|
|
Generally Mmake will do most of the work of building
|
|
libraries automatically. Here's a sample @code{Mmakefile} for
|
|
creating a library.
|
|
|
|
@example
|
|
MAIN_TARGET = libmypackage
|
|
depend: mypackage.depend
|
|
@end example
|
|
|
|
The Mmake target @samp{lib@var{foo}} is a built-in target for
|
|
creating a library whose top-level module is @samp{@var{foo}.m}.
|
|
The automatically generated Make rules for the target @samp{lib@var{foo}}
|
|
will create all the files needed to use the library.
|
|
|
|
Mmake will create static (non-shared) object libraries
|
|
and, on most platforms, shared object libraries;
|
|
however, we do not yet support the creation of dynamic link
|
|
libraries (DLLs) on Windows.
|
|
Static libraries are created using the standard tools @samp{ar}
|
|
and @samp{ranlib}.
|
|
Shared libraries are created using the @samp{--make-shared-lib}
|
|
option to @samp{ml}.
|
|
The automatically-generated Make rules for @samp{libmypackage}
|
|
will look something like this:
|
|
|
|
@example
|
|
libmypackage: libmypackage.a libmypackage.so \
|
|
$(mypackage.ints) $(mypackage.opts) mypackage.init
|
|
|
|
libmypackage.a: $(mypackage.os)
|
|
rm -f libmypackage.a
|
|
$(AR) $(ARFLAGS) libmypackage.a $(mypackage.os) $(MLOBJS)
|
|
$(RANLIB) $(RANLIBFLAGS) mypackage.a
|
|
|
|
libmypackage.so: $(mypackage.pic_os)
|
|
$(ML) $(MLFLAGS) --make-shared-lib -o libmypackage.so \
|
|
$(mypackage.pic_os) $(MLPICOBJS) $(MLLIBS)
|
|
|
|
libmypackage.init:
|
|
...
|
|
|
|
clean:
|
|
rm -f libmypackage.a libmypackage.so
|
|
@end example
|
|
|
|
If necessary, you can override the default definitions of the variables
|
|
such as @samp{ML}, @samp{MLFLAGS}, @samp{MLPICOBJS}, and @samp{MLLIBS}
|
|
to customize the way shared libraries are built. Similarly @samp{AR},
|
|
@samp{ARFLAGS}, @samp{MLOBJS}, @samp{RANLIB}, and @samp{RANLIBFLAGS}
|
|
control the way static libraries are built. (The @samp{MLOBJS} variable
|
|
is supposed to contain a list of additional object files to link into
|
|
the library, while the @samp{MLLIBS} variable should contain a list of
|
|
@samp{-l} options naming other libraries used by this library.
|
|
@samp{MLPICOBJS} is described below.)
|
|
|
|
Note that to use a library, as well as the shared or static object library,
|
|
you also need the interface files. That's why the
|
|
@samp{libmypackage} target builds @samp{$(mypackage.ints)}.
|
|
If the people using the library are going to use intermodule
|
|
optimization, you will also need the intermodule optimization interfaces.
|
|
That's why the @samp{libmypackage} target builds @samp{$(mypackage.opts)}.
|
|
If the people using the library are going to use transitive intermodule
|
|
optimization, you will also need the transitive intermodule optimization
|
|
interfaces. Currently these are @emph{not} built by default; if
|
|
you want to build them, you will need to include @samp{--trans-intermod-opt}
|
|
in your @samp{MCFLAGS} variable.
|
|
|
|
In addition, with certain compilation grades, programs will need to
|
|
execute some startup code to initialize the library; the
|
|
@samp{mypackage.init} file contains information about initialization
|
|
code for the library. The @samp{libmypackage} target will build this file.
|
|
|
|
On some platforms, shared objects must be created using position independent
|
|
code (PIC), which requires passing some special options to the C compiler.
|
|
On these platforms, @code{Mmake} will create @file{.pic_o} files,
|
|
and @samp{$(mypackage.pic_os)} will contain a list of the @file{.pic_o} files
|
|
for the library whose top-level module is @samp{mypackage}.
|
|
In addition, @samp{$(MLPICOBJS)} will be set to @samp{$MLOBJS} with
|
|
all occurrences of @samp{.o} replaced with @samp{.pic_o}.
|
|
On other platforms, position independent code is the default,
|
|
so @samp{$(mypackage.pic_os)} will just be the same as @samp{$(mypackage.os)},
|
|
which contains a list of the @file{.o} files for that module,
|
|
and @samp{$(MLPICOBJS)} will be the same as @samp{$(MLOBJS)}.
|
|
|
|
@node Installing libraries
|
|
@section Installing libraries
|
|
|
|
If you want, once you have built a library, you could then install
|
|
(i.e. copy) the shared object library, the static object library,
|
|
the interface files (possibly including the optimization interface
|
|
files and the transitive optimization interface files), and the
|
|
initialization file into a different directory, or into several
|
|
different directories, for that matter --- though it is probably
|
|
easiest for the users of the library if you keep them in a single
|
|
directory.
|
|
Or alternatively, you could package them up into a @samp{tar}, @samp{shar}, or
|
|
@samp{zip} archive and ship them to the people who will use the
|
|
library.
|
|
|
|
@node Using libraries
|
|
@section Using libraries
|
|
|
|
To use a library, you need to set the Mmake variables @samp{VPATH},
|
|
@samp{MCFLAGS}, @samp{MLFLAGS}, @samp{MLLIBS}, and @samp{C2INITFLAGS}
|
|
to specify the name and location of the library or libraries that you
|
|
wish to use. If you are using @samp{--intermodule-optimization}, you
|
|
may also need to set @samp{MGNUCFLAGS} if the library uses the C interface.
|
|
For example, if you want to link in the libraries @samp{mypackage} and
|
|
@samp{myotherlib}, which were built in the directories
|
|
@samp{/some/directory/mypackage} and @samp{/some/directory/myotherlib}
|
|
respectively, you could use the following settings:
|
|
|
|
@example
|
|
# Specify the location of the `mypackage' and `myotherlib' directories
|
|
MYPACKAGE_DIR = /some/directory/mypackage
|
|
MYOTHERLIB_DIR = /some/directory/myotherlib
|
|
|
|
# The following stuff tells Mmake to use the two libraries
|
|
VPATH = $(MYPACKAGE_DIR):$(MYOTHERLIB_DIR):$(MMAKE_VPATH)
|
|
MCFLAGS = -I$(MYPACKAGE_DIR) -I$(MYOTHERLIB_DIR) $(EXTRA_MCFLAGS)
|
|
MLFLAGS = -R$(MYPACKAGE_DIR) -R$(MYOTHERLIB_DIR) $(EXTRA_MLFLAGS) \
|
|
-L$(MYPACKAGE_DIR) -L$(MYOTHERLIB_DIR)
|
|
MLLIBS = -lmypackage -lmyotherlib $(EXTRA_MLLIBS)
|
|
C2INITFLAGS = $(MYPACKAGE_DIR)/mypackage.init \
|
|
$(MYOTHERLIB_DIR)/myotherlib.init
|
|
|
|
# This line may be needed if @samp{--intermodule-optimization}
|
|
# is in @samp{MCFLAGS}. @samp{-I} options should be added for any other
|
|
# directories containing header files that the libraries require.
|
|
MGNUCFLAGS = -I$(MYPACKAGE_DIR) -I$(MYOTHERLIB_DIR) $(EXTRA_MGNUCFLAGS)
|
|
@end example
|
|
|
|
Here @samp{VPATH} is a colon-separated list of path names specifying
|
|
directories that Mmake will search for interface files.
|
|
The @samp{-I} options in @samp{MCFLAGS} tell @samp{mmc} where to find
|
|
the interface files. The @samp{-R} options in @samp{MLFLAGS} tell
|
|
the loader where to find shared libraries, and the @samp{-L}
|
|
options tell the linker where to find libraries.
|
|
(Note that the @samp{-R} options must precede the @samp{-L} options.)
|
|
The @samp{-l} options tell the linker which libraries to link with.
|
|
The extra arguments to @samp{c2init} specified in the @samp{C2INITLFLAGS}
|
|
variable tell @samp{c2init} where to find the @samp{.init} files for the
|
|
libraries, so that it can generate appropriate initialization code.
|
|
The @samp{-I} options in @samp{MGNUCFLAGS} tell the C preprocessor where
|
|
to find the header files for the libraries.
|
|
|
|
The example above assumes that the static object library,
|
|
shared object library, interface files and initialization file
|
|
for each Mercury library being used are all put in a single directory,
|
|
which is probably the simplest way of organizing things, but the
|
|
Mercury implementation does not require that.
|
|
|
|
@node Profiling
|
|
@chapter Profiling
|
|
|
|
@menu
|
|
* Profiling introduction:: What is profiling useful for?
|
|
* Building profiled applications:: How to enable profiling.
|
|
* Time profiling methods:: Choose user, user + system, or real time.
|
|
* 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.
|
|
* Memory profiling:: Profiling memory usage rather than time.
|
|
@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 or functions 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 with profiling enabled.
|
|
This can be done by passing the @samp{-p} (@samp{--profiling}) option
|
|
to @samp{mmc} (and also to @samp{mgnuc} and @samp{ml}, if you invoke them
|
|
seperately). If you are using Mmake, then
|
|
you can do this by setting the @samp{GRADEFLAGS} variable in your Mmakefile,
|
|
e.g. by adding the line @samp{GRADEFLAGS=--profiling}.
|
|
@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 or function is called, and for every 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 Time profiling methods
|
|
@section Time profiling methods
|
|
|
|
By setting the environment variable MERCURY_OPTIONS,
|
|
which is used for passing options to the Mercury runtime system,
|
|
you can control how the Mercury profiler measures the time spent.
|
|
The default (@samp{-Tp}) is to count time spent executing the process,
|
|
including time spent by the system performing operations on behalf of
|
|
the process, but not including time that the process was suspended
|
|
(e.g. due to time slicing, or while waiting for input).
|
|
Using @samp{-Tv} counts only time spent executing the process.
|
|
Using @samp{-Tr} counts all elapsed time, even including time that
|
|
the process was suspended.
|
|
|
|
@table @asis
|
|
@item @samp{-Tr}
|
|
Profile real (elapsed) time (using ITIMER_REAL).
|
|
@item @samp{-Tv}
|
|
Profile user time (using ITIMER_VIRTUAL).
|
|
@item @samp{-Tp}
|
|
Profile user time plus system time (using ITIMER_PROF).
|
|
This is the default.
|
|
@end table
|
|
|
|
Currently, the @samp{-Tv} and @samp{-Tp} options don't work on Windows,
|
|
so on Windows you must explicitly specify @samp{-Tr}.
|
|
|
|
@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 @file{Prof.Counts}, @file{Prof.Decls},
|
|
and @file{Prof.CallPair}.
|
|
(@file{Prof.Decl} contains the names of the procedures and their
|
|
associated addresses, @file{Prof.CallPair} records the number of times
|
|
each procedure was called by each different caller, and @file{Prof.Counts}
|
|
records the number of times that execution was in each procedure
|
|
when a profiling interrupt occurred.)
|
|
|
|
It is also possible to combine profiling results from multiple runs of
|
|
your program. You can do by running your program several times, and
|
|
typing @samp{mprof_merge_counts} after each run.
|
|
|
|
Due to a known timing-related bug in our code, you may occasionally get
|
|
segmentation violations when running your program with time profiling enabled.
|
|
If this happens, just run it again --- the problem occurs only very rarely.
|
|
|
|
@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
|
|
procedure. For each procedure it shows the parents (callers) and
|
|
children (callees) of that procedure, 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 procedure and all of its descendents (i.e.
|
|
all of the procedures that it calls, directly or indirectly.)
|
|
|
|
The flat profile presents the just execution time spent in each procedure.
|
|
It does not count the time spent in descendents of a procedure.
|
|
|
|
The alphabetic listing just lists the procedures in alphabetical order,
|
|
along with their index number in the call graph profile, so that you can
|
|
quickly find the entry for a particular procedure in the call graph profile.
|
|
|
|
The profiler works by interrupting the program at frequent intervals,
|
|
and each time recording the currently active procedure and its caller.
|
|
It uses these counts to determine the proportion of the total time spent in
|
|
each procedure. 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 procedure and its descendents is calculated by
|
|
propagating the times up the call graph, assuming that each call to a
|
|
procedure 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 Mercury procedure 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
|
|
|
|
<spontaneous>
|
|
[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{<spontaneous>}, 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
|
|
procedures, the current procedure and the children procedures.
|
|
|
|
Reading across from the left, for the current procedure the fields are:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The unique index number for the current procedure.
|
|
(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 procedure
|
|
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 procedure.
|
|
As noted above, this is only a statistical approximation.
|
|
|
|
@item
|
|
The descendent time: the time spent in the
|
|
current procedure and all its descendents.
|
|
As noted above, this is only a statistical approximation.
|
|
|
|
@item
|
|
The number of times a procedure is called.
|
|
If a procedure is (directly) recursive, this column
|
|
will contain the number of calls from other procedures,
|
|
a plus sign, and then the number of recursive calls.
|
|
These numbers are exact, not approximate.
|
|
|
|
@item
|
|
The name of the procedure followed by its index number.
|
|
@end itemize
|
|
|
|
The predicate or function 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 procedures the self and descendent time have
|
|
slightly different meanings. For the parent procedures the self and descendent
|
|
time represent the proportion of the current procedure'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 procedure.
|
|
|
|
@node Memory profiling
|
|
@section Memory profiling
|
|
|
|
It is also possible to profile memory allocation. To enable memory
|
|
profiling, your program must be built with memory profiling enabled,
|
|
using the @samp{--memory-profiling} option. Then, as with time
|
|
profiling, you run your program to create the profiling data.
|
|
This will be stored in the files @file{Prof.MemoryWords}
|
|
@file{Prof.MemoryCells}, @file{Prof.Decls}, and @file{Prof.CallPair}.
|
|
|
|
To create the profile, you need to invoke @samp{mprof} with the
|
|
@samp{-m} (@samp{--profile memory-words}) option. This will profile
|
|
the amount of memory allocated, measured in units of words.
|
|
(A word is 4 bytes on a 32-bit architecture, and 8 bytes on a 64-bit
|
|
architecture.)
|
|
|
|
Alternatively, you can use @samp{mprof}'s @samp{-M}
|
|
(@samp{--profile memory-cells}) option. This will profile memory in
|
|
units of ``cells''. A cell is a group of words allocated together in a
|
|
single allocation, to hold a single object. Selecting this option this
|
|
will therefore profile the number of memory allocations, while ignoring
|
|
the size of each memory allocation.
|
|
|
|
With memory profiling, just as with time profiling,
|
|
you can use the @samp{-c} (@samp{--call-graph}) option to display
|
|
call graph profiles in addition to flat profiles.
|
|
|
|
Note that Mercury's memory profiler will only tell you about
|
|
allocation, not about deallocation (garbage collection).
|
|
It can tell you how much memory was allocated by each procedure,
|
|
but it won't tell you how long the memory was live for,
|
|
or how much of that memory was garbage-collected.
|
|
|
|
@node Invocation
|
|
@chapter Invocation
|
|
|
|
This section contains a brief description of all the options
|
|
available for @samp{mmc}, the Mercury compiler.
|
|
Sometimes this list is a little out-of-date;
|
|
use @samp{mmc --help} to get the most up-to-date list.
|
|
|
|
@menu
|
|
* Invocation overview::
|
|
* Verbosity options::
|
|
* Warning options::
|
|
* Output options::
|
|
* Auxiliary output options::
|
|
* Language semantics options::
|
|
* Termination analysis options::
|
|
* Compilation model options::
|
|
* Code generation options::
|
|
* Optimization options::
|
|
* Link options::
|
|
* Miscellaneous options::
|
|
@end menu
|
|
|
|
@node Invocation overview
|
|
@section Invocation overview
|
|
|
|
@code{mmc} is invoked as
|
|
@example
|
|
mmc [@var{options}] @var{arguments}
|
|
@end example
|
|
|
|
Arguments can be either module names or file names.
|
|
Arguments ending in @samp{.m} are assumed to be file names,
|
|
while other arguments are assumed to be module names.
|
|
If you specify a module name such as @samp{foo.bar.baz},
|
|
the compiler will look for the source in files @file{foo.bar.baz.m},
|
|
@file{bar.baz.m}, and @file{baz.m}, in that order.
|
|
|
|
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, functions, insts, modes or types.
|
|
|
|
@sp 1
|
|
@item --warn-unused-args
|
|
Warn about predicate or function arguments which are not used.
|
|
|
|
@sp 1
|
|
@item --warn-interface-imports
|
|
Warn about modules imported in the interface which are not
|
|
used in the interface.
|
|
|
|
@sp 1
|
|
@item --warn-missing-opt-files
|
|
Warn about @samp{.opt} files that cannot be opened.
|
|
|
|
@sp 1
|
|
@item --warn-non-stratification
|
|
Warn about possible non-stratification of the predicates/functions in the
|
|
module.
|
|
Non-stratification occurs when a predicate/function can call itself
|
|
negatively through some path along its call graph.
|
|
|
|
@sp 1
|
|
@item --no-warn-simple-code
|
|
Disable warnings about constructs which are so
|
|
simple that they are likely to be programming errors.
|
|
|
|
@sp 1
|
|
@item --warn-duplicate-calls
|
|
Warn about multiple calls to a predicate with the same
|
|
input arguments.
|
|
|
|
@sp 1
|
|
@item --no-warn-missing-module-name
|
|
Disable warnings for modules that do not start with a
|
|
@samp{:- module} declaration.
|
|
|
|
@sp 1
|
|
@item --no-warn-wrong-module-name
|
|
Disable warnings for modules whose @samp{:- module} declaration
|
|
does not match the module's file name.
|
|
|
|
@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-det, --debug-determinism
|
|
Output detailed debugging traces of determinism analysis.
|
|
|
|
@sp 1
|
|
@item --debug-opt
|
|
Output detailed debugging traces of the optimization process.
|
|
|
|
@sp 1
|
|
@item --debug-vn <n>
|
|
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}.
|
|
|
|
@item --generate-module-order
|
|
Output the strongly connected components of the module
|
|
dependency graph in top-down order to @file{@var{module}.order}.
|
|
Implies @samp{--generate-dependencies}.
|
|
|
|
@sp 1
|
|
@item -i
|
|
@itemx --make-int
|
|
@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 --make-short-int
|
|
@itemx --make-short-interface
|
|
Write the unqualified version of the short interface to
|
|
@file{@var{module}.int3}.
|
|
|
|
@sp 1
|
|
@item --make-priv-int
|
|
@itemx --make-private-interface
|
|
Write the module's private interface (used for compiling
|
|
nested sub-modules) to @file{@var{module}.int0}.
|
|
|
|
@sp 1
|
|
@item --make-opt-int
|
|
@itemx --make-optimization-interface
|
|
Write information used for inter-module optimization to
|
|
@file{@var{module}.opt}.
|
|
|
|
@sp 1
|
|
@item --make-trans-opt
|
|
@itemx --make-transitive-optimization-interface
|
|
Write the @file{@var{module}.trans_opt} file. This file is used to store
|
|
information used for inter-module optimization. The information is read
|
|
in when the compiler is invoked with the
|
|
@samp{--transitive-intermodule-optimization} option.
|
|
The file is called the ``transitive'' optimization interface file
|
|
because a @samp{.trans_opt} file may depend on other
|
|
@samp{.trans_opt} and @samp{.opt} files. In contrast,
|
|
a @samp{.opt} file can only hold information derived directly
|
|
from the corresponding @samp{.m} file.
|
|
|
|
@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 --no-assume-gmake
|
|
When generating @file{.dep} files, generate Makefile
|
|
fragments that use only the features of standard make;
|
|
do not assume the availability of GNU Make extensions.
|
|
This makes these files significantly larger.
|
|
|
|
@item --trace @var{level}
|
|
Generate code that includes the specified level of execution tracing.
|
|
The @var{level} should be one of
|
|
@samp{minimum}, @samp{interfaces} and @samp{all}.
|
|
@c XXX should include a pointer here to the as-yet-unwritten
|
|
@c section on debugging
|
|
|
|
@item --generate-bytecode
|
|
@c Output a bytecode version of the module
|
|
@c into the @file{@var{module}.bytecode} file,
|
|
@c and a human-readable version of the bytecode
|
|
@c into the @file{@var{module}.bytedebug} file.
|
|
@c The bytecode is for an experimental debugger.
|
|
Output a bytecode form of the module for use
|
|
by an experimental debugger.
|
|
|
|
@item --generate-prolog
|
|
Convert the program to Prolog. Output to file @file{@var{module}.pl}
|
|
or @file{@var{module}.nl} (depending the the dialect).
|
|
|
|
@item --prolog-dialect @var{dialect}
|
|
Target the named dialect if generating Prolog code.
|
|
The @var{dialect} should be one of @samp{sicstus}, @samp{nu}.
|
|
|
|
@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.
|
|
This option only works in conjunction 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 @var{fields}
|
|
@itemx --verbose-dump-hlds @var{fields}
|
|
With @samp{--dump-hlds}, include extra detail in the dump.
|
|
Each type of detail is included in the dump
|
|
if its corresponding letter occurs in the option argument.
|
|
These details are:
|
|
a - argument modes in unifications,
|
|
b - builtin flags on calls,
|
|
c - contexts of goals and types,
|
|
d - determinism of goals,
|
|
f - follow_vars sets of goals,
|
|
i - instmap deltas of goals,
|
|
l - pred/mode ids and unify contexts of called predicates,
|
|
n - nonlocal variables of goals,
|
|
p - pre-birth, post-birth, pre-death and post-death sets of goals,
|
|
r - resume points of goals,
|
|
s - store maps of goals,
|
|
t - results of termination analysis,
|
|
u - unification categories,
|
|
v - variable numbers in variable names,
|
|
T - type and typeclass information,
|
|
M - mode and inst information,
|
|
C - clause information,
|
|
U - unify predicates,
|
|
P - path information.
|
|
The special argument value ``all''
|
|
will cause the printing of all these fields.
|
|
|
|
@end table
|
|
|
|
@node Language semantics options
|
|
@section Language semantics options
|
|
|
|
See the Mercury language reference manual for detailed explanations
|
|
of these options.
|
|
|
|
@table @code
|
|
@item --no-reorder-conj
|
|
Execute conjunctions left-to-right except where the modes imply
|
|
that reordering is unavoidable.
|
|
|
|
@sp 1
|
|
@item --no-reorder-disj
|
|
Execute disjunctions strictly left-to-right.
|
|
|
|
@sp 1
|
|
@item --fully-strict
|
|
Don't optimize away loops or calls to @code{error/1}.
|
|
|
|
@sp 1
|
|
@item --infer-types
|
|
If there is no type declaration for a predicate or function,
|
|
try to infer the type, rather than just reporting an error.
|
|
|
|
@sp 1
|
|
@item --infer-modes
|
|
If there is no mode declaration for a predicate,
|
|
try to infer the modes, rather than just reporting an error.
|
|
|
|
@sp 1
|
|
@item --no-infer-det, --no-infer-determinism
|
|
If there is no determinism declaration for a procedure,
|
|
don't try to infer the determinism, just report an error.
|
|
|
|
@sp 1
|
|
@item --type-inference-iteration-limit @var{n}
|
|
Perform at most @var{n} passes of mode inference (default: 60).
|
|
|
|
@sp 1
|
|
@item --mode-inference-iteration-limit @var{n}
|
|
Perform at most @var{n} passes of mode inference (default: 30).
|
|
@end table
|
|
|
|
@node Termination analysis options
|
|
@section Termination analysis options
|
|
|
|
For detailed explanations, see the ``Termination analysis'' section
|
|
in Mercury Language Reference Manual. (It is listed under
|
|
``Implementation dependent pragmas'' in the ``Pragmas'' chapter.)
|
|
|
|
@table @code
|
|
@item --enable-term
|
|
@itemx --enable-termination
|
|
Enable termination analysis. Termination analysis analyses each mode of
|
|
each predicate to see whether it terminates. The @samp{terminates},
|
|
@samp{does_not_terminate} and @samp{check_termination}
|
|
pragmas have no effect unless termination analysis is enabled. When
|
|
using termination, @samp{--intermodule-optimization} should be enabled,
|
|
as it greatly improves the accuracy of the analysis.
|
|
|
|
@sp 1
|
|
@item --chk-term
|
|
@itemx --check-term
|
|
@itemx --check-termination
|
|
Enable termination analysis, and emit warnings for some predicates or
|
|
functions that cannot be proved to terminate. In many cases in which the
|
|
compiler is unable to prove termination, the problem is either a lack of
|
|
information about the termination properties of other predicates, or the
|
|
fact that the program used language constructs (such as higher order
|
|
calls) which cannot be analysed. In these cases the compiler does
|
|
not emit a warning of non-termination, as it is likely to be spurious.
|
|
|
|
@sp 1
|
|
@item --verb-chk-term
|
|
@itemx --verb-check-term
|
|
@itemx --verbose-check-termination
|
|
Enable termination analysis, and emit warnings for all predicates or
|
|
functions that cannot be proved to terminate.
|
|
|
|
@sp 1
|
|
@item --term-single-arg @var{limit}
|
|
@itemx --termination-single-argument-analysis @var{limit}
|
|
When performing termination analysis, try analyzing
|
|
recursion on single arguments in strongly connected
|
|
components of the call graph that have up to @var{limit} procedures.
|
|
Setting this limit to zero disables single argument analysis.
|
|
|
|
@sp 1
|
|
@item --termination-norm @var{norm}
|
|
The norm defines how termination analysis measures the size
|
|
of a memory cell. The @samp{simple} norm says that size is always one.
|
|
The @samp{total} norm says that it is the number of words in the cell.
|
|
The @samp{num-data-elems} norm says that it is the number of words in
|
|
the cell that contain something other than pointers to cells of
|
|
the same type.
|
|
|
|
@sp 1
|
|
@item --term-err-limit @var{limit}
|
|
@itemx --termination-error-limit @var{limit}
|
|
Print at most @var{n} reasons for any single termination error.
|
|
|
|
@sp 1
|
|
@item --term-path-limit @var{limit}
|
|
@itemx --termination-path-limit @var{limit}
|
|
Perform termination analysis only on predicates with at most @var{n} paths.
|
|
|
|
@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.
|
|
(Attempting to link object files compiled with different
|
|
settings of these options will generally result in an error at
|
|
link time, typically of the form @samp{undefined symbol MR_grade_@dots{}}
|
|
or @samp{symbol MR_runtime_grade multiply defined}.)
|
|
|
|
The options below must be passed to @samp{mgnuc} and @samp{ml} as well
|
|
as to @samp{mmc}. If you are using Mmake, then you should specify
|
|
these options in the @samp{GRADEFLAGS} variable rather than specifying
|
|
them in @samp{MCFLAGS}, @samp{MGNUCFLAGS}, and @samp{MLFLAGS}.
|
|
|
|
@table @asis
|
|
@item @code{-s @var{grade}}
|
|
@itemx @code{--grade @var{grade}}
|
|
Select the compilation model. The @var{grade} should be a base
|
|
grade with zero or more grade modifiers appended.
|
|
The base grades are @samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump},
|
|
@samp{fast}, and @samp{asm_fast}.
|
|
The grade modifiers are @samp{.gc}, @samp{.prof}, @samp{.proftime},
|
|
@samp{.profcalls}, @samp{.tr}, and @samp{.debug}. The @samp{.prof},
|
|
@samp{.proftime}, and @samp{.profcalls} grade modifiers are mutually
|
|
exclusive; only one of those three may be specified.
|
|
If a grade includes more than one grade modifier,
|
|
the grade modifiers must be given in the same order as the
|
|
order they are listed here.
|
|
|
|
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 environment variable @samp{MERCURY_DEFAULT_GRADE} 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 error message will typically be something like
|
|
@samp{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.
|
|
|
|
@table @asis
|
|
@item @var{Grade}
|
|
@var{Options implied}.
|
|
|
|
@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 --gcc-nonlocal-gotos}.
|
|
|
|
@item @samp{asm_jump}
|
|
@code{--gcc-nonlocal-gotos --asm-labels}.
|
|
|
|
@item @samp{asm_fast}
|
|
@code{--gcc-global-registers --gcc-nonlocal_gotos --asm-labels}.
|
|
|
|
@end table
|
|
|
|
@table @asis
|
|
@item @var{Grade modifier}
|
|
@var{Options implied}.
|
|
|
|
@item @samp{.gc}
|
|
@code{--gc conservative}.
|
|
|
|
@item @samp{.prof}
|
|
@code{--profiling}.
|
|
|
|
@item @samp{.memprof}
|
|
@code{--memory-profiling}.
|
|
|
|
@c The following are undocumented because
|
|
@c they are basically useless... documenting
|
|
@c them would just confuse people.
|
|
@c
|
|
@c @item @samp{.profall}
|
|
@c @code{--profile-calls --profile-time --profile-memory}.
|
|
@c (not recommended because --profile-memory interferes with
|
|
@c --profile-time)
|
|
@c
|
|
@c @item @samp{.proftime}
|
|
@c @code{--profile-time}.
|
|
@c
|
|
@c @item @samp{.profcalls}
|
|
@c @code{--profile-calls}.
|
|
@c
|
|
@item @samp{.tr}
|
|
@code{--use-trail}.
|
|
|
|
@item @samp{.debug}
|
|
@code{--debug}.
|
|
|
|
@end table
|
|
|
|
@sp 1
|
|
@item @code{--gcc-global-registers} (grades: reg, fast, asm_fast)
|
|
@itemx @code{--no-gcc-global-registers} (grades: 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: 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: 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.
|
|
Grades containing @samp{.gc} 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{--profiling}, @code{--time-profiling} (grades: any grade containing @samp{.prof})
|
|
Enable time 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}.
|
|
|
|
@sp 1
|
|
@item @code{--memory-profiling} (grades: any grade containing @samp{.memprof})
|
|
Enable memory profiling. Insert memory profiling hooks in the
|
|
generated code, and also output some profiling
|
|
information (the static call graph) to the file
|
|
@samp{@var{module}.prof}. @xref{Memory profiling}.
|
|
|
|
@ignore
|
|
The following are basically useless, hence undocumented.
|
|
|
|
@sp 1
|
|
@item @code{--profile-calls} (grades: any grade containing @samp{.profcalls})
|
|
Similar to @samp{--profiling}, except that this option only gathers
|
|
call counts, not timing information. Useful on systems where time
|
|
profiling is not supported -- but not as useful as @samp{--memory-profiling}.
|
|
|
|
@sp 1
|
|
@item @code{--profile-time} (grades: any grade containing @samp{.proftime})
|
|
Similar to @samp{--profiling}, except that this option only gathers
|
|
timing information, not call counts. For the results to be useful,
|
|
call counts for an identical run of your program need to be gathered
|
|
using @samp{--profiling} or @samp{--profile-calls}.
|
|
XXX this doesn't work, because the code addresses change.
|
|
The only advantage of using @samp{--profile-time} and @samp{--profile-calls}
|
|
to gather timing information and call counts in seperate runs,
|
|
rather than just using @samp{--profiling} to gather them both at once,
|
|
is that the former method can give slightly more accurate timing results.
|
|
because with the latter method the code inserted to record call counts
|
|
has a small effect on the execution speed.
|
|
|
|
@end ignore
|
|
|
|
@sp 1
|
|
@item @code{--debug} (grades: any grade containing @samp{.debug})
|
|
Enable debugging.
|
|
|
|
To try this out, compile your program with @samp{--debug},
|
|
run @samp{mdb @var{program}}, and then type @samp{h}
|
|
at the @samp{mdb} prompt.
|
|
|
|
XXX We should document this in more detail.
|
|
|
|
@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, which is the default,
|
|
generally leads to more efficient code.
|
|
|
|
@sp 1
|
|
@item @code{--no-type-layout}
|
|
(This option is not intended for general use.)
|
|
Don't output base_type_layout structures or references to them.
|
|
This option will generate smaller executables, but will not allow the
|
|
use of code that uses the layout information (e.g. @samp{functor},
|
|
@samp{arg}). Using such code will result in undefined behaviour at
|
|
runtime. The C code also needs to be compiled with
|
|
@samp{-DNO_TYPE_LAYOUT}.
|
|
|
|
@sp 1
|
|
@item @code{--pic-reg} (grades: any grade containing `.pic_reg')
|
|
[For Unix with intel x86 architecture only.]
|
|
Select a register usage convention that is compatible
|
|
with position-independent code (gcc's `-fpic' option).
|
|
This is necessary when using shared libraries on Intel x86 systems
|
|
running Unix. On other systems it has no effect.
|
|
|
|
@end table
|
|
|
|
@node Code generation options
|
|
@section Code generation options
|
|
|
|
@table @code
|
|
@item @code{--low-level-debug}
|
|
Enables various low-level debugging stuff that was in the distant past
|
|
used to debug the Mercury compiler's low-level code generation.
|
|
This option is not likely to be useful to anyone except the Mercury
|
|
implementors. It causes the generated code to become very big and very
|
|
inefficient, and slows down compilation a lot.
|
|
|
|
@sp 1
|
|
@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 --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.
|
|
|
|
@sp 1
|
|
@item @code{--c-debug}
|
|
Pass the @samp{-g} flag to the C compiler, to enable debugging
|
|
of the generated C code.
|
|
Since the generated C code is very low-level, this option is not likely
|
|
to be useful to anyone except the Mercury implementors, except perhaps
|
|
for debugging code that uses Mercury's C interface extensively.
|
|
|
|
@sp 1
|
|
@item --fact-table-max-array-size @var{size}
|
|
Specify the maximum number of elements in a single
|
|
@samp{pragma fact_table} data array (default: 1024).
|
|
The data for fact tables is placed into multiple C arrays, each with a
|
|
maximum size given by this option. The reason for doing this is that
|
|
most C compilers have trouble compiling very large arrays.
|
|
|
|
@sp 1
|
|
@item --fact-table-hash-percent-full @var{percentage}
|
|
Specify how full the @samp{pragma fact_table} hash tables should be
|
|
allowed to get. Given as an integer percentage (valid range: 1 to 100,
|
|
default: 90). A lower value means that the compiler will use
|
|
larger tables, but there will generally be less hash collisions,
|
|
so it may result in faster lookups.
|
|
|
|
@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.
|
|
|
|
@end table
|
|
|
|
@node Optimization options
|
|
@section Optimization options
|
|
|
|
@menu
|
|
* Overall optimization options::
|
|
* High-level (HLDS -> HLDS) optimization options::
|
|
* Medium-level (HLDS -> LLDS) optimization options::
|
|
* Low-level (LLDS -> LLDS) optimization options::
|
|
* Output-level (LLDS -> C) optimization options::
|
|
* Object-level (C -> object code) optimization options::
|
|
@end menu
|
|
|
|
@node Overall optimization options
|
|
@subsection Overall optimization options
|
|
|
|
@table @code
|
|
@item -O @var{n}
|
|
@itemx --opt-level @var{n}
|
|
@itemx --optimization-level @var{n}
|
|
Set optimization level to @var{n}.
|
|
Optimization levels range from -1 to 6.
|
|
Optimization level -1 disables all optimizations,
|
|
while optimization level 6 enables all optimizations
|
|
except for the cross-module optimizations listed below.
|
|
|
|
In general, there is a trade-off between compilation speed and the
|
|
speed of the generated code. When developing, you should normally use
|
|
optimization level 0, which aims to minimize compilation time. It
|
|
enables only those optimizations that in fact usually @emph{reduce}
|
|
compilation time. The default optimization level is level 2, which
|
|
delivers reasonably good optimization in reasonable time. Optimization
|
|
levels higher than that give better optimization, but take longer,
|
|
and are subject to the law of diminishing returns. The difference in
|
|
the quality of the generated code between optimization level 5 and
|
|
optimization level 6 is very small, but using level 6 may increase
|
|
compiation time and memory requirements dramatically.
|
|
|
|
Note that if you want the compiler to perform cross-module
|
|
optimizations, then you must enable them separately;
|
|
the cross-module optimizations are not enabled by any @samp{-O}
|
|
level, because they affect the compilation process in ways
|
|
that require special treatment by @samp{mmake}.
|
|
|
|
@sp 1
|
|
@item --opt-space
|
|
@itemx --optimize-space
|
|
Turn on optimizations that reduce code size
|
|
and turn off optimizations that significantly increase code size.
|
|
@end table
|
|
|
|
@table @code
|
|
@item --intermodule-optimization
|
|
Perform inlining and higher-order specialization of the code for
|
|
predicates or functions imported from other modules.
|
|
|
|
@sp 1
|
|
@item --trans-intermod-opt
|
|
@itemx --transitive-intermodule-optimization
|
|
Use the information stored in @file{@var{module}.trans_opt} files
|
|
to make intermodule optimizations. The @file{@var{module}.trans_opt} files
|
|
are differents to the @file{@var{module}.opt} files as @samp{.trans_opt}
|
|
files may depend on other @samp{.trans_opt} files, whereas each
|
|
@samp{.opt} file may only depend on the corresponding @samp{.m} file.
|
|
|
|
@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}.
|
|
|
|
N.B. When using @samp{mmake}, the @samp{--split-c-files} option should
|
|
not be placed in the @samp{MCFLAGS} variable. Instead, use the
|
|
@samp{@var{MODULE}.split} target, i.e. type @samp{mmake foo.split}
|
|
rather than @samp{mmake foo}.
|
|
|
|
@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-compound-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.
|
|
|
|
@item --inline-simple-threshold @var{threshold}
|
|
Inline a procedure if its size is less than the given threshold.
|
|
|
|
@item --intermod-inline-simple-threshold @var{threshold}
|
|
Similar to --inline-simple-threshold, except used to determine which
|
|
predicates should be included in @samp{.opt} files. Note that changing this
|
|
between writing the @samp{.opt} file and compiling to C may cause link errors,
|
|
and too high a value may result in reduced performance.
|
|
|
|
|
|
@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 --optimize-unused-args
|
|
Remove unused predicate arguments. The compiler will
|
|
generate more efficient code for polymorphic predicates.
|
|
|
|
@sp 1
|
|
@item --intermod-unused-args
|
|
Perform unused argument removal across module boundaries.
|
|
This option implies `--optimize-unused-args' and
|
|
`--intermodule-optimization'.
|
|
|
|
@sp 1
|
|
@item --optimize-higher-order
|
|
Specialize calls to higher-order predicates where
|
|
the higher-order arguments are known.
|
|
|
|
@sp 1
|
|
@item --optimize-constant-propagation
|
|
Evaluate constant expressions at compile time.
|
|
|
|
@sp 1
|
|
@item --optimize-constructor-last-call
|
|
Enable the optimization of ``last'' calls that are followed by
|
|
constructor application.
|
|
|
|
@sp 1
|
|
@item --optimize-dead-procs.
|
|
Enable dead predicate elimination.
|
|
|
|
@sp 1
|
|
@item --excess-assign
|
|
Remove excess assignment unifications.
|
|
|
|
@sp 1
|
|
@item --optimize-duplicate-calls
|
|
Optimize away multiple calls to a predicate with the same input arguments.
|
|
|
|
@sp 1
|
|
@item --optimize-saved-vars
|
|
Reorder goals to minimize the number of variables
|
|
that have to be saved across calls.
|
|
|
|
@sp 1
|
|
@item --deforestation
|
|
Enable deforestation. Deforestation is a program transformation whose aim
|
|
is to avoid the construction of intermediate data structures and to avoid
|
|
repeated traversals over data structures within a conjunction.
|
|
|
|
@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: 3).
|
|
|
|
@sp 1
|
|
@item --try-switch-size @var{size}
|
|
The number of alternatives in a try-chain switch
|
|
must be at least this number (default: 3).
|
|
|
|
@sp 1
|
|
@item --binary-switch-size @var{size}
|
|
The number of alternatives in a binary search switch
|
|
must be at least this number (default: 4).
|
|
|
|
@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.
|
|
|
|
@sp 1
|
|
@item --pred-value-number
|
|
Extend value numbering to whole procedures, 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 --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 --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.
|
|
|
|
@end table
|
|
|
|
@node Object-level (C -> object code) optimization options
|
|
@subsection Object-level (C -> object code) optimization options
|
|
|
|
These optimizations are applied during the process of compiling
|
|
the generated C code to machine code object files.
|
|
|
|
If you are using Mmake, you need to pass these options
|
|
to @samp{mgnuc} rather than to @samp{mmc}.
|
|
|
|
@table @code
|
|
@item --no-c-optimize
|
|
Don't enable the C compiler's optimizations.
|
|
|
|
@sp 1
|
|
@item --inline-alloc
|
|
Inline calls to @samp{GC_malloc()}.
|
|
This can improve performance a fair bit,
|
|
but may significantly increase code size.
|
|
This option has no effect if @samp{--gc conservative}
|
|
is not set or if the C compiler is not GNU C.
|
|
|
|
@end table
|
|
|
|
@node Miscellaneous options
|
|
@section Miscellaneous options
|
|
@table @code
|
|
@item -I @var{dir}
|
|
@itemx --search-directory @var{dir}
|
|
Append @var{dir} to the list of directories to be searched for
|
|
imported modules.
|
|
|
|
@item --intermod-directory @var{dir}
|
|
Append @var{dir} to the list of directories to be searched for
|
|
@samp{.opt} files.
|
|
|
|
@item --use-search-directories-for-intermod
|
|
Append the arguments of all -I options to the list of directories
|
|
to be searched for @samp{.opt} files.
|
|
|
|
@item --use-subdirs
|
|
Create intermediate files in a @file{Mercury} subdirectory,
|
|
rather than in the current directory.
|
|
|
|
@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 C header files for the Mercury runtime system (@file{*.h}).
|
|
This environment variable is used
|
|
only to define the default value of MERCURY_ALL_C_INCL_DIRS,
|
|
so if you define that environment variable separately,
|
|
the value of MERCURY_C_INCL_DIR is ignored.
|
|
|
|
@sp 1
|
|
@item MERCURY_ALL_C_INCL_DIRS
|
|
A list of options for the C compiler that specifies
|
|
all the directories the C compiler should search for the C header files
|
|
of the Mercury runtime system and garbage collector.
|
|
The default value of this option is -I$MERCURY_C_INCL_DIR,
|
|
since usually all these header files are installed in one directory.
|
|
|
|
@sp 1
|
|
@item MERCURY_INT_DIR
|
|
Directory for the Mercury library interface
|
|
files (@file{*.int}, @file{*.int2}, @file{*.int3} and @file{*.opt}).
|
|
|
|
@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_NU_OVERRIDING_LIB_OBJS
|
|
List of the NU-Prolog object files (@file{*.no}) for the Mercury
|
|
library which override definitions given in @samp{MERCURY_NU_LIB_OBJS}.
|
|
|
|
@sp 1
|
|
@item MERCURY_SP_LIB_DIR
|
|
Directory for the Sicstus-Prolog object files (@file{*.ql}) for the
|
|
Sicstus-Prolog Mercury library.
|
|
|
|
@sp 1
|
|
@item MERCURY_SP_LIB_OBJS
|
|
List of the Sicstus-Prolog object files (@file{*.ql}) for the Mercury
|
|
library.
|
|
|
|
@sp 1
|
|
@item MERCURY_SP_OVERRIDING_LIB_OBJS
|
|
List of the Sicstus-Prolog object files (@file{*.ql}) for the Mercury
|
|
library which override definitions given in @samp{MERCURY_SP_LIB_OBJS}.
|
|
|
|
@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
|
|
@samp{MGNUC=MERCURY_C_COMPILER=@dots{} mgnuc} to your @samp{Mmake} file,
|
|
or by using the @samp{--cc} option to @samp{mmc}.
|
|
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{mmc} 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{mmc}. (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
|