[m-dev.] for review: document `--target asm' option

[Fergus Henderson]

Estimated hours taken: 2

Document the GCC back-end interface.
(XXX still need to document installation instructions.)

Also fix some other problems in the documentation that I noticed at
the same time.

NEWS:
	Mention the new GCC back-end.

compiler/options.m:
doc/user_guide.texi:
	Document the `--target asm' option.
	Fix up the documentation of the various grade options to 
	say which options are not supported by which back-ends.

doc/user_guide.texi:
	Document the `--use-trail' option, which was previously only
	documented in options.m.
	Refer to grade `ilc' rather than `il' (which is not yet
	documented since it is not yet supported).

Workspace: /home/venus/fjh/ws-venus2/mercury
Index: NEWS
===================================================================
RCS file: /home/mercury1/repository/mercury/NEWS,v
retrieving revision 1.198
diff -u -d -u -r1.198 NEWS
--- NEWS	2001/02/09 14:03:58	1.198
+++ NEWS	2001/02/17 20:09:33
@@ -36,6 +36,28 @@
 
 * We've added a new `hash_table' library module.
 
+Changes to the Mercury implementation:
+
+* Native code compiler.
+
+  There's a new back-end for the Mercury compiler that compiles
+  directly to assembler, rather than than going via C.  This
+  back-end is enabled using the new `--target asm' option.
+
+  This new back-end is implemented by linking the Mercury compiler
+  with the (relatively) language independent GNU Compiler Collection
+  back-end.  In other words, there is now a Mercury front-end for GCC.
+
+  Note that this should be considered as a beta release of the native
+  code compiler.  Furthermore our current version of the native code
+  compiler is based on an unreleased snapshot version of the GCC
+  back-end.
+
+  So far we have only tested it on i686-pc-linux-gnu (Intel x86-based
+  PCs running Linux).  But in theory it should work fine on other
+  platforms too.
+
+
 NEWS for Mercury release 0.10:
 ------------------------------
 
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.312
diff -u -d -r1.312 options.m
--- compiler/options.m	2001/02/17 18:06:53	1.312
+++ compiler/options.m	2001/02/17 19:20:36
@@ -1735,8 +1735,9 @@
 		"\tCheck the module for errors, but do not generate any code.",
 		"-C, --target-code-only",
 		"\tGenerate target code (i.e. C code in `<module>.c',",
-		"\t\tIL code in `<module>.il', or Java code in",
-		"\t\t`<module>.java'), but not object code.",
+		"\tassembler code in `<module>.s' or `<module>.pic_s',",
+		"\tIL code in `<module>.il', or Java code in",
+		"\t`<module>.java'), but not object code.",
 		"-c, --compile-only",
 		"\tGenerate C code in `<module>.c' and object code in `<module>.o'",
 		"\tbut do not attempt to link the named modules.",
@@ -1928,10 +1929,33 @@
 		"library which has been compiled with the same setting.",
 		"-s <grade>, --grade <grade>",
 		"\tSelect the compilation model. The <grade> should be one of",
-		"\t`none', `reg', `jump', `asm_jump', `fast', `asm_fast', `hlc'",
-		"--target {c, il, java}",
-		"\tSpecify the target language: C, IL or Java (default: C).",
-		"\tThe IL and Java targets imply `--high-level-code' (see below).",
+		"\tthe base grades `none', `reg', `jump', `asm_jump', `fast', ",
+		"\t`asm_fast', `hlc', `ilc', or `java',",
+% These grades (hl, hl_nest, and hlc_nest) are not yet documented, because
+% the --high-level-data option is not yet supported for C,
+% and the --gcc-nested-functions option is not yet documented.
+%		"\t`hl', `hl_nest', `hlc_nest'",
+		"\tor one of those with one or more of the grade modifiers",
+		"\t`.gc', `.prof', `.memprof', `.tr', `.debug', `.par', and/or",
+		"`.pic_reg' appended.",
+		"\tDepending on your particular installation, only a subset",
+		"\tof these possible grades will have been installed.",
+		"\tAttempting to use a grade which has not been installed",
+		"\twill result in an error at link time.",
+		"--target c\t\t\t(grades: none, reg, jump, fast,",
+		"\t\t\t\t\tasm_jump, asm_fast, hlc)",
+		"--target asm\t\t\t(grades: hlc)",
+		"--target il\t\t\t(grades: ilc)",
+		"--target java\t\t\t(grades: java)",
+		"\tSpecify the target language: C, assembler, IL or Java.",
+		"\tThe default is C.",
+		"\t""IL"" is the Microsoft.NET Intermediate Language.",
+		"\tTargets other than C imply `--high-level-code' (see below).",
+		"\tAs an exception to the usual rule for options in this section,",
+		"\twhere different option settings normally correspond to different",
+		"\tABIs, code generated using `--target asm' is binary compatible",
+		"\twith code generated using `--target c --high-level code', so",
+		"\tthese both use grade `hlc'.",
 		"--il",
 		"\tAn abbreviation for `--target il'.",
 		"--il-only",
