[m-dev.] for review: improve doc for compiler options
Fergus Henderson
fjh at cs.mu.OZ.AU
Wed Apr 21 21:53:50 AEST 1999
Estimated hours taken: 1.5
Rearrange and improve the documentation of the compilation model and
code generation options.
doc/user_guide.texi:
compiler/options.m:
- Move the `--max-jump-table-size' option to the code generation
options section, since this option is not a compilation model
option (it doesn't affect binary compatibility).
- Move the compilation model options that are not intended for general
use into a new subsection "developer compilation model options".
- Move the code generation options that are used for optimizing
the generated C code based on the target architecture
(these happen to also be all the ones that are not intended for
general use) into a new subsection "code generation target options".
- Add line breaks, i.e. "$*" in TexInfo, after all the
"(This option is not intended for general use.)" statements.
compiler/options.m:
- Move the `--have-delay-slot' and `--num-real-{r,f}-{regs,temps}'
options to the code generation options section, since these option
are not a compilation model option (they don't affect binary
compatibility). These options were already in the code generation
options section in user_guide.texi.
- Fix a layout error in the help message for `--output-grade-string'.
doc/user_guide.texi:
Document the `--no-reclaim-heap-on-failure' option. Previously
this was documented in options.m but not in user_guide.texi.
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.256
diff -u -r1.256 options.m
--- options.m 1999/04/15 14:55:05 1.256
+++ options.m 1999/04/21 11:22:21
@@ -161,7 +161,6 @@
; unboxed_float
; sync_term_size % in words
; type_layout
- ; max_jump_table_size
% Options for internal use only
% (the values of these options are implied by the
% settings of other options)
@@ -200,6 +199,7 @@
; cflags_for_gotos
; c_debug
; c_include_directory
+ ; max_jump_table_size
; fact_table_max_array_size
% maximum number of elements in a single
% fact table data array
@@ -476,8 +476,6 @@
% of writing) - will usually be over-
% ridden by a value from configure.
type_layout - bool(yes),
- max_jump_table_size - int(0),
- % 0 indicates any size.
basic_stack_layout - bool(no),
agc_stack_layout - bool(no),
procid_stack_layout - bool(no),
@@ -521,6 +519,8 @@
% the `mmc' script will override the
% above default with a value determined
% at configuration time
+ max_jump_table_size - int(0),
+ % 0 indicates any size.
fact_table_max_array_size - int(1024),
fact_table_hash_percent_full - int(90)
]).
@@ -819,7 +819,6 @@
long_option("args", args).
long_option("arg-convention", args).
long_option("type-layout", type_layout).
-long_option("max-jump-table-size", max_jump_table_size).
long_option("agc-stack-layout", agc_stack_layout).
long_option("basic-stack-layout", basic_stack_layout).
long_option("procid-stack-layout", procid_stack_layout).
@@ -854,6 +853,7 @@
long_option("cflags-for-gotos", cflags_for_gotos).
long_option("c-debug", c_debug).
long_option("c-include-directory", c_include_directory).
+long_option("max-jump-table-size", max_jump_table_size).
long_option("fact-table-max-array-size",fact_table_max_array_size).
long_option("fact-table-hash-percent-full",
fact_table_hash_percent_full).
@@ -1450,7 +1450,7 @@
"\tWrite Aditi-RL bytecode to `<module>.rlo' and",
"\tdo not compile to C.",
*****/
- "\t--output-grade-string",
+ "--output-grade-string",
"\tCompute the grade of the library to link with based on",
"\tthe command line options, and print it to the standard",
"\toutput."
@@ -1690,6 +1690,8 @@
"\twith position-independent code (gcc's `-fpic' option).",
"\tThis is necessary when using shared libraries on Intel x86",
"\tsystems running Unix. On other systems it has no effect.",
+
+ "Developer compilation model options:",
"--tags {none, low, high}\t(This option is not for general use.)",
"\tSpecify whether to use the low bits or the high bits of ",
"\teach word as tag bits (default: low).",
@@ -1706,20 +1708,6 @@
% The --bytes-per-word option is intended for use
% by the `mmc' script; it is deliberately not documented.
- "--branch-delay-slot\t\t(This option is not for general use.)",
- "\tAssume that branch instructions have a delay slot.",
- "--num-real-r-regs <n>\t\t(This option is not for general use.)",
- "\tAssume registers r1 up to r<n> are real general purpose",
- "\tregisters.",
- "--num-real-f-regs <n>\t\t(This option is not for general use.)",
- "\tAssume registers f1 up to f<n> are real floating point",
- "\tregisters.",
- "--num-real-r-temps <n>\t\t(This option is not for general use.)",
- "\tAssume that <n> non-float temporaries will fit into",
- "\treal machine registers.",
- "--num-real-f-temps <n>\t\t(This option is not for general use.)",
- "\tAssume that <n> float temporaries will fit into",
- "\treal machine registers.",
"--args {simple, compact}",
"--arg-convention {simple, compact}",
"(This option is not for general use.)",
@@ -1739,12 +1727,6 @@
"\tto them. (The C code also needs to be compiled with",
"\t`-DNO_TYPE_LAYOUT').",
- "--max-jump-table-size",
- "\tThe maximum number of entries a jump table can have.",
- "\tThe special value 0 indicates the table size is unlimited.",
- "\tThis option can be useful to avoid exceeding fixed limits",
- "\timposed by some C compilers.\n",
-
% This is a developer only option.
% "--basic-stack-layout",
% "(This option is not for general use.)",
@@ -1830,13 +1812,35 @@
"\t(This has the same effect as",
"\t`--cflags ""-g"" --link-flags ""--no-strip""'.)",
+ "--max-jump-table-size",
+ "\tThe maximum number of entries a jump table can have.",
+ "\tThe special value 0 indicates the table size is unlimited.",
+ "\tThis option can be useful to avoid exceeding fixed limits",
+ "\timposed by some C compilers.\n",
+
"--fact-table-max-array-size <n>",
"\tSpecify the maximum number of elements in a single",
"\t`pragma fact_table' data array (default: 1024).",
"--fact-table-hash-percent-full <percentage>",
"\tSpecify how full the `pragma fact_table' hash tables should be",
"\tallowed to get. Given as an integer percentage",
- "\t(valid range: 1 to 100, default: 90)."
+ "\t(valid range: 1 to 100, default: 90).",
+
+ "Code generation target options:",
+ "--branch-delay-slot\t\t(This option is not for general use.)",
+ "\tAssume that branch instructions have a delay slot.",
+ "--num-real-r-regs <n>\t\t(This option is not for general use.)",
+ "\tAssume registers r1 up to r<n> are real general purpose",
+ "\tregisters.",
+ "--num-real-f-regs <n>\t\t(This option is not for general use.)",
+ "\tAssume registers f1 up to f<n> are real floating point",
+ "\tregisters.",
+ "--num-real-r-temps <n>\t\t(This option is not for general use.)",
+ "\tAssume that <n> non-float temporaries will fit into",
+ "\treal machine registers.",
+ "--num-real-f-temps <n>\t\t(This option is not for general use.)",
+ "\tAssume that <n> float temporaries will fit into",
+ "\treal machine registers."
]).
:- pred options_help_optimization(io__state::di, io__state::uo) is det.
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.167
diff -u -r1.167 user_guide.texi
--- user_guide.texi 1999/04/21 10:35:35 1.167
+++ user_guide.texi 1999/04/21 11:43:36
@@ -1847,6 +1847,9 @@
@node Developer commands
@subsection Developer commands
@sp 1
+The following commands are intended for use by the developers
+of the Mercury implementation.
+ at sp 1
@table @code
@item nondet_stack
Prints the contents of the fixed slots of the frames on the nondet stack.
@@ -2937,20 +2940,6 @@
@samp{accurate} is not yet implemented.
@sp 1
- at item @code{--tags @{none, low, high@}}
-(This option is not intended for general use.)
-Specify whether to use the low bits or the high bits of
-each word as tag bits (default: low).
-
- at sp 1
- at item @code{--num-tag-bits @var{n}}
-(This option is not intended for general use.)
-Use @var{n} tag bits. This option is required if you specify
- at samp{--tags high}.
-With @samp{--tags low}, the default number of tag bits to use
-is determined by the auto-configuration script.
-
- at sp 1
@item @code{--profiling}, @code{--time-profiling} (grades: any grade containing @samp{.prof})
Enable time profiling. Insert profiling hooks in the
generated code, and also output some profiling
@@ -2995,9 +2984,47 @@
that allow the program to be debugged with @samp{mdb} (see @ref{Debugging}).
@sp 1
+ at item @code{--pic-reg} (grades: any grade containing `.pic_reg')
+[For Unix with intel x86 architecture only.]
+Select a register usage convention that is compatible
+with position-independent code (gcc's `-fpic' option).
+This is necessary when using shared libraries on Intel x86 systems
+running Unix. On other systems it has no effect.
+
+ at end table
+
+ at menu
+* Developer compilation model options::
+ at end menu
+
+ at node Developer compilation model options
+ at subsection Developer compilation model options
+
+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
+use by developers of the Mercury implementation rather than by
+ordinary Mercury programmers.
+
+ at table @asis
+ at sp 1
+ at item @code{--tags @{none, low, high@}}
+(This option is not intended for general use.)@*
+Specify whether to use the low bits or the high bits of
+each word as tag bits (default: low).
+
+ at sp 1
+ at item @code{--num-tag-bits @var{n}}
+(This option is not intended for general use.)@*
+Use @var{n} tag bits. This option is required if you specify
+ at samp{--tags high}.
+With @samp{--tags low}, the default number of tag bits to use
+is determined by the auto-configuration script.
+
+ at sp 1
@item @code{--args @{simple, compact@}}
@item @code{--arg-convention @{simple, compact@}}
-(This option is not intended for general use.)
+(This option is not intended for general use.)@*
Use the specified argument passing convention
in the generated low-level C code.
With the @samp{simple} convention,
@@ -3010,7 +3037,7 @@
@sp 1
@item @code{--no-type-layout}
-(This option is not intended for general use.)
+(This option is not intended for general use.)@*
Don't output base_type_layout structures or references to them.
This option will generate smaller executables, but will not allow the
use of code that uses the layout information (e.g. @samp{functor},
@@ -3018,21 +3045,6 @@
runtime. The C code also needs to be compiled with
@samp{-DNO_TYPE_LAYOUT}.
- at sp 1
- at item @code{--max-jump-table-size}
-The maximum number of entries a jump table can have. The special value 0
-indicates that there is no limit on the jump table size.
-This option can be useful to avoid exceeding fixed limits
-imposed by some C compilers.
-
- at sp 1
- at item @code{--pic-reg} (grades: any grade containing `.pic_reg')
-[For Unix with intel x86 architecture only.]
-Select a register usage convention that is compatible
-with position-independent code (gcc's `-fpic' option).
-This is necessary when using shared libraries on Intel x86 systems
-running Unix. On other systems it has no effect.
-
@end table
@node Code generation options
@@ -3069,6 +3081,10 @@
Don't reclaim heap on backtracking in semidet code.
@sp 1
+ at item --no-reclaim-heap-on-failure
+Combines the effect of the two options above.
+
+ at sp 1
@item --cc @var{compiler-name}
Specify which C compiler to use.
@@ -3105,29 +3121,47 @@
larger tables, but there will generally be less hash collisions,
so it may result in faster lookups.
- at sp 1
+ at end table
+
+ at menu
+* Code generation target options::
+ at end menu
+
+ at node Code generation target options
+ at subsection Code generation target options
+
+The following options allow the Mercury compiler to optimize the generated
+C code based on the characteristics of the expected target architecture.
+The default values of these options will be whatever is appropriate
+for the host architecture that the Mercury compiler was installed on,
+so normally there is no need to set these options manually. They might
+come in handy if you are cross-compiling. But even when cross-compiling,
+it's probably not worth bothering to set these unless efficiency is
+absolutely paramount.
+
+ at table @asis
@item @code{--have-delay-slot}
-(This option is not intended for general use.)
+(This option is not intended for general use.)@*
Assume that branch instructions have a delay slot.
@sp 1
@item @code{--num-real-r-regs @var{n}}
-(This option is not intended for general use.)
+(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}}
-(This option is not intended for general use.)
+(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}}
-(This option is not intended for general use.)
+(This option is not intended for general use.)@*
Assume that @var{n} non-float temporaries will fit into real machine registers.
@sp 1
@item @code{--num-real-f-temps @var{n}}
-(This option is not intended for general use.)
+(This option is not intended for general use.)@*
Assume that @var{n} float temporaries will fit into real machine registers.
@end table
--
Fergus Henderson <fjh at cs.mu.oz.au> | "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh> | of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3 | -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to: mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions: mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------
More information about the developers
mailing list