[m-rev.] for review: add index to user guide
Fergus Henderson
fjh at cs.mu.OZ.AU
Tue Jun 5 04:57:26 AEST 2001
Estimated hours taken: 4
Branches: main
doc/user_guide.texi:
Add an index.
Also a couple of minor corrections:
- delete MERCURY_INTERPRETER environment variable (no longer used)
- s/dead predicate/dead procedure/
- s/--no-gcc-nonlocal_gotos/--no-gcc-nonlocal-gotos/g
^ ^
Workspace: /home/mars/fjh/ws1/mercury
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.254
diff -u -d -r1.254 user_guide.texi
--- doc/user_guide.texi 2001/06/04 16:11:01 1.254
+++ doc/user_guide.texi 2001/06/04 18:51:28
@@ -15,6 +15,33 @@
@c @cropmarks
@finalout
@setchapternewpage off
+
+ at c ----------------------------------------------------------------------------
+
+ at c We use the following indices in this document:
+ at c
+ at c The "@cindex" / "cp" (concept) index:
+ at c for general concepts (e.g. "Determinism", "Debugging", etc.)
+ at c The "@pindex" / "pg" (program) index:
+ at c for programs or shell scripts (mmc, mgnuc, etc.).
+ at c The "@findex" / "fn" (function) index:
+ at c for command-line options.
+ at c The "@kindex" / "ky" (keystroke) index:
+ at c for mdb commands.
+ at c The "@vindex" / "vr" (variable) index:
+ at c for environment variables and Mmake variables.
+ at c
+ at c That is in case we ever want to produce separate indices for the
+ at c different categories. Currently, however, we merge them all into
+ at c a single index, via the commands below.
+
+ at syncodeindex fn cp
+ at syncodeindex ky cp
+ at syncodeindex vr cp
+ at syncodeindex pg cp
+
+ at c ----------------------------------------------------------------------------
+
@ifinfo
This file documents the Mercury implementation.
@@ -62,9 +89,14 @@
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage
+
+ at c ----------------------------------------------------------------------------
+
@contents
@page
+ at c ----------------------------------------------------------------------------
+
@ifinfo
@node Top,,, (mercury)
@top The Mercury User's Guide
@@ -86,9 +118,12 @@
* 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.
+* Index::
@end menu
@end ifinfo
+ at c ----------------------------------------------------------------------------
+
@node Introduction
@chapter Introduction
@@ -104,8 +139,12 @@
than invoking @samp{mmc} directly, because @samp{mmake} is generally
easier to use and avoids unnecessary recompilation.
+ at c ----------------------------------------------------------------------------
+
@node Filenames
@chapter File naming conventions
+ at cindex File extensions
+ at cindex File names
Mercury source files must be named @file{*.m}.
Each Mercury source file should contain a single Mercury module
@@ -117,6 +156,7 @@
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
+ at findex --use-subdirs
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.
@@ -130,6 +170,15 @@
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.
+ at findex --make-int
+ at findex --make-interface
+ at findex --make-short-int
+ at findex --make-short-interface
+ at findex --make-priv-interface
+ at findex --make-private-interface
+ at findex --make-optimization-interface
+ at findex --make-transitive-optimization-interface
+ at findex --make-trans-opt-int
Files ending in @file{.opt} are
interface files used in inter-module optimization,
and are created using the @samp{--make-optimization-interface}
@@ -167,12 +216,15 @@
executed by the Aditi deductive database system (@pxref{Using Aditi}).
@end ifset
+ at c ----------------------------------------------------------------------------
+
@node Using mmc
@chapter Using the Mercury compiler
Following a long Unix tradition,
the Mercury compiler is called @samp{mmc}
(for ``Melbourne Mercury Compiler'').
+ at pindex mmc
Some of its options (e.g. @samp{-c}, @samp{-o}, and @samp{-I})
have a similar meaning to that in other Unix compilers.
@@ -232,6 +284,9 @@
mmc --make-priv-int @var{filename1}.m @var{filename2}.m ...
mmc --make-int @var{filename1}.m @var{filename2}.m ...
@end example
+ at findex --make-short-int
+ at findex --make-priv-int
+ at findex --make-int
If you are going to compile with @samp{--intermodule-optimization} enabled,
then you also need to create the optimization interface files.
@@ -239,13 +294,16 @@
@example
mmc --make-opt-int @var{filename1}.m @var{filename2}.m ...
@end example
+ at findex --make-opt-int
If you are going to compile with @samp{--transitive-intermodule-optimization}
enabled, then you also need to create the transitive optimization files.
+ at findex --transitive-intermodule-optimization
@example
mmc --make-trans-opt @var{filename1}.m @var{filename2}.m ...
@end example
+ at findex --make-trans-opt
Given that you have made all the interface files,
one way to create an executable for a multi-module program
@@ -259,9 +317,11 @@
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.
+ at findex -o
The other way to create an executable for a multi-module program
is to compile each module separately using @samp{mmc -c},
+ at findex -c
and then link the resulting object files together.
The linking is a two stage process.
@@ -274,6 +334,8 @@
c2init @var{module1}.c @var{module2}.c ... > @var{main-module}_init.c,
mgnuc -c @var{main-module}_init.c
@end example
+ at pindex c2init
+ at pindex mgnuc
The @samp{c2init} command line must contain
the name of the C file of every module in the program.
@@ -290,6 +352,7 @@
@example
ml -o @var{main-module} @var{module1}.o @var{module2}.o ... @var{main_module}_init.o
@end example
+ at pindex ml
@samp{ml}, the Mercury linker, is another shell script
that invokes a C compiler with options appropriate for Mercury,
@@ -307,6 +370,8 @@
You can use that option to see what is actually going on.
For the full set of options of @samp{mmc}, see @ref{Invocation}.
+ at c ----------------------------------------------------------------------------
+
@node Running
@chapter Running programs
@@ -315,19 +380,25 @@
certain options to the Mercury runtime system.
The Mercury runtime accepts
options via the @samp{MERCURY_OPTIONS} environment variable.
+ at vindex MERCURY_OPTIONS
The most useful of these are the options that set the size of the stacks.
(For the full list of available options, see @ref{Environment}.)
+ at c XXX FIXME This is wrong for the case when --high-level-code is enabled.
The det stack and the nondet stack
are allocated fixed sizes at program start-up.
The default size is 4096k for the det stack and 128k for the nondet stack,
but these can be overridden with the
@samp{--detstack-size} and @samp{--nondetstack-size} options,
+ at findex --detstack-size
+ at findex --nondetstack-size
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.
+ at cindex Stack size
+ at cindex Stack overflow
With conservative garbage collection (the default),
the heap will start out with a zero size,
@@ -336,9 +407,17 @@
the heap has a fixed size like the stacks.
The default size is 4 Mb, but this can be overridden
with the @samp{--heap-size} option.
+ at cindex Heap size
+ at cindex Heap overflow
+
+ at c ----------------------------------------------------------------------------
@node Using Mmake
@chapter Using Mmake
+ at pindex mmake
+ at pindex make: see Mmake
+ at cindex Building programs
+ at cindex Recompiling
Mmake, short for ``Mercury Make'',
is a tool for building Mercury programs
@@ -434,6 +513,9 @@
@samp{cp}. The variable @code{INSTALL_MKDIR} specifies the command to use
to create directories, by default @samp{mkdir -p}.
For more information, see @ref{Supporting multiple grades and architectures}.
+ at vindex LIBGRADES
+ at vindex INSTALL
+ at vindex INSTALL_MKDIR
@item @var{main-module}.clean
Removes the automatically generated files
@@ -503,66 +585,89 @@
@table @code
@item MAIN_TARGET
+ at vindex 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
+ at vindex MC
The executable that invokes the Mercury compiler.
@item GRADEFLAGS and EXTRA_GRADEFLAGS
+ at vindex GRADEFLAGS
+ at vindex EXTRA_GRADEFLAGS
Compilation model options (@pxref{Compilation model options})
to pass to the Mercury compiler, linker, and other tools
(in particular @code{mmc}, @code{mgnuc}, @code{ml}, and @code{c2init}).
@item MCFLAGS and EXTRA_MCFLAGS
+ at vindex CFLAGS
+ at vindex EXTRA_CFLAGS
Options to pass to the Mercury compiler.
(Note that compilation model options should be
specified in @code{GRADEFLAGS}, not in @code{MCFLAGS}.)
@item MGNUC
+ at vindex MGNUC
The executable that invokes the C compiler.
@item MGNUCFLAGS and EXTRA_MGNUCFLAGS
+ at vindex MGNUCFLAGS
+ at vindex EXTRA_MGNUCFLAGS
Options to pass to the C compiler.
@item MS_CLFLAGS and EXTRA_MS_CLFLAGS
+ at vindex MS_CLFLAGS
+ at vindex EXTRA_MS_CLFLAGS
Options to pass to the Microsoft command line C++ compiler (if you are
using it).
@item MS_CL_NOASM
+ at vindex MS_CL_NOASM
The option to control whether the Microsoft command line C++ compile
will generate assemblies from managed C++ files. Set to
@samp{:noAssembly} to turn off assembly generation, leave empty to turn
on assembly generation. The default is to leave this variable empty.
@item ML
+ at vindex ML
The executable that invokes the linker.
@item MLFLAGS and EXTRA_MLFLAGS
+ at vindex MLFLAGS
+ at vindex EXTRA_MLFLAGS
Options to pass to the linker.
(Note that compilation model options should be
specified in @code{GRADEFLAGS}, not in @code{MLFLAGS}.)
@item MLLIBS and EXTRA_MLLIBS
+ at vindex MLLIBS
+ at vindex EXTRA_MLLIBS
A list of @samp{-l} options specifying libraries used by the program
(or library) that you are building. @xref{Using libraries}.
@item MLOBJS
+ at vindex MLOBJS
A list of extra object files to link into any programs or libraries
that you are building.
@item C2INITFLAGS and EXTRA_C2INITFLAGS
+ at vindex C2INITFLAGS
+ at vindex EXTRA_C2INITFLAGS
Options to pass to the c2init program.
(Note that compilation model options and extra files to be processed by
c2init should not be specified in @code{C2INITFLAGS} - they should be
specified in @code{GRADEFLAGS} and @code{C2INITARGS}, respectively.)
@item C2INITARGS and EXTRA_C2INITARGS
+ at vindex C2INITARGS
+ at vindex EXTRA_C2INITARGS
Extra files to be processed by c2init. These variables should not be
used for specifying flags to c2init (that's what @code{C2INITFLAGS} is for)
since they are also used to derive extra dependency information.
@item EXTRA_LIBRARIES
+ at vindex EXTRA_LIBRARIES
A list of extra Mercury libraries to link into any programs or libraries
that you are building.
Libraries should be specified using their base name; that is, without any
@@ -571,29 +676,35 @@
@file{foo.init} would be referred to as just @samp{foo}.
@item EXTRA_LIB_DIRS
+ at vindex EXTRA_LIB_DIRS
A list of extra Mercury library directory hierarchies to search when
looking for extra libraries.
@item INSTALL_PREFIX
+ at vindex INSTALL_PREFIX
The path to the root of the directory hierarchy where the libraries,
etc. you are building should be installed. The default is to install in
the same location as the Mercury compiler being used to do the install.
@item INSTALL
+ at vindex INSTALL
The command used to install each file in a library. The command should
take a list of files to install and the location to install them.
The default command is @samp{cp}.
@item INSTALL_MKDIR
+ at vindex INSTALL_MKDIR
The command used to create each directory in the directory hierarchy
where the libraries are to be installed. The default command is
@samp{mkdir -p}.
@item LIBGRADES
+ at vindex LIBGRADES
A list of additional grades which should be built when installing libraries.
The default is to install the Mercury compiler's default set of grades.
Note that this may not be the set of grades in which the standard libraries
were actually installed.
+ at vindex GRADEFLAGS
Note also that any @code{GRADEFLAGS} settings will also be applied when
the library is built in each of the listed grades, so you may not get what
you expect if those options are not subsumed by each of the grades listed.
@@ -635,8 +746,11 @@
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.
+ at c ----------------------------------------------------------------------------
+
@node Libraries
@chapter Libraries
+ at cindex Libraries
Often you will want to use a particular set of Mercury modules
in more than one program. The Mercury implementation
@@ -692,6 +806,11 @@
@node Building libraries
@section Building libraries
+ at cindex Shared objects
+ at cindex Shared libraries
+ at cindex Static libraries
+ at cindex Position independent code
+ at cindex PIC (position independent code)
Generally Mmake will do most of the work of building
libraries automatically. Here's a sample @code{Mmakefile} for
@@ -740,6 +859,15 @@
clean:
rm -f libmypackage.a libmypackage.so
@end example
+ at vindex AR
+ at vindex ARFLAGS
+ at vindex MLOBJS
+ at vindex RANLIB
+ at vindex RANLIBFLAGS
+ at vindex ML
+ at vindex MLFLAGS
+ at vindex MLPICOBJS
+ at vindex MLLIBS
If necessary, you can override the default definitions of the variables
such as @samp{ML}, @samp{MLFLAGS}, @samp{MLPICOBJS}, and @samp{MLLIBS}
@@ -760,11 +888,13 @@
The @samp{libmypackage} target will build @samp{$(mypackage.opts)} if
@samp{--intermodule-optimization} is specified in your @samp{MCFLAGS}
variable (this is recommended).
+ at findex --intermodule-optimization
Similarly, if the people using the library are going to use transitive
intermodule optimization, you will also need the transitive intermodule
optimization interfaces (@samp{$(mypackage.trans_opt)}).
These will be built if @samp{--trans-intermod-opt} is specified in your
@samp{MCFLAGS} variable.
+ at findex --trans-intermod-opt
In addition, with certain compilation grades, programs will need to
execute some startup code to initialize the library; the
@@ -801,6 +931,13 @@
@node Using libraries
@section Using libraries
+ at vindex VPATH
+ at vindex MCFLAGS
+ at vindex MLFLAGS
+ at vindex MLLIBS
+ at vindex C2INITARGS
+ at vindex MGNUCFLAGS
+ at findex intermodule-optimization
To use a library, you need to set the Mmake variables @samp{VPATH},
@samp{MCFLAGS}, @samp{MLFLAGS}, @samp{MLLIBS}, and @samp{C2INITARGS}
to specify the name and location of the library or libraries that you
@@ -871,6 +1008,8 @@
INSTALL_PREFIX = /my/install/dir
LIBGRADES = asm_fast asm_fast.gc.tr.debug
@end example
+ at vindex INSTALL_PREFIX
+ at vindex LIBGRADES
This specifies that libraries should be installed in
@file{/my/install/dir/lib/mercury}, in the default grade plus
@@ -892,9 +1031,11 @@
The command used to install each file is specified by @samp{INSTALL}.
If @samp{INSTALL} is not specified, @samp{cp} will be used.
+ at vindex INSTALL
The command used to create directories is specified by @samp{INSTALL_MKDIR}.
If @samp{INSTALL_MKDIR} is not specified, @samp{mkdir -p} will be used.
+ at vindex INSTALL_MKDIR
Note that currently it is not possible to set the installation prefix
on a library-by-library basis.
@@ -911,6 +1052,8 @@
/some/directory/myotherlib/lib/mercury
EXTRA_LIBRARIES = mypackage myotherlib
@end example
+ at vindex EXTRA_LIBRARIES
+ at vindex EXTRA_LIB_DIRS
Mmake will then ensure that the appropriate directories are searched for
the relevant interface files, module initialisation files, compiled
@@ -930,8 +1073,13 @@
EXTRA_LIBRARIES-foo = mylib4foo
@end example
+ at c ----------------------------------------------------------------------------
+
@node Debugging
@chapter Debugging
+ at cindex Debugging
+ at cindex Tracing
+ at pindex mdb
@menu
* Quick overview::
@@ -956,6 +1104,7 @@
You can do this by using the @samp{--debug} option to @samp{mmc},
or by including @samp{GRADEFLAGS = --debug} in your @file{Mmakefile}.
+ at findex --debug
@example
bash$ mmc --debug hello.m
@end example
@@ -963,6 +1112,7 @@
Once you've compiled with debugging enabled, you can use the @samp{mdb}
command to invoke your program under the debugger:
+ at pindex mdb
@example
bash$ mdb ./hello arg1 arg2 ...
@end example
@@ -1049,6 +1199,8 @@
@node GNU Emacs interface
@section GNU Emacs interface
+ at cindex GNU Emacs
+ at cindex Emacs
As well as the command-line debugger, mdb, there is also an Emacs
interface to this debugger. Note that the Emacs interface only
@@ -1168,6 +1320,7 @@
@node Tracing of Mercury programs
@section Tracing of Mercury programs
+ at cindex Tracing
The Mercury debugger is based on a modified version of the box model
on which the four-port debuggers of most Prolog systems are based.
@@ -1177,6 +1330,10 @@
The four kinds of events supported by most Prolog systems (their @emph{ports})
are
+ at cindex call
+ at cindex exit
+ at cindex redo
+ at cindex fail
@table @emph
@item call
A call event occurs just after a procedure has been called,
@@ -1234,6 +1391,10 @@
Each of these internal event types has an associated parameter called a path.
The internal event types are:
+ at cindex then
+ at cindex else
+ at cindex disj
+ at cindex switch
@table @emph
@item then
A then event occurs when execution reaches
@@ -1259,6 +1420,8 @@
@c @item pragma_later
@end table
+ at cindex path
+ at cindex goal path
A path is a sequence of path components separated by semicolons.
Each path component is one of the following:
@@ -1365,6 +1528,9 @@
which of three trace levels, @samp{none}, @samp{shallow} and @samp{deep},
you want to compile them with:
+ at cindex trace level
+ at cindex shallow tracing
+ at cindex deep tracing
@table @samp
@item none
A procedure compiled with trace level @samp{none}
@@ -1512,6 +1678,7 @@
it executes commands from the following three sources, in order:
@enumerate
@item
+ at vindex MERCURY_DEBUGGER_INIT
The file named by the @samp{MERCURY_DEBUGGER_INIT} environment variable.
Usually, @samp{mdb} sets this variable to point to a file
that provides documentation for all the debugger commands
@@ -1523,6 +1690,8 @@
@samp{mdb} will print a warning,
since in that case, that usual online documentation will not be available.
@item
+ at cindex mdbrc
+ at cindex .mdbrc
The file named @samp{.mdbrc} in your home directory.
You can put your usual aliases and settings here.
@item
@@ -1538,6 +1707,8 @@
@table @emph
@item break points
+ at cindex break points
+ at cindex spy points
The user may associate a break point
with some events that occur inside a procedure;
the invocation condition of the break point says which events these are.
@@ -1575,6 +1746,7 @@
Neither of these will happen if the break point is disabled.
@sp 1
@item strict commands
+ at cindex strict commands
When a debugger command steps over some events
without user interaction at those events,
the @emph{strictness} of the command controls whether
@@ -1585,11 +1757,16 @@
it will not stop at an event
just because a break point in the stop state applies to it.
+ at cindex debugger interrupt
+ at cindex interrupt, in debugger
+ at cindex control-C
If the debugger receives an interrupt (e.g. if the user presses control-C),
it will stop at the next event regardless of what command it is executing
at the time.
@sp 1
@item print level
+ at cindex print level
+ at cindex debugger print level
When a debugger command steps over some events
without user interaction at those events,
the @emph{print level} controls under what circumstances
@@ -1626,6 +1803,7 @@
changes the environment yet again or execution continues to another event.
@sp 1
@item procedure specification
+ at cindex procedure specification
Some debugger commands, e.g. @samp{break},
require a parameter that specifies a procedure.
Such a procedure specification has
@@ -1687,6 +1865,9 @@
@item query @var{module1} @var{module2} @dots{}
@itemx cc_query @var{module1} @var{module2} @dots{}
@itemx io_query @var{module1} @var{module2} @dots{}
+ at kindex query (mdb command)
+ at kindex cc_query (mdb command)
+ at kindex io_query (mdb command)
@c This documentation has been duplicated in
@c Opium-M/source/interactive_queries.op so please tell me (jahier at irisa.fr)
@@ -1753,6 +1934,7 @@
@table @code
@item step [-NSans] [@var{num}]
+ at kindex step (mdb command)
Steps forward @var{num} events.
If this command is given at event @var{cur}, continues execution until
event @var{cur} + @var{num}. The default value of @var{num} is 1.
@@ -1772,6 +1954,7 @@
An empty command line is interpreted as `step 1'.
@sp 1
@item goto [-NSans] @var{num}
+ at kindex goto (mdb command)
Continues execution until the program reaches event number @var{num}.
If the current event number is larger than @var{num}, it reports an error.
@sp 1
@@ -1785,6 +1968,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item next [-NSans] [@var{num}]
+ at kindex next (mdb command)
Continues execution until it reaches the next event of
the @var{num}'th ancestor of the call to which the current event refers.
The default value of @var{num} is zero,
@@ -1801,6 +1985,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item finish [-NSans] [@var{num}]
+ at kindex finish (mdb command)
Continues execution until it reaches a final (EXIT, FAIL or EXCP) port
of the @var{num}'th ancestor of the call to which the current event refers.
The default value of @var{num} is zero,
@@ -1838,6 +2023,7 @@
@c By default, this command is strict, and it uses the default print level.
@sp 1
@item exception [-NSans]
+ at kindex exception (mdb command)
Continues the program until execution reaches an exception event.
Reports an error if the current event is already an exception event.
@sp 1
@@ -1851,6 +2037,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item return [-NSans]
+ at kindex return (mdb command)
Continues the program until the program finished returning,
i.e. until it reaches a port other than EXIT.
Reports an error if the current event already refers to such a port.
@@ -1865,6 +2052,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item forward [-NSans]
+ at kindex forward (mdb command)
Continues the program until the program resumes forward execution,
i.e. until it reaches a port other than REDO or FAIL.
Reports an error if the current event already refers to such a port.
@@ -1879,6 +2067,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item mindepth [-NSans] @var{depth}
+ at kindex mindepth (mdb command)
Continues the program until the program reaches an event
whose depth is at least @var{depth}.
Reports an error if the current event already refers to such a port.
@@ -1893,6 +2082,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item maxdepth [-NSans] @var{depth}
+ at kindex maxdepth (mdb command)
Continues the program until the program reaches an event
whose depth is at most @var{depth}.
Reports an error if the current event already refers to such a port.
@@ -1907,6 +2097,7 @@
By default, this command is strict, and it uses the default print level.
@sp 1
@item continue [-NSans]
+ at kindex continue (mdb command)
Continues execution until it reaches the end of the program.
@sp 1
The options @samp{-n} or @samp{--none}, @samp{-s} or @samp{--some},
@@ -1926,6 +2117,7 @@
@sp 1
@table @code
@item retry
+ at kindex retry (mdb command)
Restarts execution at the call port
of the call corresponding to the current event.
@sp 1
@@ -1981,11 +2173,13 @@
@sp 1
@table @code
@item vars
+ at kindex vars (mdb command)
Prints the names of all the known variables in the current environment,
together with an ordinal number for each variable.
@sp 1
@item print [-fpv] @var{name}
@itemx print [-fpv] @var{num}
+ at kindex print (mdb command)
Prints the value of the variable in the current environment
with the given name, or with the given ordinal number.
This is a non-interactive version of the @samp{browse}
@@ -2012,6 +2206,7 @@
@sp 1
@item browse [-fpv] @var{name}
@itemx browse [-fpv] @var{num}
+ at kindex browse (mdb command)
Invokes an interactive term browser to browse the value of the
variable in the current environment with the given ordinal number or
with the given name.
@@ -2039,6 +2234,7 @@
and @samp{-v} or @samp{--verbose} specify the format to use for browsing.
@sp 1
@item stack [-d]
+ at kindex stack (mdb command)
Prints the names of the ancestors of the call
specified by the current event.
If two or more ancestor calls are for the same procedure,
@@ -2054,6 +2250,7 @@
information available about any ancestor.
@sp 1
@item up [-d] [@var{num}]
+ at kindex up (mdb command)
Sets the current environment to the stack frame
of the @var{num}'th level ancestor of the current environment
(the immediate caller is the first-level ancestor).
@@ -2072,6 +2269,7 @@
if the call is to a procedure that is being execution traced.
@sp 1
@item down [-d] [@var{num}]
+ at kindex down (mdb command)
Sets the current environment to the stack frame
of the @var{num}'th level descendant of the current environment
(the procedure called by the current environment
@@ -2088,6 +2286,7 @@
if the call is to a procedure that is being execution traced.
@sp 1
@item level [-d] [@var{num}]
+ at kindex level (mdb command)
Sets the current environment to the stack frame of the @var{num}'th
level ancestor of the call to which the current event belongs.
The zero'th ancestor is the call of the event itself.
@@ -2104,12 +2303,19 @@
if the call is to a procedure that is being execution traced.
@sp 1
@item current
+ at kindex current (mdb command)
Prints the current event.
This is useful if the details of the event,
which were printed when control arrived at the event,
have since scrolled off the screen.
@sp 1
@item set [-APBfpv] @var{param} @var{value}
+ at kindex set (mdb command)
+ at kindex format (mdb command)
+ at kindex depth (mdb command)
+ at kindex size (mdb command)
+ at kindex width (mdb command)
+ at kindex lines (mdb command)
Updates the configuration parameters of the browser.
The parameters that can be configured are
@samp{format}, @samp{depth}, @samp{size}, @samp{width} and @samp{lines}.
@@ -2158,9 +2364,11 @@
@sp 1
@node Breakpoint commands
@subsection Breakpoint commands
+ at cindex Breakpoints
@sp 1
@table @code
@item break [-PS] @var{filename}:@var{linenumber}
+ at kindex break (mdb command)
Puts a break point on the specified line of the specified source file,
if there is an event or a call at that position.
If the filename is omitted,
@@ -2208,6 +2416,7 @@
Lists the details and status of all break points.
@sp 1
@item disable @var{num}
+ at kindex disable (mdb command)
Disables the break point with the given number.
Reports an error if there is no break point with that number.
@sp 1
@@ -2223,6 +2432,7 @@
Reports an error if there is no break point with that number.
@sp 1
@item enable *
+ at kindex enable (mdb command)
Enables all break points.
@sp 1
@item enable
@@ -2230,6 +2440,7 @@
Reports an error if the most recently added breakpoint has since been deleted.
@sp 1
@item delete @var{num}
+ at kindex delete (mdb command)
Deletes the break point with the given number.
Reports an error if there is no break point with that number.
@sp 1
@@ -2242,13 +2453,16 @@
has already been deleted.
@sp 1
@item modules
+ at kindex modules (mdb command)
Lists all the debuggable modules
(i.e. modules that have debugging information).
@sp 1
@item procedures @var{module}
+ at kindex procedures (mdb command)
Lists all the procedures in the debuggable module @var{module}.
@sp 1
@item register
+ at kindex register (mdb command)
Registers all debuggable modules with the debugger.
Has no effect if this registration has already been done.
The debugger will perform this registration when creating breakpoints
@@ -2260,6 +2474,7 @@
@sp 1
@table @code
@item mmc_options @var{option1} @var{option2} @dots{}
+ at kindex mmc_options (mdb command)
This command sets the options that will be passed to @samp{mmc}
to compile your query when you use one of the query commands:
@samp{query}, @samp{cc_query}, or @samp{io_query}.
@@ -2267,6 +2482,7 @@
it may sometimes be helpful to use @samp{mmc_options --verbose-error-messages}.
@sp 1
@item printlevel none
+ at kindex printlevel (mdb command)
Sets the default print level to @samp{none}.
@sp 1
@item printlevel some
@@ -2279,6 +2495,7 @@
Reports the current default print level.
@sp 1
@item echo on
+ at kindex echo (mdb command)
Turns on the echoing of commands.
@sp 1
@item echo off
@@ -2288,6 +2505,7 @@
Reports whether commands are being echoed or not.
@sp 1
@item scroll on
+ at kindex scroll (mdb command)
Turns on user control over the scrolling of sequences of event reports.
This means that every screenful of event reports
will be followed by a @samp{--more--} prompt.
@@ -2315,6 +2533,9 @@
Reports whether user scroll control is enabled and what the window size is.
@sp 1
@item context none
+ at kindex context (mdb command)
+ at cindex line numbers
+ at cindex file names
When reporting events or ancestor levels,
does not print contexts (filename/line number pairs).
@sp 1
@@ -2348,6 +2569,7 @@
Reports where contexts are being printed.
@sp 1
@item alias @var{name} @var{command} [@var{command-parameter} ...]
+ at kindex alias (mdb command)
Introduces @var{name} as an alias
for the given command with the given parameters.
Whenever a command line has @var{name} as its first word,
@@ -2365,6 +2587,7 @@
whenever the user types in a command line that consists of a single number.
@sp 1
@item unalias @var{name}
+ at kindex unalias (mdb command)
Removes any existing alias for @var{name}.
@end table
@sp 1
@@ -2373,6 +2596,7 @@
@sp 1
@table @code
@item document_category @var{slot} @var{category}
+ at kindex document_category (mdb command)
Create a new category of help items, named @var{category}.
The summary text for the category is given by the lines following this command,
up to but not including a line containing only the lower-case word @samp{end}.
@@ -2380,6 +2604,7 @@
is ordered on the integer @var{slot} numbers of the categories involved.
@sp 1
@item document @var{category} @var{slot} @var{item}
+ at kindex document (mdb command)
Create a new help item named @var{item} in the help category @var{category}.
The text for the help item is given by the lines following this command,
up to but not including a line containing only the lower-case word @samp{end}.
@@ -2387,6 +2612,7 @@
is ordered on the integer @var{slot} numbers of the items involved.
@sp 1
@item help @var{category} @var{item}
+ at kindex help (mdb command)
Prints help text about the item @var{item} in category @var{category}.
@sp 1
@item help @var{word}
@@ -2402,6 +2628,7 @@
@sp 1
@table @code
@item histogram_all @var{filename}
+ at kindex histogram_all (mdb command)
Prints (to file @var{filename})
a histogram that counts all events at various depths
since the start of the program.
@@ -2409,6 +2636,7 @@
only in some experimental versions of the Mercury runtime system.
@sp 1
@item histogram_exp @var{filename}
+ at kindex histogram_exp (mdb command)
Prints (to file @var{filename})
a histogram that counts all events at various depths
since the start of the program or since the histogram was last cleared.
@@ -2416,6 +2644,7 @@
only in some experimental versions of the Mercury runtime system.
@sp 1
@item clear_histogram
+ at kindex clear_histogram (mdb command)
Clears the histogram printed by @samp{histogram_exp},
i.e. sets the counts for all depths to zero.
@end table
@@ -2427,16 +2656,20 @@
@sp 1
@table @code
@item nondet_stack
+ at kindex nondet_stack (mdb command)
Prints the contents of the fixed slots of the frames on the nondet stack.
@sp 1
@item stack_regs
+ at kindex stack_regs (mdb command)
Prints the contents of the virtual machine registers
that point to the det and nondet stacks.
@sp 1
@item all_regs
+ at kindex all_regs (mdb command)
Prints the contents of all the virtual machine registers.
@sp 1
@item table_io
+ at kindex table_io (mdb command)
Reports which phase of I/O tabling we are in at the moment.
@sp 1
@item table_io stats
@@ -2449,6 +2682,7 @@
Tells the debugger to stop tabling I/O actions.
@sp 1
@item proc_stats
+ at kindex proc_stats (mdb command)
Prints statistics about proc layout structures in the program.
@sp 1
@item proc_stats @var{filename}
@@ -2456,6 +2690,7 @@
to the file @var{filename}.
@sp 1
@item label_stats
+ at kindex label_stats (mdb command)
Prints statistics about label layout structures in the program.
@sp 1
@item label_stats @var{filename}
@@ -2467,17 +2702,20 @@
@sp 1
@table @code
@item source [-i] @var{filename}
+ at kindex source (mdb command)
Executes the commands in the file named @var{filename}.
@sp 1
The option @samp{-i} or @samp{--ignore-errors} tells @samp{mdb}
not to complain if the named file does not exist or is not readable.
@sp 1
@item save @var{filename}
+ at kindex save (mdb command)
Saves current set of breakpoints and the current set of aliases
in the named file as a set of @samp{break} and @samp{alias} commands.
Sourcing the file will recreate the current breakpoints and aliases.
@sp 1
@item quit [-y]
+ at kindex quit (mdb command)
Quits the debugger and aborts the execution of the program.
If the option @samp{-y} is not present, asks for confirmation first.
Any answer starting with @samp{y}, or end-of-file, is considered confirmation.
@@ -2485,9 +2723,14 @@
End-of-file on the debugger's input is considered a quit command.
@end table
+ at c ----------------------------------------------------------------------------
+
@ifset aditi
@node Using Aditi
@chapter Using Aditi
+ at cindex Aditi
+ at cindex database, deductive
+ at cindex deductive database
The Mercury compiler allows compilation of predicates for execution
using the Aditi2 deductive database system. There are several sources
@@ -2516,8 +2759,19 @@
@end ifset
+ at c ----------------------------------------------------------------------------
+
@node Profiling
@chapter Profiling
+ at pindex mprof
+ at pindex mdprof
+ at cindex Profiling
+ at cindex Profiling memory allocation
+ at cindex Time profiling
+ at cindex Heap profiling
+ at cindex Memory profiling
+ at cindex Allocation profiling
+ at cindex Deep profiling
@menu
* Profiling introduction:: What is profiling useful for?
@@ -2534,6 +2788,10 @@
@node Profiling introduction
@section Profiling introduction
+ at cindex Profiling
+ at cindex Measuring performance
+ at cindex Optimization
+ at cindex Efficiency
To obtain the best trade-off between productivity and efficiency,
programmers should not spend too much time optimizing their code
@@ -2555,6 +2813,14 @@
@node Building profiled applications
@section Building profiled applications
+ at cindex Building profiled applications
+ at pindex mprof
+ at pindex mdprof
+ at cindex Time profiling
+ at cindex Heap profiling
+ at cindex Memory profiling
+ at cindex Allocation profiling
+ at cindex Deep profiling
To enable profiling, your program must be built with profiling enabled.
The two different profilers require different support,
@@ -2598,6 +2864,15 @@
@node Creating profiles
@section Creating profiles
+ at cindex Profiling
+ at cindex Creating profiles
+ at pindex mprof
+ at pindex mdprof
+ at cindex Time profiling
+ at cindex Heap profiling
+ at cindex Memory profiling
+ at cindex Allocation profiling
+ at cindex Deep profiling
Once you have created a profiled executable,
you can gather profiling information by running the profiled executable
@@ -2658,12 +2933,17 @@
@node Using mprof for time profiling
@section Using mprof for time profiling
+ at pindex mprof
+ at cindex Time profiling
To display the graph profile information
gathered from one or more profiling runs,
just type @samp{mprof} or @samp{mprof -c}.
(For programs built with @samp{--high-level-code},
you need to also pass the @samp{--no-demangle} option to @samp{mprof} as well.)
+ at findex --high-level-code
+ at findex --demangle
+ at findex --no-demangle
Note that @samp{mprof} can take quite a while to execute
(especially with @samp{-c}),
and will usually produce quite a lot of output,
@@ -2676,6 +2956,7 @@
The output of @samp{mprof} contains
the flat profile and the alphabetic listing only.
+ at cindex Call graph profile
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,
@@ -2684,6 +2965,7 @@
in the procedure and all of its descendents
(i.e. all of the procedures that it calls, directly or indirectly.)
+ at cindex Flat profile
The flat profile presents the just execution time spent in each procedure.
It does not count the time spent in descendents of a procedure.
@@ -2692,6 +2974,7 @@
so that you can quickly find the entry for a particular procedure
in the call graph profile.
+ at cindex Profiling interrupts
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
@@ -2713,6 +2996,7 @@
(The deep profiler does not make such an assumption,
and hence its output is significantly more reliable.)
+ at cindex Garbage collection, profiling
Note that any time spent in a C function
(e.g. time spent in @samp{GC_malloc()},
which does memory allocation and garbage collection)
@@ -2852,6 +3136,11 @@
@node Using mprof for memory profiling
@section Using mprof for memory profiling
+ at pindex mprof
+ at cindex Memory profiling
+ at cindex Allocation profiling
+ at cindex Heap profiling
+ at cindex Profiling memory allocation
To create a memory profile, you can invoke @samp{mprof}
with the @samp{-m} (@samp{--profile memory-words}) option.
@@ -2881,6 +3170,8 @@
@node Using mdprof
@section Using mdprof
+ at pindex mdprof
+ at cindex Deep profiling
To display the information contained in a deep profiling data file
(which will be called @file{Deep.data} unless you renamed it),
@@ -2898,6 +3189,10 @@
@node Profiling and shared libraries
@section Profiling and shared libraries
+ at pindex mprof
+ at cindex Shared libraries and profiling
+ at cindex Profiling and shared libraries
+ at vindex LD_BIND_NOW
On some operating systems,
Mercury's profiling doesn't work properly with shared libraries.
@@ -2916,6 +3211,8 @@
Another work-around that sometimes works is to set the environment variable
@samp{LD_BIND_NOW} to a non-null value before running the program.
+ at c ----------------------------------------------------------------------------
+
@node Invocation
@chapter Invocation
@@ -2923,6 +3220,7 @@
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.
+ at findex --help
@menu
* Invocation overview::
@@ -2964,16 +3262,21 @@
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}.
+ at findex --no-
@node Warning options
@section Warning options
+ at cindex Warning options
@table @code
@item -w
@itemx --inhibit-warnings
+ at findex -w
+ at findex --inhibit-warnings
Disable all warning messages.
@sp 1
@item --halt-at-warn
+ at findex --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
@@ -2982,21 +3285,27 @@
@sp 1
@item --halt-at-syntax-error
+ at findex --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 --inhibit-accumulator-warnings
+ at findex --inhibit-accumulator-warnings
Don't warn about argument order rearrangement caused by
@samp{--introduce-accumulators}.
@sp 1
@item --no-warn-singleton-variables
+ at findex --no-warn-singleton-variables
+ at findex --warn-singleton-variables
Don't warn about variables which only occur once.
@sp 1
@item --no-warn-missing-det-decls
+ at findex --no-warn-missing-det-decls
+ at findex --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.
@@ -3005,33 +3314,42 @@
@sp 1
@item --no-warn-det-decls-too-lax
+ at findex --no-warn-det-decls-too-lax
+ at findex --warn-det-decls-too-lax
Don't warn about determinism declarations
which could have been stricter.
@sp 1
@item --no-warn-nothing-exported
+ at findex --no-warn-nothing-exported
+ at findex --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
+ at findex --warn-unused-args
Warn about predicate or function arguments which are not used.
@sp 1
@item --warn-interface-imports
+ at findex --warn-interface-imports
Warn about modules imported in the interface which are not
used in the interface.
@sp 1
@item --warn-missing-opt-files
+ at findex --warn-missing-opt-files
Warn about @samp{.opt} files that cannot be opened.
@sp 1
@item --warn-missing-trans-opt-files
+ at findex --warn-missing-trans-opt-files
Warn about @samp{.trans_opt} files that cannot be opened.
@sp 1
@item --warn-non-stratification
+ at findex --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
@@ -3039,21 +3357,28 @@
@sp 1
@item --no-warn-simple-code
+ at findex --no-warn-simple-code
+ at findex --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
+ at findex --warn-duplicate-calls
Warn about multiple calls to a predicate with the same
input arguments.
@sp 1
@item --no-warn-missing-module-name
+ at findex --no-warn-missing-module-name
+ at findex --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
+ at findex --no-warn-wrong-module-name
+ at findex --warn-wrong-module-name
Disable warnings for modules whose @samp{:- module} declaration
does not match the module's file name.
@@ -3061,60 +3386,82 @@
@node Verbosity options
@section Verbosity options
+ at cindex Verbosity options
@table @code
@item -v
@itemx --verbose
+ at findex -v
+ at findex --verbose
Output progress messages at each stage in the compilation.
@sp 1
@item -V
@itemx --very-verbose
+ at findex -V
+ at findex --very-verbose
Output very verbose progress messages.
@sp 1
@item -E
@itemx --verbose-error-messages
+ at findex -E
+ at findex --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
+ at findex -S
+ at findex --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.
+ at findex --no-trad-passes
+ at findex --trad-passes
@sp 1
@item -T
@itemx --debug-types
+ at findex -T
+ at findex --debug-types
Output detailed debugging traces of the type checking.
@sp 1
@item -N
@itemx --debug-modes
+ at findex -N
+ at findex --debug-modes
Output detailed debugging traces of the mode checking.
@sp 1
- at item --debug-det, --debug-determinism
+ at item --debug-det
+ at itemx --debug-determinism
+ at findex --debug-det
+ at findex --debug-determinism
Output detailed debugging traces of determinism analysis.
@sp 1
@item --debug-opt
+ at findex --debug-opt
Output detailed debugging traces of the optimization process.
@sp 1
@item --debug-pd
+ at findex --debug-pd
Output detailed debugging traces of the partial
deduction and deforestation process.
@ifset aditi
@sp 1
@item --debug-rl-gen
+ at findex --debug-rl-gen
Output detailed debugging traces of Aditi-RL code generation
(@pxref{Using Aditi}).
@sp 1
@item --debug-rl-opt
+ at findex --debug-rl-opt
Output detailed debugging traces of Aditi-RL optimization
(@pxref{Using Aditi}).
@end ifset
@@ -3122,6 +3469,7 @@
@sp 1
@item --debug-liveness <n>
+ at findex --debug-liveness
Output detailed debugging traces of the liveness analysis
of the predicate with the given predicate id.
@@ -3139,6 +3487,9 @@
@table @code
@item -M
@itemx --generate-dependencies
+ at findex -M
+ at findex --generate-dependencies
+ at cindex dependencies
Output ``Make''-style dependencies for the module and all of its
dependencies to @file{@var{module}.dep}, @file{@var{module}.dv} and the
relevant @samp{.d} files.
@@ -3152,30 +3503,41 @@
@item -i
@itemx --make-int
@itemx --make-interface
+ at findex -i
+ at findex --make-int
+ at findex --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
+ at findex --make-short-int
+ at findex --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
+ at findex --make-priv-int
+ at findex --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
+ at findex --make-opt-int
+ at findex --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
+ at findex --make-trans-opt
+ at findex --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
@@ -3190,6 +3552,9 @@
@item -P
@itemx --pretty-print
@itemx --convert-to-mercury
+ at findex -P
+ at findex --pretty-print
+ at findex --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
@@ -3198,6 +3563,7 @@
@sp 1
@item --typecheck-only
+ at findex --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,
@@ -3208,11 +3574,15 @@
@sp 1
@item -e
@itemx --errorcheck-only
+ at findex -e
+ at findex --errorcheck-only
Check the module for errors, but do not generate any code.
@sp 1
@item -C
@itemx --target-code-only
+ at findex -C
+ at findex --target-code-only
Generate target code (i.e. C in @file{@var{module}.c},
assembler in @file{@var{module}.s} or @file{@var{module}.pic_s},
IL in @file{@var{module}.il} or Java in @file{@var{module}.java}),
@@ -3221,6 +3591,8 @@
@sp 1
@item -c
@itemx --compile-only
+ at findex -c
+ at findex --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.
@@ -3228,6 +3600,7 @@
@ifset aditi
@sp 1
@item --aditi-only
+ at findex --aditi-only
Write Aditi-RL bytecode to @file{@var{module}.rlo} and do not compile to C
(@pxref{Using Aditi}).
@end ifset
@@ -3235,6 +3608,7 @@
@sp 1
@item --output-grade-string
+ at findex --output-grade-string
Compute from the rest of the option settings the canonical grade
string and print it on the standard output.
@end table
@@ -3243,21 +3617,27 @@
@section Auxiliary output options
@table @code
@item --no-assume-gmake
+ at findex --no-assume-gmake
+ at findex --assume-gmake
When generating @file{.d}, @file{.dep} and @file{.dv} files,
generate Makefile fragments that use only the features of standard make;
do not assume the availability of GNU Make extensions.
This can make these files significantly larger.
@item --trace-level @var{level}
+ at findex --trace-level @var{level}
Generate code that includes the specified level of execution tracing.
The @var{level} should be one of
@samp{none}, @samp{shallow}, @samp{deep}, and @samp{default}.
See @ref{Debugging}.
@item --trace-optimized
+ at findex --trace-optimized
Do not disable optimizations that can change the trace.
@item --no-delay-death
+ at findex --no-delay-death
+ at findex --delay-death
When the trace level is `deep', the compiler normally
preserves the values of variables as long as possible, even
beyond the point of their last use, in order to make them
@@ -3265,11 +3645,13 @@
However, it will not do this if this option is given.
@item --stack-trace-higher-order
+ at findex --stack-trace-higher-order
Enable stack traces through predicates and functions with
higher-order arguments, even if stack tracing is not
supported in general.
@item --generate-bytecode
+ at findex --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
@@ -3279,26 +3661,36 @@
by an experimental debugger.
@item --auto-comments
+ at findex --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.
+ at findex --no-llds-optimize
+ at findex --llds-optimize
@sp 1
- at item -n-, --no-line-numbers
+ at item -n-
+ at itemx --no-line-numbers
+ at findex -n-
+ at findex --no-line-numbers
+ at findex --line-numbers
Do not put source line numbers in the generated code.
The generated code may be in C (the usual case)
or in Mercury (with @samp{--convert-to-mercury}).
@sp 1
@item --show-dependency-graph
+ at findex --show-dependency-graph
Write out the dependency graph to @var{module}.dependency_graph.
@sp 1
@item -d @var{stage}
@itemx --dump-hlds @var{stage}
+ at findex -d
+ at findex --dump-hlds
Dump the HLDS (intermediate representation) after
the specified stage number or stage name to
@file{@var{module}.hlds_dump. at var{num}- at var{name}}.
@@ -3308,6 +3700,7 @@
@sp 1
@item --dump-hlds-options @var{options}
+ at findex --dump-hlds-options
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.
@@ -3338,18 +3731,21 @@
@ifset aditi
@sp 1
@item --dump-rl
+ at findex --dump-rl
Output a human readable form of the internal compiler representation
of the generated Aditi-RL code to @file{@var{module}.rl_dump}
(@pxref{Using Aditi}).
@sp 1
@item --dump-rl-bytecode
+ at findex --dump-rl-bytecode
Output a human readable representation of the generated Aditi-RL
bytecodes @file{@var{module}.rla}. Aditi-RL bytecodes are directly
executed by the Aditi system (@pxref{Using Aditi}).
@sp 1
@item --generate-schemas
+ at findex --generate-schemas
Output schema strings for Aditi base relations to
@file{@var{module}.base_schema} and for Aditi derived
relations to @file{@var{module}.derived_schema}. A schema
@@ -3363,53 +3759,82 @@
@node Language semantics options
@section Language semantics options
+ at cindex Language semantics options
+ at cindex Semantics options
+ at cindex Order of execution
+ at cindex Reordering
+ at cindex Optimization
See the Mercury language reference manual for detailed explanations
of these options.
@table @code
@item --no-reorder-conj
+ at findex --no-reorder-conj
+ at findex --reorder-conj
Execute conjunctions left-to-right except where the modes imply
that reordering is unavoidable.
@sp 1
@item --no-reorder-disj
+ at findex --no-reorder-disj
+ at findex --reorder-disj
Execute disjunctions strictly left-to-right.
@sp 1
@item --fully-strict
+ at findex --fully-strict
Don't optimize away loops or calls to @code{error/1}.
@sp 1
@item --infer-all
+ at findex --infer-all
+ at cindex Inference
An abbreviation for @samp{--infer-types --infer-modes --infer-det}.
@sp 1
@item --infer-types
+ at findex --infer-types
+ at cindex Inference of 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
+ at findex --infer-modes
+ at cindex Inference of modes
If there is no mode declaration for a predicate,
try to infer the modes, rather than just reporting an error.
@sp 1
- at item --no-infer-det, --no-infer-determinism
+ at item --no-infer-det
+ at itemx --no-infer-determinism
+ at findex --no-infer-det
+ at findex --no-infer-determinism
+ at findex --infer-det
+ at findex --infer-determinism
+ at cindex Determinism inference
+ at cindex Inference of 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}
+ at findex --type-inference-iteration-limit
+ at cindex Inference of types
+ at cindex Type inference
Perform at most @var{n} passes of type inference (default: 60).
@sp 1
@item --mode-inference-iteration-limit @var{n}
+ at cindex Inference of modes
+ at cindex Mode inference
Perform at most @var{n} passes of mode inference (default: 30).
@end table
@node Termination analysis options
@section Termination analysis options
+ at cindex Termination analysis options
For detailed explanations, see the ``Termination analysis'' section
of the ``Implementation-dependent extensions'' chapter in the Mercury
@@ -3418,6 +3843,8 @@
@table @code
@item --enable-term
@itemx --enable-termination
+ at findex --enable-term
+ at findex --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}
@@ -3429,6 +3856,9 @@
@item --chk-term
@itemx --check-term
@itemx --check-termination
+ at findex --chk-term
+ at findex --check-term
+ at findex --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
@@ -3441,12 +3871,17 @@
@item --verb-chk-term
@itemx --verb-check-term
@itemx --verbose-check-termination
+ at findex --verb-chk-term
+ at findex --verb-check-term
+ at findex --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}
+ at findex --term-single-arg @var{limit}
+ at findex --termination-single-argument-analysis
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.
@@ -3454,6 +3889,7 @@
@sp 1
@item --termination-norm @var{norm}
+ at findex --termination-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.
@@ -3464,17 +3900,29 @@
@sp 1
@item --term-err-limit @var{limit}
@itemx --termination-error-limit @var{limit}
+ at findex --term-err-limit
+ at findex --termination-error-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}
+ at findex --term-path-limit
+ at findex --termination-path-limit
Perform termination analysis only on predicates with at most @var{n} paths.
@end table
@node Compilation model options
@section Compilation model options
+ at cindex Link errors
+ at cindex Undefined symbol
+ at cindex Compilation model options
+ at cindex Compilation models
+ at cindex Compilation grades
+ at cindex Grades
+ at cindex ABI (Application Binary Interface)
+ at cindex Application Binary Interface (ABI)
The following compilation options affect the generated
code in such a way that the entire program must be
@@ -3492,10 +3940,16 @@
these options in the @samp{GRADEFLAGS} variable rather than specifying
them in @samp{MCFLAGS}, @samp{MGNUCFLAGS}, @samp{C2INITFLAGS}
and @samp{MLFLAGS}.
+ at vindex GRADEFLAGS
+ at vindex MCFLAGS
+ at vindex MGNUCFLAGS
+ at vindex C2INITFLAGS
@table @asis
@item @code{-s @var{grade}}
@itemx @code{--grade @var{grade}}
+ at findex -s
+ at findex --grade
Select the compilation model.
The @var{grade} should be a @samp{.} separated list of the
grade options to set. The grade options may be given in any order.
@@ -3503,6 +3957,33 @@
exclusive alternatives governing a single aspect of the compilation model.
The set of aspects and their alternatives are:
+ at cindex none (compilation grade)
+ at cindex reg (compilation grade)
+ at cindex jump (compilation grade)
+ at cindex asm_jump (compilation grade)
+ at cindex fast (compilation grade)
+ at cindex asm_fast (compilation grade)
+ at cindex hlc (compilation grade)
+ at cindex ilc (compilation grade)
+ at cindex java (compilation grade)
+ at cindex .prof (grade modifier)
+ at cindex .memprof (grade modifier)
+ at cindex .profdeep (grade modifier)
+ at cindex .tr (grade modifier)
+ at cindex .gc (grade modifier)
+ at cindex .agc (grade modifier)
+ at cindex .rt (grade modifier)
+ at cindex .debug (grade modifier)
+ at cindex .par (grade modifier)
+ at cindex prof (grade modifier)
+ at cindex memprof (grade modifier)
+ at cindex profdeep (grade modifier)
+ at cindex tr (grade modifier)
+ at cindex gc (grade modifier)
+ at cindex agc (grade modifier)
+ at cindex rt (grade modifier)
+ at cindex debug (grade modifier)
+ at cindex par (grade modifier)
@table @asis
@item What target language to use, and (for C) what combination of GNU C extensions to use:
@samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump},
@@ -3535,6 +4016,7 @@
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.
+ at vindex MERCURY_DEFAULT_GRADE
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
@@ -3548,12 +4030,26 @@
@table @asis
@item @var{Grade}
@var{Options implied}.
+ at findex --gcc-global-registers
+ at findex --no-gcc-global-registers
+ at findex --gcc-nonlocal-gotos
+ at findex --no-gcc-nonlocal-gotos
+ at findex --asm-labels
+ at findex --no-asm-labels
+ at findex --high-level-code
+ at findex --no-high-level-code
+ at findex --target
+ at findex --il
+ at findex --gc
+ at findex --profiling
+ at findex --memory-profiling
+ at findex --deep-profiling
@item @samp{none}
- at code{--target c --no-gcc-global-registers --no-gcc-nonlocal_gotos --no-asm-labels}.
+ at code{--target c --no-gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}.
@item @samp{reg}
- at code{--target c --gcc-global-registers --no-gcc-nonlocal_gotos --no-asm-labels}.
+ at code{--target c --gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}.
@item @samp{jump}
@code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --no-asm-labels}.
@@ -3565,7 +4061,7 @@
@code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --asm-labels}.
@item @samp{asm_fast}
- at code{--target c --gcc-global-registers --gcc-nonlocal_gotos --asm-labels}.
+ at code{--target c --gcc-global-registers --gcc-nonlocal-gotos --asm-labels}.
@item @samp{hlc}
@code{--target c --high-level-code}.
@@ -3629,6 +4125,7 @@
@sp 1
@item @code{--il-only}
+ at findex --il-only
An abbreviation for @samp{--target il --target-code-only}.
Generate IL assembler code in @file{@var{module}.il}, but do not invoke
ilasm to produce IL object code.
@@ -3636,12 +4133,14 @@
@sp 1
@item @code{--compile-to-c}
@itemx @code{--compile-to-C}
+ at findex --compile-to-c
An abbreviation for @samp{--target c --target-code-only}.
Generate C code in @file{@var{module}.c}, but do not invoke the
C compiler to generate object code.
@sp 1
@item @code{--java-only}
+ at findex --java-only
An abbreviation for @samp{--target java --target-code-only}.
Generate Java code in @file{@var{module}.java}, but do not invoke
the Java compiler to produce Java bytecode.
@@ -3649,24 +4148,32 @@
@sp 1
@item @code{--gcc-global-registers} (grades: reg, fast, asm_fast)
@itemx @code{--no-gcc-global-registers} (grades: none, jump, asm_jump)
+ at findex --gcc-global-registers
+ at findex --no-gcc-global-registers
Specify whether or not to use GNU C's global register variables extension.
This option is ignored if the @samp{--high-level-code} option is enabled.
@sp 1
@item @code{--gcc-non-local-gotos} (grades: jump, fast, asm_jump, asm_fast)
@itemx @code{--no-gcc-non-local-gotos} (grades: none, reg)
+ at findex --gcc-non-local-gotos
+ at findex --no-gcc-non-local-gotos
Specify whether or not to use GNU C's ``labels as values'' extension.
This option is ignored if the @samp{--high-level-code} option is enabled.
@sp 1
@item @code{--asm-labels} (grades: asm_jump, asm_fast)
@itemx @code{--no-asm-labels} (grades: none, reg, jump, fast)
+ at findex --asm-labels
+ at findex --no-asm-labels
Specify whether or not to use GNU C's asm extensions
for inline assembler labels.
This option is ignored if the @samp{--high-level-code} option is enabled.
@sp 1
@item @code{-H}, @code{--high-level-code} (grades: hlc, ilc, java)
+ at findex -H
+ at findex --high-level-code
Use an alternative back-end that generates high-level code
rather than the very low-level code that is generated by our
original back-end.
@@ -3674,6 +4181,11 @@
@sp 1
@item @code{--gc @{none, conservative, accurate@}}
@itemx @code{--garbage-collection @{none, conservative, accurate@}}
+ at cindex Garbage collection
+ at cindex Conservative garbage collection
+ at cindex Accurate garbage collection
+ at findex --gc
+ at findex --garbage-collection
Specify which method of garbage collection to use.
Grades containing @samp{.gc} use @samp{--gc conservative},
other grades use @samp{--gc none}.
@@ -3683,6 +4195,10 @@
@sp 1
@item @code{--profiling}, @code{--time-profiling} (grades: any grade containing @samp{.prof})
+ at cindex Profiling
+ at cindex Time profiling
+ at findex --profiling
+ at findex --time-profiling
Enable time profiling. Insert profiling hooks in the
generated code, and also output some profiling
information (the static call graph) to the file
@@ -3691,6 +4207,11 @@
@sp 1
@item @code{--memory-profiling} (grades: any grade containing @samp{.memprof})
+ at findex --memory-profiling
+ at cindex Profiling
+ at cindex Memory profiling
+ at cindex Heap profiling
+ at cindex Allocation profiling
Enable memory profiling. Insert memory profiling hooks in the
generated code, and also output some profiling
information (the static call graph) to the file
@@ -3699,6 +4220,8 @@
@sp 1
@item @code{--deep-profiling} (grades: any grade containing @samp{.profdeep})
+ at findex --deep-profiling
+ at cindex Deep profiling
Enable deep profiling by inserting the appropriate hooks in the generated code.
This option is not supported for the high-level C, IL and Java back-ends.
@@ -3707,12 +4230,14 @@
@sp 1
@item @code{--profile-calls} (grades: any grade containing @samp{.profcalls})
+ at findex --profile-calls
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})
+ at findex --profile-time
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
@@ -3729,18 +4254,27 @@
@sp 1
@item @code{--debug} (grades: any grade containing @samp{.debug})
+ at findex --debug
+ at cindex Debugging
Enables the inclusion in the executable of code and data structures
that allow the program to be debugged with @samp{mdb} (see @ref{Debugging}).
This option is not yet supported for the @samp{--high-level-code} back-ends.
@sp 1
@item @code{--use-trail} (grades: any grade containing @samp{.tr})
+ at findex --use-trail
+ at cindex Trailing
+ at cindex Constraint solving
+ at cindex Backtrackable destructive update
+ at cindex Destructive update, backtrackable
Enable use of a trail.
This is necessary for interfacing with constraint solvers,
or for backtrackable destructive update.
This option is not yet supported for the IL or Java back-ends.
@sp 1
@item @code{--reserve-tag} (grades: any grade containing @samp{.rt})
+ at findex --reserve-tag
+ at cindex Tags
Reserve a tag in the data representation of the generated
code. This tag is intended to be used to give an explicit
representation to free variables.
@@ -3748,6 +4282,11 @@
for use with HAL.
@sp 1
@item @code{--pic-reg} (grades: any grade containing `.pic_reg')
+ at findex --pic-reg
+ at findex -fpic
+ at cindex Position independent code
+ at cindex PIC (position independent code)
+ at cindex Shared libraries
[For Unix with intel x86 architecture only.]
Select a register usage convention that is compatible
with position-independent code (gcc's `-fpic' option).
@@ -3763,6 +4302,7 @@
@node Developer compilation model options
@subsection Developer compilation model options
+ at cindex Cross-compiling
Of the options listed below, the @samp{--num-tag-bits} option
may be useful for cross-compilation, but apart from that
these options are all experimental and are intended for
@@ -3772,12 +4312,16 @@
@table @asis
@sp 1
@item @code{--tags @{none, low, high@}}
+ at findex --tags
+ at cindex Tags
(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}}
+ at findex --num-tag-bits
+ at cindex Tags
(This option is not intended for general use.)@*
Use @var{n} tag bits. This option is required if you specify
@samp{--tags high}.
@@ -3786,6 +4330,9 @@
@sp 1
@item @code{--use-foreign-language @var{foreign language}}
+ at findex --use-foreign-language
+ at cindex Foreign language interfacing
+ at cindex Interfacing with other languages
Use the given foreign language to implement predicates
written in foreign languages. Any name that can be used
to specify foreign languages in @samp{pragma foreign} declarations
@@ -3796,6 +4343,8 @@
@sp 1
@item @code{--no-type-layout}
+ at findex --no-type-layout
+ at findex --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
@@ -3808,9 +4357,11 @@
@node Code generation options
@section Code generation options
+ at cindex Code generation options
@table @code
- at item @code{--low-level-debug}
+ at item --low-level-debug
+ at findex --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
@@ -3818,7 +4369,10 @@
inefficient, and slows down compilation a lot.
@sp 1
- at item @code{--pic}
+ at item --pic
+ at findex --pic
+ at cindex Position independent code
+ at cindex PIC (position independent code)
Generate position independent code.
This option is only used by the @samp{--target asm} back-end.
The generated assembler will be written to @samp{@var{module}.pic_s}
@@ -3826,6 +4380,9 @@
@sp 1
@item @code{--target-debug}
+ at findex @code{--target-debug}
+ at findex @code{--c-debug}
+ at findex @code{/debug}
Enable debugging of the generated target code.
If the target language is C, this has the same effect as
@samp{--c-debug} (see below).
@@ -3834,6 +4391,8 @@
@sp 1
@item --no-trad-passes
+ at findex --no-trad-passes
+ at findex --trad-passes
The default @samp{--trad-passes} completely processes each predicate
before going on to the next predicate.
This option tells the compiler
@@ -3848,22 +4407,33 @@
@sp 1
@item --no-reclaim-heap-on-nondet-failure
+ at findex --no-reclaim-heap-on-nondet-failure
+ at findex --reclaim-heap-on-nondet-failure
Don't reclaim heap on backtracking in nondet code.
@sp 1
@item --no-reclaim-heap-on-semidet-failure
+ at findex --no-reclaim-heap-on-semidet-failure
+ at findex --reclaim-heap-on-semidet-failure
Don't reclaim heap on backtracking in semidet code.
@sp 1
@item --no-reclaim-heap-on-failure
+ at findex --no-reclaim-heap-on-failure
+ at findex --reclaim-heap-on-failure
Combines the effect of the two options above.
@sp 1
@item --cc @var{compiler-name}
+ at findex --cc
+ at cindex C compiler
Specify which C compiler to use.
@sp 1
@item --c-include-directory @var{dir}
+ at findex --c-include-directory
+ at cindex Include directories
+ at cindex Directories
Append @var{dir} to the list of directories to be searched for
C header files. Note that if you want to override this list, rather than
append to it, then you can set the @samp{MERCURY_MC_ALL_C_INCL_DIRS}
@@ -3871,10 +4441,15 @@
@sp 1
@item --cflags @var{options}
+ at findex --cflags
+ at cindex C compiler options
Specify options to be passed to the C compiler.
@sp 1
@item @code{--c-debug}
+ at findex --c-debug
+ at cindex C debugging
+ at cindex Debugging the generated C code
Pass the @samp{-g} flag to the C compiler, to enable debugging
of the generated C code, and also pass @samp{--no-strip} to the Mercury
linker, to tell it not to strip the C debugging information.
@@ -3885,23 +4460,36 @@
@sp 1
@item --javac @var{compiler-name}
@item --java-compiler @var{compiler-name}
+ at findex --javac
+ at findex --java-compiler
+ at cindex Java compiler
Specify which Java compiler to use. The default is @samp{javac}.
@sp 1
@item --java-flags @var{options}
+ at findex --java-flags
+ at cindex Java compiler options
Specify options to be passed to the Java compiler.
@sp 1
@item --java-classpath @var{dir}
+ at findex --java-classpath
+ at cindex classpath
+ at cindex Directories
Set the classpath for the Java compiler.
@sp 1
@item --java-object-file-extension @var{extension}
+ at findex --java-object-file-extension
+ at cindex File extensions
Specify an extension for Java object (bytecode) files. By default this
is @samp{.class}.
@sp 1
@item --fact-table-max-array-size @var{size}
+ at findex --fact-table-max-array-size @var{size}
+ at cindex Fact tables
+ at cindex pragma fact_table
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
@@ -3910,6 +4498,9 @@
@sp 1
@item --fact-table-hash-percent-full @var{percentage}
+ at findex --fact-table-hash-percent-full
+ at cindex Fact tables
+ at cindex pragma fact_table
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
@@ -3924,6 +4515,8 @@
@node Code generation target options
@subsection Code generation target options
+ at cindex Target options
+ at cindex Cross-compiling
The following options allow the Mercury compiler to optimize the generated
C code based on the characteristics of the expected target architecture.
@@ -3936,26 +4529,31 @@
@table @asis
@item @code{--have-delay-slot}
+ at findex --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}}
+ at findex --num-real-r-regs
(This option is not intended for general use.)@*
Assume r1 up to r at var{n} are real general purpose registers.
@sp 1
@item @code{--num-real-f-regs @var{n}}
+ at findex --num-real-f-regs
(This option is not intended for general use.)@*
Assume f1 up to f at var{n} are real floating point registers.
@sp 1
@item @code{--num-real-r-temps @var{n}}
+ at findex --num-real-r-temps
(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}}
+ at findex --num-real-f-temps
(This option is not intended for general use.)@*
Assume that @var{n} float temporaries will fit into real machine registers.
@@ -3963,6 +4561,7 @@
@node Optimization options
@section Optimization options
+ at cindex Optimization options
@menu
* Overall optimization options::
@@ -3984,6 +4583,13 @@
@item -O @var{n}
@itemx --opt-level @var{n}
@itemx --optimization-level @var{n}
+ at findex -O
+ at findex --opt-level
+ at findex --optimization-level
+ at cindex Optimization levels
+ at cindex Compilation speed
+ at cindex Intermodule optimization
+ at cindex Cross-module optimization
Set optimization level to @var{n}.
Optimization levels range from -1 to 6.
Optimization level -1 disables all optimizations,
@@ -4011,18 +4617,32 @@
@sp 1
@item --opt-space
@itemx --optimize-space
+ at findex --opt-space
+ at findex --optimize-space
+ at findex Optimizing space
+ at findex Optimizing code size
Turn on optimizations that reduce code size
and turn off optimizations that significantly increase code size.
@end table
@table @code
@item --intermodule-optimization
+ at findex --intermodule-optimization
+ at cindex Intermodule optimization
+ at cindex Cross-module optimization
+ at cindex Inlining
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
+ at findex --trans-intermod-opt
+ at findex --transitive-intermodule-optimization
+ at cindex Transitive intermodule optimization
+ at cindex Intermodule optimization, transitive
+ at cindex Cross-module optimization, transitive
+ at cindex Termination analysis
Use the information stored in @file{@var{module}.trans_opt} files
to make intermodule optimizations. The @file{@var{module}.trans_opt} files
are different to the @file{@var{module}.opt} files as @samp{.trans_opt}
@@ -4030,17 +4650,23 @@
@samp{.opt} file may only depend on the corresponding @samp{.m} file.
@item --use-opt-files
+ at findex --use-opt-files
Perform inter-module optimization using any @samp{.opt} files which are
already built, e.g. those for the standard library, but do not build any
others.
@item --use-trans-opt-files
+ at findex --use-trans-opt-files
Perform inter-module optimization using any @samp{.trans_opt} files which are
already built, e.g. those for the standard library, but do not build any
others.
@sp 1
@item --split-c-files
+ at findex --split-c-files
+ at findex --optimize-dead-procs
+ at cindex Optimizing code size
+ at cindex Optimizing space
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},
@@ -4054,6 +4680,7 @@
This option is only useful with @samp{--procs-per-c-function 1},
so this option automatically sets @samp{--procs-per-c-function 1}.
+ at findex --high-level-code
The @samp{--high-level-code} back-end does not support
@samp{--split-c-files}.
@@ -4066,30 +4693,41 @@
@node High-level (HLDS -> HLDS) optimization options
@subsection High-level (HLDS -> HLDS) optimization options
+ at cindex HLDS
These optimizations are high-level transformations on our HLDS (high-level
data structure).
@table @code
@item --no-inlining
+ at findex --no-inlining
+ at findex --inlining
+ at cindex Inlining
Disable all forms of inlining.
@item --no-inline-simple
+ at findex --no-inline-simple
+ at findex --inline-simple
Disable the inlining of simple procedures.
@item --no-inline-single-use
+ at findex --no-inline-single-use
+ at findex --inline-single-use
Disable the inlining of procedures called only once.
@item --inline-compound-threshold @var{threshold}
+ at findex --inline-compound-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}
+ at findex --inline-simple-threshold
Inline a procedure if its size is less than the given threshold.
@item --intermod-inline-simple-threshold @var{threshold}
+ at findex --intermod-inline-simple-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,
@@ -4098,10 +4736,14 @@
@sp 1
@item --no-common-struct
+ at findex --no-common-struct
+ at findex --common-struct
Disable optimization of common term structures.
@sp 1
@item --no-common-goal
+ at findex --no-common-goal
+ at findex --common-goal
Disable optimization of common goals.
At the moment this optimization
detects only common deconstruction unifications.
@@ -4109,34 +4751,46 @@
that the compiler considers to be deterministic.
@c @item --constraint-propagation
+ at c @findex --constraint-propagation
@c Enable the constraint propagation transformation.
@c @sp 1
@c @item --prev-code
+ at c @findex --prev-code
@c Migrate into the start of branched goals.
@sp 1
@item --no-follow-code
+ at findex --no-follow-code
+ at findex --follow-code
Don't migrate builtin goals into branched goals.
@sp 1
@item --optimize-unused-args
+ at findex --optimize-unused-args
+ at cindex Unused arguments
Remove unused predicate arguments. The compiler will
generate more efficient code for polymorphic predicates.
@sp 1
@item --intermod-unused-args
+ at findex --intermod-unused-args
+ at cindex Unused arguments
Perform unused argument removal across module boundaries.
This option implies @samp{--optimize-unused-args} and
@samp{--intermodule-optimization}.
@sp 1
@item --unneeded-code
+ at findex --unneeded-code
+ at cindex Unused outputs
Remove goals from computation paths where their outputs are not needed,
-provided the semantics options allow the deletion or movement of the goal.
+provided the language semantics options allow the deletion or movement
+of the goal.
@sp 1
@item --unneeded-code-copy-limit
+ at findex --unneeded-code-copy-limit
Gives the maximum number of places to which a goal may be copied
when removing it from computation paths on which its outputs are not needed.
A value of zero forbids goal movement and allows only goal deletion;
@@ -4144,16 +4798,23 @@
@sp 1
@item --optimize-higher-order
+ at findex --optimize-higher-order
+ at cindex Higher-order specialization
+ at cindex Specialization of higher-order calls
Specialize calls to higher-order predicates where
the higher-order arguments are known.
@sp 1
@item --type-specialization
+ at findex --type-specialization
+ at cindex Type specialization
Specialize calls to polymorphic predicates where
the polymorphic types are known.
@sp 1
@item --user-guided-type-specialization
+ at findex --user-guided-type-specialization
+ at cindex Type specialization, user guided
Enable specialization of polymorphic predicates for which
there are `:- pragma type_spec' declarations.
See the ``Type specialization'' section in the ``Pragmas''
@@ -4161,6 +4822,7 @@
@sp 1
@item --higher-order-size-limit
+ at findex --higher-order-size-limit
Set the maximum goal size of specialized versions created by
@samp{--optimize-higher-order} and @samp{--type-specialization}.
Goal size is measured as the number of calls, unifications
@@ -4168,42 +4830,61 @@
@sp 1
@item --optimize-constant-propagation
+ at findex --optimize-constant-propagation
Evaluate constant expressions at compile time.
@sp 1
@item --introduce-accumulators
+ at findex --introduce-accumulators
+ at cindex Accumulator introduction
+ at cindex Tail recursion optimization
+ at cindex Last call optimization
Attempt to introduce accumulating variables into
procedures, so as to make the procedure tail recursive.
@sp 1
@item --optimize-constructor-last-call
+ at findex --optimize-constructor-last-call
+ at cindex Tail recursion optimization
+ at cindex Last call optimization
Enable the optimization of ``last'' calls that are followed by
constructor application.
@sp 1
@item --optimize-dead-procs
-Enable dead predicate elimination.
+ at findex --optimize-dead-procs
+ at cindex Dead procedure elimination
+ at cindex Dead predicate elimination
+ at cindex Dead function elimination
+ at cindex Unused procedure elimination
+Enable dead procedure elimination.
@sp 1
@item --excess-assign
+ at findex --excess-assign
Remove excess assignment unifications.
@sp 1
@item --optimize-duplicate-calls
+ at findex --optimize-duplicate-calls
+ at cindex Duplicate call optimization
Optimize away multiple calls to a predicate with the same input arguments.
@sp 1
@item --delay-constructs
+ at findex --delay-constructs
Reorder goals to move construction unifications after
primitive goals that can fail.
@sp 1
@item --optimize-saved-vars
+ at findex --optimize-saved-vars
Reorder goals to minimize the number of variables
that have to be saved across calls.
@sp 1
@item --deforestation
+ at findex --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.
@@ -4212,20 +4893,27 @@
@node MLDS backend (MLDS -> MLDS) optimization options
@subsection MLDS backend (MLDS -> MLDS) optimization options
+ at cindex MLDS
These optimizations are applied to the medium level
intermediate code.
@table @code
@item --no-mlds-optimize
+ at findex --no-mlds-optimize
+ at findex --mlds-optimize
Disable the MLDS -> MLDS optimization passes.
@sp 1
@item --no-optimize-tailcalls
+ at findex --no-optimize-tailcalls
+ at findex --optimize-tailcalls
Treat tailcalls as ordinary calls rather than optimizing
by turning self-tailcalls into loops.
@item --no-optimize-initializations
+ at findex --no-optimize-initializations
+ at findex --optimize-initializations
Leave initializations of local variables as assignment statements,
rather than converting such assignments statements into initializers.
@@ -4233,12 +4921,16 @@
@node Medium-level (HLDS -> LLDS) optimization options
@subsection Medium-level (HLDS -> LLDS) optimization options
+ at cindex HLDS
+ at cindex LLDS
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
+ at findex --no-static-ground-terms
+ at findex --static-ground-terms
Disable the optimization of constructing constant ground terms
at compile time and storing them as static constants.
Note that auxiliary data structures created by the compiler
@@ -4247,111 +4939,144 @@
@sp 1
@item --no-smart-indexing
+ at findex --no-smart-indexing
+ at findex --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}
+ at findex --dense-switch-req-density
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}
+ at findex --dense-switch-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}
+ at findex --lookup-switch-req-density
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}
+ at findex --lookup-switch-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}
+ at findex --string-switch-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}
+ at findex --tag-switch-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}
+ at findex --try-switch-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}
+ at findex --binary-switch-size
The number of alternatives in a binary search switch
must be at least this number (default: 4).
@sp 1
@item --no-middle-rec
+ at findex --no-middle-rec
+ at findex --middle-rec
Disable the middle recursion optimization.
@sp 1
@item --no-simple-neg
+ at findex --no-simple-neg
+ at findex --simple-neg
Don't generate simplified code for simple negations.
@sp 1
@item --no-follow-vars
+ at findex --follow-vars
+ at findex --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
+ at cindex LLDS
These optimizations are transformations that are applied to our
low-level intermediate code before emitting C code.
@table @code
@item --no-common-data
+ at findex --no-common-data
+ at findex --common-data
Disable optimization of common data structures.
@item --no-llds-optimize
+ at findex --no-llds-optimize
+ at findex --llds-optimize
Disable the low-level optimization passes.
@sp 1
@item --no-optimize-peep
+ at findex --no-optimize-peep
+ at findex --optimize-peep
Disable local peephole optimizations.
@sp 1
@item --no-optimize-jumps
+ at findex --no-optimize-jumps
+ at findex --optimize-jumps
Disable elimination of jumps to jumps.
@sp 1
@item --no-optimize-fulljumps
+ at findex --no-optimize-fulljumps
+ at findex --optimize-fulljumps
Disable elimination of jumps to ordinary code.
@sp 1
@item --pessimize-tailcalls
+ at findex --pessimize-tailcalls
Disable the optimization of tailcalls.
@sp 1
@item --checked-nondet-tailcalls
+ at findex --checked-nondet-tailcalls
Convert nondet calls into tail calls whenever possible, even
when this requires a runtime check. This option tries to
minimize stack consumption, possibly at the expense of speed.
@sp 1
@item --use-local-vars
+ at findex --use-local-vars
Disable the transformation to use local variables in C code
blocks whereever possible.
@sp 1
@item --no-optimize-labels
+ at findex --no-optimize-labels
+ at findex --optimize-labels
Disable elimination of dead labels and code.
@sp 1
@item --optimize-dups
+ at findex --optimize-dups
Enable elimination of duplicate code.
@c @sp 1
@@ -4360,14 +5085,19 @@
@sp 1
@item --no-optimize-frames
+ at findex --no-optimize-frames
+ at findex --optimize-frames
Disable stack frame optimizations.
@sp 1
@item --no-optimize-delay-slot
+ at findex --no-optimize-delay-slot
+ at findex --optimize-delay-slot
Disable branch delay slot optimizations.
@sp 1
@item --optimize-repeat @var{n}
+ at findex --optimize-repeat
Iterate most optimizations at most @var{n} times (default: 3).
@end table
@@ -4380,15 +5110,18 @@
@table @code
@item --no-emit-c-loops
+ at findex --no-emit-c-loops
Use only gotos --- don't emit C loop constructs.
@sp 1
@item --use-macro-for-redo-fail
+ at findex --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}
+ at findex --procs-per-c-function
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
@@ -4411,10 +5144,12 @@
@table @code
@item --no-c-optimize
+ at findex --no-c-optimize
Don't enable the C compiler's optimizations.
@sp 1
@item --inline-alloc
+ at findex --inline-alloc
Inline calls to @samp{GC_malloc()}.
This can improve performance a fair bit,
but may significantly increase code size.
@@ -4431,22 +5166,27 @@
@table @code
@item --optimize-rl
+ at findex --optimize-rl
Enable the optimizations of Aditi-RL procedures described below.
@sp 1
@item --optimize-rl-cse
+ at findex --optimize-rl-cse
Optimize common subexpressions in Aditi-RL procedures.
@sp 1
@item --optimize-rl-invariants
+ at findex --optimize-rl-invariants
Optimize loop invariants in Aditi-RL procedures.
@sp 1
@item --optimize-rl-index
+ at findex --optimize-rl-index
Use indexing to optimize access to relations in Aditi-RL procedures.
@sp 1
@item --detect-rl-streams
+ at findex --detect-rl-streams
Detect cases where intermediate results in Aditi-RL procedures
do not need to be materialised.
@end table
@@ -4460,18 +5200,33 @@
@table @code
@item -I @var{dir}
@itemx --search-directory @var{dir}
+ at findex -I
+ at findex --search-directory
+ at cindex Directories
+ at cindex Search path
Append @var{dir} to the list of directories to be searched for
imported modules.
@item --intermod-directory @var{dir}
+ at findex --intermod-directory
+ at cindex Directories
+ at cindex Search path
Append @var{dir} to the list of directories to be searched for
@samp{.opt} files.
@item --use-search-directories-for-intermod
+ at findex --use-search-directories-for-intermod
+ at cindex Directories
+ at cindex Search path
Append the arguments of all -I options to the list of directories
to be searched for @samp{.opt} files.
@item --use-subdirs
+ at findex --use-subdirs
+ at cindex File names
+ at cindex Directories
+ at cindex Subdirectories
+ at cindex @file{Mercury} subdirectory
Create intermediate files in a @file{Mercury} subdirectory,
rather than in the current directory.
@@ -4479,10 +5234,15 @@
@item -?
@itemx -h
@itemx --help
+ at findex -?
+ at findex -h
+ at findex --help
+ at cindex Help option
Print a usage message.
@sp 1
@item --filenames-from-stdin
+ at findex --filenames-from-stdin
Read then compile a newline terminated module name or file name from the
standard input. Repeat this until EOF is reached. (This allows a program
or user to interactively compile several modules without the overhead of
@@ -4491,11 +5251,13 @@
@ifset aditi
@sp 1
@item --aditi
+ at findex --aditi
Enable Aditi compilation. You need to enable this option if you
are making use of the Aditi deductive database interface (@pxref{Using Aditi}).
@sp 1
@item --aditi-user
+ at findex --aditi-user
Specify the Aditi login of the owner of the predicates in any Aditi RL
files produced if no @samp{:- pragma owner(@dots{})} declaration is given.
The owner field is used along with module, name and arity to identify
@@ -4509,34 +5271,56 @@
@node Link options
@section Link options
+ at cindex Link options
+ at cindex Linker options
@table @code
@sp 1
@item -o @var{filename}
@itemx --output-file @var{filename}
+ at findex -o
+ at findex --output-file
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}
+ at findex --link-flags
+ at cindex Link options
+ at cindex Linker options
Specify options to be passed to @samp{ml}, the Mercury linker.
@sp 1
@item -L @var{directory}
@itemx --library-directory @var{directory}
+ at findex -L
+ at findex --library-directory
+ at cindex Directories for libraries
+ at cindex Search path for libraries
Append @var{dir} to the list of directories in which to search for libraries.
@item -l @var{library}
@itemx --library @var{library}
+ at findex -l
+ at findex --library
+ at cindex Libraries, linking with
Link with the specified library.
@item --link-object @var{object}
+ at findex --link-object
+ at cindex Object files, linking with
Link with the specified object file.
@end table
+ at c ----------------------------------------------------------------------------
+
@node Environment
@chapter Environment variables
+ at cindex Environment variables
+ at cindex Variables, environment
+ at cindex Directories
+ at cindex Search path
The shell scripts in the Mercury compilation environment
will use the following environment variables if they are set.
@@ -4545,10 +5329,12 @@
@table @code
@item MERCURY_DEFAULT_GRADE
+ at vindex MERCURY_DEFAULT_GRADE
The default grade to use if no @samp{--grade} option is specified.
@sp 1
@item MERCURY_C_INCL_DIR
+ at vindex 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 values of MERCURY_ALL_C_INCL_DIRS
@@ -4558,6 +5344,7 @@
@sp 1
@item MERCURY_ALL_C_INCL_DIRS
+ at vindex 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.
@@ -4569,6 +5356,7 @@
@sp 1
@item MERCURY_ALL_MC_C_INCL_DIRS
+ at vindex MERCURY_ALL_MC_C_INCL_DIRS
A list of options for mmc that specifies
all the directories it should search for the C header files
of the Mercury runtime system and garbage collector.
@@ -4581,15 +5369,18 @@
@sp 1
@item MERCURY_INT_DIR
+ at vindex 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
+ at vindex MERCURY_NC_BUILTIN
Filename of the Mercury `nc'-compatibility file (nc_builtin.nl).
@sp 1
@item MERCURY_C_LIB_DIR
+ at vindex 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
@@ -4597,6 +5388,7 @@
@sp 1
@item MERCURY_NONSHARED_LIB_DIR
+ at vindex 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
@@ -4604,33 +5396,35 @@
@sp 1
@item MERCURY_MOD_LIB_DIR
+ at vindex 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
+ at vindex MERCURY_MOD_LIB_MODS
The names of the .init files in the Mercury library.
@sp 1
@item MERCURY_COMPILER
+ at vindex MERCURY_COMPILER
Filename of the Mercury Compiler.
@sp 1
- at item MERCURY_INTERPRETER
-Filename of the Mercury Interpreter.
-
- at sp 1
@item MERCURY_MKINIT
+ at vindex MERCURY_MKINIT
Filename of the program to create the @file{*_init.c} file.
@sp 1
@item MERCURY_DEBUGGER_INIT
+ at vindex MERCURY_DEBUGGER_INIT
Name of a file that contains startup commands for the Mercury debugger.
This file should contain documentation for the debugger command set,
and possibly a set of default aliases.
@sp 1
@item MERCURY_OPTIONS
+ at vindex MERCURY_OPTIONS
A list of options for the Mercury runtime that gets
linked into every Mercury program.
Their meanings are as follows.
@@ -4647,6 +5441,7 @@
@c by mercury_engine.c was actually used.
@item -C @var{size}
+ at findex -C
Tells the runtime system
to optimize the locations of the starts of the various data areas
for a primary data cache of @var{size} kilobytes.
@@ -4654,6 +5449,7 @@
to differ as much as possible modulo this size.
@c @item -d @var{debugflag}
+ at c @findex -d
@c Sets a low-level debugging flag.
@c These flags are consulted only if
@c the runtime was compiled with the appropriate definitions;
@@ -4664,6 +5460,7 @@
@sp 1
@item -D @var{debugger}
+ at findex -D
Enables execution tracing of the program,
via the internal debugger if @var{debugger} is @samp{i}
and via the external debugger if @var{debugger} is @samp{e}.
@@ -4672,25 +5469,30 @@
@sp 1
@item -p
+ at findex -p
Disables profiling.
This only has an effect if the executable was built in a profiling grade.
@sp 1
@item -P @var{num}
+ at findex -P
Tells the runtime system to use @var{num} threads
if the program was built in a parallel grade.
@c @item -r @var{num}
+ at c @findex -r
@c Repeats execution of the entry point procedure @var{num} times,
@c to enable accurate timing.
@c @item -t
+ at c @findex -t
@c Tells the runtime system to measure the time taken by
@c the (required number of repetitions of) the program,
@c and to print the result of this time measurement.
@sp 1
@item -T @var{time-method}
+ at findex -T
If the executable was compiled in a grade that includes time profiling,
this option specifies what time is counted in the profile.
@var{time-method} must have one of the following values:
@@ -4712,43 +5514,55 @@
@c the above sentence is duplicated above
@c @item -x
+ at c @findex -x
@c Tells the Boehm collector not to perform any garbage collection.
@sp 1
@item --heap-size @var{size}
+ at findex --heap-size
Sets the size of the heap to @var{size} kilobytes.
@sp 1
@item --detstack-size @var{size}
+ at findex --detstack-size
Sets the size of the det stack to @var{size} kilobytes.
@sp 1
@item --nondetstack-size @var{size}
+ at findex --nondetstack-size
Sets the size of the nondet stack to @var{size} kilobytes.
@sp 1
@item --trail-size @var{size}
+ at findex --trail-size
+ at cindex Trail size
Sets the size of the trail to @var{size} kilobytes.
@c @sp 1
@c @item --heap-redzone-size @var{size}
+ at c @findex --heap-redzone-size
@c Sets the size of the redzone on the heap to @var{size} kilobytes.
@c @sp 1
@c @item --detstack-redzone-size @var{size}
+ at c @findex --detstack-redzone-size
@c Sets the size of the redzone on the det stack to @var{size} kilobytes.
@c @sp 1
@c @item --nondetstack-redzone-size @var{size}
+ at c @findex --nondetstack-redzone-size
@c Sets the size of the redzone on the nondet stack to @var{size} kilobytes.
@c @sp 1
@c @item --trail-redzone-size @var{size}
+ at c @findex --trail-redzone-size
@c Sets the size of the redzone on the trail to @var{size} kilobytes.
@sp 1
@item -i @var{filename}
@itemx --mdb-in @var{filename}
+ at findex -i
+ at findex --mdb-in
Read debugger input from the file or device specified by @var{filename},
rather than from standard input.
@@ -4756,17 +5570,23 @@
@item -o @var{filename}
@itemx --mdb-out @var{filename}
Print debugger output to the file or device specified by @var{filename},
+ at findex -o
+ at findex --mdb-out
rather than to standard output.
@sp 1
@item -e @var{filename}
@itemx --mdb-err @var{filename}
+ at findex -e
+ at findex --mdb-err
Print debugger error messages to the file or device specified by @var{filename},
rather than to standard error.
@sp 1
@item -m @var{filename}
@itemx --mdb-tty @var{filename}
+ at findex -m
+ at findex --mdb-tty
Redirect all three debugger I/O streams -- input, output, and error messages --
to the file or device specified by @var{filename}.
@@ -4774,8 +5594,14 @@
@end table
+ at c ----------------------------------------------------------------------------
+
@node C compilers
@chapter Using a different C compiler
+ at cindex C compilers
+ at cindex Using a different C compiler
+ at cindex GNU C
+ at findex --cc
The Mercury compiler takes special advantage of certain extensions
provided by GNU C to generate much more efficient code. We therefore
@@ -4799,6 +5625,7 @@
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
+ at vindex MERCURY_DEFAULT_GRADE
@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.)
@@ -4809,5 +5636,14 @@
code with @samp{--no-static-ground-terms}.
@end itemize
+
+ at c ----------------------------------------------------------------------------
+
+ at node Index
+ at unnumbered Index
+
+ at printindex cp
+
+ at c ----------------------------------------------------------------------------
@bye
--
Fergus Henderson <fjh at cs.mu.oz.au> | "I have always known that the pursuit
| of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh> | -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post: mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------
More information about the reviews
mailing list