@@ -1952,17 +1976,6 @@
 		"\tcode.",
 
 
-% These grades (hl, hl_nest, and hlc_nest) are not yet documented, because
-% the --high-level-data option is not yet implemented,
-% and the --gcc-nested-functions option is not yet documented.
-%		"\t`hl', `hl_nest', `hlc_nest'",
-		"\tor one of those with `.gc', `.prof', `.proftime',",
-		"\t`.profcalls', `.tr', `.sa', `.debug', and/or `.pic_reg'",
-		"\tappended (in that order).",
-		"\tDepending on your particular installation, only a subset",
-		"\tof these possible grades will have been installed.",
-		"\tAttempting to use a grade which has not been installed",
-		"\twill result in an error at link time.",
 		"--gcc-global-registers\t\t(grades: reg, fast, asm_fast)",
 		"--no-gcc-global-registers\t(grades: none, jump, asm_jump)",
 		"\tSpecify whether or not to use GNU C's",
@@ -1985,16 +1998,16 @@
 % the --high-level-data option is not yet implemented,
 % and the --gcc-nested-functions option is not yet documented.
 %		"-H, --high-level-code\t\t\t(grades: hl, hlc, hl_nest, hlc_nest)",
-		"-H, --high-level-code\t\t\t(grades: hlc, ilc)",
+		"-H, --high-level-code\t\t\t(grades: hlc, ilc, java)",
 		"\tUse an alternative back-end that generates high-level code",
 		"\trather than the very low-level code that is generated by our",
 		"\toriginal back-end.",
 % The --high-level-data option is not yet documented,
-% because it is not yet implemented
+% because it is not yet supported
 %		"--high-level-data\t\t\t(grades: hl, hl_nest)",
 %		"\tUse an alternative higher-level data representation.",
 % The --high-level option is not yet documented,
-% because --high-level-data is not yet implemented
+% because --high-level-data is not yet supported
 %		"--high-level\t\t\t(grades: hl, hl_nest)",
 %		"\tAn abbreviation for `--high-level-code --high-level-data'.",
 % The --gcc-nested-functions option is not yet documented,
@@ -2004,13 +2017,14 @@
 %		"\tSpecify whether or not to use GNU C's nested functions extension.",
 %		"\tThis option is ignored if the `--high-level-code' option is not enabled.",
 % The --det-copy-out option is not yet documented,
-% because it is not yet tested and probably not very useful.
+% because it is not yet tested much and probably not very useful,
+% except for Java, where it is the default.
 %		"--det-copy-out",
 %		"\tSpecify whether to handle output arguments for det/semidet",
 %		"\tprocedures using return-by-value rather than pass-by-reference.",
 %		"\tThis option is ignored if the `--high-level-code' option is not enabled.",
 % The --nondet-copy-out option is not yet documented,
-% because it is probably not very useful except for IL,
+% because it is probably not very useful except for IL and Java,
 % where it is the default.
 %		"--nondet-copy-out\t\t(grades: il, ilc)",
 %		"\tSpecify whether to handle output arguments for nondet",
@@ -2032,19 +2046,25 @@
 		"\t\t\t\tother grades use `--gc none'.)",
 		"\tSpecify which method of garbage collection to use",
 		"\t(default: conservative).  `accurate' GC is not yet implemented.",
+		"\tThis option is ignored for the IL and Java back-ends,",
+		"\twhich always use the garbage collector of the underlying",
+		"\tIL or Java implementation.",
 		"\t`--high-level-code' requires `conservative' GC.",
 		"--use-trail\t\t\t(grade modifier: `.tr')",
 		"\tEnable use of a trail.",
 		"\tThis is necessary for interfacing with constraint solvers,",
 		"\tor for backtrackable destructive update.",
