[m-rev.] for review: documentation for using `mmc --make' with mmake

[Simon Taylor]

Estimated hours taken: 0.5

doc/user_guide.texi:
	Document using `mmc --make' with Mmake.

Index: user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.307
diff -u -u -r1.307 user_guide.texi
--- user_guide.texi	19 Apr 2002 14:59:29 -0000	1.307
+++ user_guide.texi	1 May 2002 15:32:04 -0000
@@ -819,7 +819,7 @@
 MCFLAGS-bad_style = --inhibit-warnings
 @end example
 
-Mmake has a few options, including @samp{--use-subdirs},
+Mmake has a few options, including @samp{--use-subdirs}, @samp{--use-mmc-make},
 @samp{--save-makefile}, @samp{--verbose}, and @samp{--no-warn-undefined-vars}.
 For details about these options, see the man page or type @samp{mmake --help}.
 
@@ -829,27 +829,51 @@
 is very useful if you have a machine with more than one CPU.
 
 As an alternative to Mmake, the Mercury compiler now contains a
-significant part of the functionality of Mmake, using the
- at samp{--make} option.  
+significant part of the functionality of Mmake, using the mmc's
+ at samp{--make} option.
 @findex --make
-To use the compiler's internal make with Mmake, set the
- at samp{MMAKE_USE_MMC_MAKE} environment variable to @samp{yes},
-or create a file @file{Mercury.options} in the directory
-containing the source files.  When this is done, Mmake will
-process source files written in other programming languages,
-but all Mercury compilation will be done by @samp{mmc --make}.
 
 The advantages of the @samp{mmc --make} over Mmake are that there
 is no @samp{mmake depend} step and the dependencies are more accurate.
-Library installation (@pxref{Libraries}) and parallel makes are
-not yet supported.
+Library installation (@pxref{Libraries}) and parallel builds are not
+yet supported.
 
 The Mmake variables above can be used by @samp{mmc --make} if they
 are set in a file called @file{Mercury.options}. The @file{Mercury.options}
 file has the same syntax as an Mmakefile, but only variable assignments and
 @samp{include} directives are allowed.  All variables in the Mercury.options
-are treated as if they are assigned using @samp{:=}.  As with Mmake,
-variables may also be set in the environment.
+are treated as if they are assigned using @samp{:=}. Variables may also
+be set in the environment.
+
+ at samp{mmc --make} can be used in conjunction with Mmake. This is useful
+for projects which include source code written in languages other than
+Mercury.  The @samp{--use-mmc-make} Mmake option disables Mmake's
+Mercury-specific rules. Mmake will then process source files written in
+other languages, but all Mercury compilation will be done by
+ at samp{mmc --make}.  The following variables can be set in the Mmakefile
+to control the use of @samp{mmc --make}.
+
+ at table @code
+
+ at item MERCURY_MAIN_MODULES
+ at vindex MERCURY_MAIN_MODULES
+The top-level modules of the programs or libraries being built in
+the directory.  This must be set to tell Mmake to use @samp{mmc --make}
+to rebuild the targets for the main modules even if those files already
+exist.
+
+ at item MC_MAKE_FILES
+ at vindex MC_MAKE_FILES
+Other files which should be built with @samp{mmc --make}.
+This should only be necessary for header files generated by the
+Mercury compiler which are included the user's C source files.
+
+ at item MC_MAKE_FLAGS and EXTRA_MC_MAKE_FLAGS
+ at vindex MC_MAKE_FLAGS
+ at vindex EXTRA_MC_MAKE_FLAGS
+Options to pass to the Mercury compiler only when using @samp{mmc --make}.
+
+ at end table
 
 @c ----------------------------------------------------------------------------
 
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------