[m-rev.] for review: docs for mmc --make

[Peter Wang]

Estimated hours taken: 2
Branches: main

doc/user_guide.texi:
	Move the existing text about `mmc --make' from out of the Mmake
	chapter into a new chapter and add some more to it.

Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.460
diff -u -r1.460 user_guide.texi
--- doc/user_guide.texi	28 Nov 2005 02:30:25 -0000	1.460
+++ doc/user_guide.texi	13 Jan 2006 05:46:15 -0000
@@ -114,6 +114,7 @@
 * Running::         Execution of programs built with the Mercury compiler.
 * Using Mmake::     ``Mercury Make'', a tool for building Mercury programs.
 * Libraries::       Creating and using libraries of Mercury modules.
+* mmc --make::	    Another tool for building Mercury prorgams.
 * Using Aditi::     Executing Mercury predicates using the Aditi
                     deductive database.
 * Debugging::       The Mercury debugger @samp{mdb}.
@@ -841,56 +842,6 @@
 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.
 
-As an alternative to Mmake, the Mercury compiler now contains a
-significant part of the functionality of Mmake, using mmc's
- at samp{--make} option.
- at findex --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.
-Parallel builds are not yet supported.
-
-Note that @samp{--use-subdirs} is automatically enabled if you specify
- at samp{mmc --make}.
-
- at cindex Options files
- at cindex Mercury.options
-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
- at samp{include} directives are allowed.  All variables in @file{Mercury.options} are treated as if they are assigned using @samp{:=}. Variables may also
-be set in the environment, overriding settings in options files.
-
- 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_BUILD_FILES
- at vindex MC_BUILD_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 by 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 ----------------------------------------------------------------------------
 
 @node Libraries
@@ -1182,6 +1133,199 @@
 
 @c ----------------------------------------------------------------------------
 
+ at node mmc --make
+ at chapter @samp{mmc --make}
+
+As an alternative to Mmake, the Mercury compiler contains a
+significant part of the functionality of Mmake, using mmc's
+ at samp{--make} option.
+ at findex --make
+Any non-option arguments to @samp{mmc --make} are treated as 
+targets to make, rather than source files.
+Note that @samp{--use-subdirs} is automatically enabled if you specify
+ at samp{mmc --make}.
+
+The advantages of @samp{mmc --make} over Mmake are that there
+is no @samp{mmake depend} step and the dependencies are more accurate.
+However, @samp{mmc --make} is not a general tool. To
+do things other than building and installing Mercury prorgams you may
+need to enlist a separate tool such as Mmake or make.
+Also, Mmake is more mature.
+
+Parallel builds are not yet supported.
+
+Just about all targets supported by Mmake are supported by
+ at samp{mmc --make}.  The main exceptions are @samp{clean} and
+ at samp{realclean}, although @samp{@var{main-module}.clean} and
+ at samp{@var{main-module}.realclean} @emph{are} supported.
+ at samp{@var{module}.depend} targets are ignored.
+
+ at c XXX list specifically which targets are supported
+
+To forceably rebuild the program, including intermediate files, replace
+ at samp{--make} by @samp{--rebuild}.  This can be useful if you change
+grades, or otherwise enable compiler options which are incompatible with
+previous builds.  @samp{-m} and @samp{-r} are abbreviations for
+ at samp{--make} and @samp{--rebuild}, respectively.
+
+ at cindex Options files
+ at cindex Mercury.options
+Settings for @samp{mmc --make} are stored in files named
+ at file{Mercury.options}.  Syntactically they are a subset of Mmakefiles
+but contain only variable assignments and @samp{include} directives.
+There are no target rules in the file.
+
+Compared to Mmake, all variables in @file{Mercury.options} are treated
+as if they are assigned using @samp{:=}, however both @samp{=} and
+ at samp{:=} syntaxes are supported.  Variables may be appended to with
+ at samp{+=}.  Variable references are made with @samp{$(VAR)} or
+ at samp{$@{VAR@}}.  The braces or parentheses can be omitted for
+single-lettered variables, but this is discouraged.
+A dollar sign can be written with @samp{$$}.
+
+Environment variables override variables with the same names in
+options files, which are in turn overridden by arguments on the
+ at samp{mmc --make} command line.
+
+Include directives are written @samp{include FILENAME}, or
+ at samp{-include FILENAME} if you don't want an error to be issued
+if the file does not exist.
+
+Comments begin with @samp{#} and continue to the end of the
+line.  Long lines can be broken by backslashes.
+
+Note that the @samp{VAR=VALUE} command line syntax of Mmake and make is
+ at emph{not} supported, so you cannot write
+ at samp{mmc --make libfoo.install INSTALL_PREFIX=/some/path}.
+Instead you should set the environment variable with your shell
+before invoking @samp{mmc}, e.g.
+ at samp{INSTALL_PREFIX=/some/path mmc --make libfoo.install}.
+In this example you could just as well use the command-line option,
+ at samp{mmc --make libfoo.install --install-prefix /some/path}.
+
+See @pxref{Using Mmake} for a list of variables meaningful variables
+in @file{Mercury.options}.
+
+ at c XXX make a list here
+
+ at menu
+* A short example of mmc --make::
+* Using mmc --make with Mmake::
+ at end menu
+
+ at c ----------------------------------------------------------------------------
+
+ at node A short example of mmc --make
+ at section A short example of @samp{mmc --make}
+
+Assume we have a simple program with a top level module called
+ at samp{main.m}.  If there are any source files for which
+the file name does not match the module name, then 
+a @file{Mercury.modules} must first be created with this command:
+
+ at example
+mmc -f *.m
+ at end example
+
+ at noindent
+To compile the program, simply run:
+
+ at example
+mmc --make main
+ at end example
+
+If successful an executable called @file{main} will be produced in the
+current directory.  Any intermediate files would be produced in a
+subdirectory called @file{Mercury}.  You do not normally need to worry
+about what goes in there.
+
+To clean up the directory, run @samp{mmc --make main.clean} or
+ at samp{mmc --make main.realclean}.  You may delete the @file{Mercury}
+directory if you like.
+
+Now assume we want to compile the program under the grade @samp{hlc.gc},
+with a higher optimisation level, and we want to use the
+ at samp{complex_numbers} library from the @samp{extras} distribution, which
+has already been installed into the standard library directory.
+The command we need is:
+
+ at example
+mmc --make main --grade hlc.gc -O3 --ml complex_numbers
+ at end example
+
+ at noindent
+We can put all those options into a file so that we can repeat the
+build easily.  The file must be called @samp{Mercury.options} and the
+contents would be:
+
+ at example
+MAIN_TARGET = main
+GRADEFLAGS = --grade hlc.gc
+MCFLAGS = -O3
+EXTRA_LIBRARIES = complex_numbers
+ at end example
+
+ at noindent
+XXX The GRADEFLAGS line doesn't actually work yet.
+Instead you can set MERCURY_DEFAULT_GRADE = hlc.gc in the file
+or in an environment variable.
+
+ at noindent
+Now you can just run @samp{mmc --make} or, in practice, @samp{mmc -m}.
+
+Building libraries is similar to building programs, and works in the
+same way as Mmake.  If there exists a module in @file{foo.m}, you can
+build both static and shared libraries using the command @samp{mmc
+--make libfoo}.  Use the targets @samp{libfoo.a} and @samp{libfoo.so}
+if you only want one or the other.
+
+ at c XXX does that make any sense on platforms other than Unix?
+
+A library can be installed with the @samp{libfoo.install} target.  The
+library will be built and installed in the current grade plus the default
+set of grades.  The @samp{--no-libgrade}, @samp{--libgrade} and
+ at samp{--lib-linkage} options can be used to reduce the set of grades and
+linkages for which the library is installed.
+
+ at c ----------------------------------------------------------------------------
+
+ at node Using mmc --make with Mmake
+ at section Using mmc --make with Mmake
+
+ at samp{mmc --make} can also 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_BUILD_FILES
+ at vindex MC_BUILD_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 by 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
+
+ at c ----------------------------------------------------------------------------
+
 @node Debugging
 @chapter Debugging
 @cindex Debugging
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------