[m-rev.] For review: New FAQ entries for installation.

[Paul Bone]

On Wed, Sep 03, 2008 at 01:34:47PM +1000, Peter Wang wrote:
> > + at item
> > + at emph{The compiler crashes during the ``make install'' phase}
> > + at sp 1
> > +
> > +An incompatibility between Mercury's low-level C backend and some GCC
> > +optimizations in GCC 4.2 seems to be causing problems.  Try using a different
> > +version of GCC, otherwise the following instructions may help.
> > +
> > +After unpacking the tarball but before running @samp{configure}, create a file in
> > +the root directory of the unpacked source named @samp{Mmake.params} containing
> > +the line @samp{-EXTRA_CFLAGS=-O0}, and run @samp{configure} as
> > + at samp{./configure --with-llds-base-grade=none --with-default-grade=hlc.gc}.
> > +This disables GCC's optimizations and some of Mercury's optimizations for the
> 
> nearly all of Mercury's optimizations
> 
> > +low-level C backend.  Programs build using this Mercury installation will use
> 
> built
> 
> > +the high-level C backend by default.
> > +
> > +See bugs 66 and 77.
> 
> in the bug database.
> 
> (Unless I'm mistaken, you would still need to set -O0 when building any
> programs with the low-level C grade, so you may want to write something
> about that.)
> 

Thanks Peter for your review.  Below is a new diff including the changes
you've recommended.  However I'd like somebody to check the additional
paragraph I've added in this first FAQ item, the paragraph about
building programs in the low-level C grade.

Thanks.

Index: doc/faq.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/faq.texi,v
retrieving revision 1.33
diff -u -p -r1.33 faq.texi
--- doc/faq.texi	14 Jan 2008 00:08:01 -0000	1.33
+++ doc/faq.texi	5 Sep 2008 00:54:06 -0000
@@ -75,12 +75,61 @@ into another language, under the above c
 @node Top,,, (mercury)
 @top The Mercury Frequently Asked Questions List, version <VERSION>
 @menu
+* Installing::      Problems during compilation and installation.
 * Programming::     Common programming errors.
 * Unimplemented::   Problems caused by unimplemented Mercury features.
 * Last resort::     What to do when all else fails.
 @end menu
 @end ifnottex
 
+ at node Installing
+ at chapter Problems during compilation and installation.
+
+ at enumerate
+
+ at item
+ at emph{The compiler crashes during the ``make install'' phase}
+ at sp 1
+
+An incompatibility between Mercury's low-level C backend and some GCC
+optimizations in GCC 4.2 seems to be causing problems.  Try using a different
+version of GCC, otherwise the following instructions may help.
+
+After unpacking the tarball but before running @samp{configure}, create a file in
+the root directory of the unpacked source named @samp{Mmake.params} containing
+the line @samp{-EXTRA_CFLAGS=-O0}, and run @samp{configure} as
+ at samp{./configure --with-llds-base-grade=none --with-default-grade=hlc.gc}.
+This disables GCC's optimizations and nearly all of Mercury's optimizations for
+the low-level C backend.
+
+Programs built using this Mercury installation will use the high-level C
+backend by default.  To build a program in the low-level C grade the GCC
+optimizations should be disabled by creating a @samp{Mmake.params} file in the
+root directory of the program, as described above for the compiler.
+
+See bugs 66 and 77 in the bug database.
+
+ at sp 1
+ at item
+ at emph{The ``make install'' phase takes ages!  What's going on?}
+ at sp 1
+
+Mercury supports many grades.  A grade is a combination the target language and
+feature options.  These features include garbage collection, debugging and
+profiling support.  See ``Grades and grade components'' in the User's Guide.
+
+During the ``make install'' phase the newly built compiler is used to compile
+the standard library in each of the selected grades.  The runtime system is
+also rebuilt for each grade. 
+
+To install fewer grades and reduce the time ``make install'' takes, see the
+configure script's options, in particular @samp{--disable-most-grades}.
+Alternatively, run @samp{make install LIBGRADES=<grades>} instead, where
+``<grades>'' is a space-separated list of grades.
+
+
+ at end enumerate
+
 @node Programming
 @chapter Common programming errors
 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20080905/6522d79d/attachment.sig>