+		"\tThis option is not yet supported for the IL or Java back-ends.",
 		"-p, --profiling, --time-profiling",
 		"\t\t\t\t(grade modifier: `.prof')",
 		"\tEnable time and call profiling.  Insert profiling hooks in the",
 		"\tgenerated code, and also output some profiling",
 		"\tinformation (the static call graph) to the file",
 		"\t`<module>.prof'.",
+		"\tThis option is not supported for the IL or Java back-ends.",
 		"--memory-profiling\t\t(grade modifier: `.memprof')",
 		"\tEnable memory and call profiling.",
+		"\tThis option is not supported for the IL or Java back-ends.",
 /*****************
 XXX The following options are not documented,
 because they are currently not useful.
@@ -2071,6 +2091,8 @@
 		"\tEnable Mercury-level debugging.",
 		"\tSee the Debugging chapter of the Mercury User's Guide",
 		"\tfor details.",
+		"\tThis option is not yet supported for the `--high-level-code'",
+		"\tback-ends.",
 		"--pic-reg\t\t\t(grade modifier: `.pic_reg')",
 		"[For Unix with intel x86 architecture only]",
 		"\tSelect a register usage convention that is compatible,",
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.240
diff -u -d -r1.240 user_guide.texi
--- doc/user_guide.texi	2001/02/12 04:39:58	1.240
+++ doc/user_guide.texi	2001/02/17 19:16:19
@@ -3130,6 +3130,7 @@
 @item -C
 @itemx --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}),
 but not object code.
 
@@ -3491,7 +3492,7 @@
 @item @samp{hlc}
 @code{--target c --high-level-code}.
 
- at item @samp{il}
+ at item @samp{ilc}
 @code{--target il --high-level-code}.
 
 @item @samp{java}
@@ -3534,13 +3535,13 @@
 
 @sp 1
 @item @code{--target c} (grades: none, reg, jump, fast, asm_jump, asm_fast, hlc)
+ at item @code{--target asm} (grades: hlc)
 @itemx @code{--il}, @code{--target il} (grades: ilc)
 @itemx @code{--java}, @code{--target java} (grades: java)
-Specify the target language used for compilation: C, IL or Java.
+Specify the target language used for compilation: C, assembler, IL or Java.
 C means ANSI/ISO C, optionally with GNU C extensions (see below).
 IL means the Microsoft .NET Intermediate Language.
- at samp{--target il} implies @samp{--high-level-code}.
- at samp{--target java} implies @samp{--high-level-code}.
+Targets other than C imply @samp{--high-level-code}.
 
 @sp 1
 @item @code{--il-only}
@@ -3581,7 +3582,7 @@
 This option is ignored if the @samp{--high-level-code} option is enabled.
 
 @sp 1
- at item @code{-H}, @code{--high-level-code} (grades: hlc, ilc)
+ at item @code{-H}, @code{--high-level-code} (grades: hlc, ilc, java)
 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.
@@ -3593,6 +3594,8 @@
 Grades containing @samp{.gc} use @samp{--gc conservative},
 other grades use @samp{--gc none}.
 @samp{accurate} is not yet implemented.
+This option is ignored by the IL and Java back-ends, which always use
+the underlying IL or Java implementation's garbage collector.
 
 @sp 1
 @item @code{--profiling}, @code{--time-profiling} (grades: any grade containing @samp{.prof})
@@ -3600,6 +3603,7 @@
 generated code, and also output some profiling
 information (the static call graph) to the file
 @samp{@var{module}.prof}.  @xref{Profiling}.
+This option is not supported for the IL and Java back-ends.
 
 @sp 1
 @item @code{--memory-profiling} (grades: any grade containing @samp{.memprof})
@@ -3607,6 +3611,7 @@
 generated code, and also output some profiling
 information (the static call graph) to the file
 @samp{@var{module}.prof}.  @xref{Memory profiling}.
+This option is not supported for the IL and Java back-ends.
 
 @ignore
 	The following are basically useless, hence undocumented.
@@ -3637,7 +3642,14 @@
 @item @code{--debug} (grades: any grade containing @samp{.debug})
 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.
 
+ at sp 1
+ at item @code{--use-trail} (grades: any grade containing @samp{.tr})
+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{--pic-reg} (grades: any grade containing `.pic_reg')
 [For Unix with intel x86 architecture only.]

-- 
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-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
--------------------------------------------------------------------------