[project @ 2003-09-03 13:16:37 by simonmar]

Update the unregisterised bootstrapping instructions to recommend
using hc-build, and rearange some things.

docs/building/building.sgml

@@ -3711,6 +3711,20 @@ foo% make install
       since unregisterised compilation is usually just a step on the
       way to a full registerised port, we don't mind too much.</para>
 
+      <para>Notes on GHC portability in general: we've tried to stick
+      to writing portable code in most parts of the system, so it
+      should compile on any POSIXish system with gcc, but in our
+      experience most systems differ from the standards in one way or
+      another.  Deal with any problems as they arise - if you get
+      stuck, ask the experts on
+      <email>glasgow-haskell-users@haskell.org</email>.</para>
+	
+      <para>Lots of useful information about the innards of GHC is
+      available in the <ulink
+      url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+      Commentary</ulink>, which might be helpful if you run into some
+      code which needs tweaking for your system.</para>
+
       <sect3>
 	<title>Cross-compiling to produce an unregisterised GHC</title>
 
@@ -3876,55 +3890,32 @@ $ make hc-file-bundle Project=Ghc
 	  <listitem>
 	    <para>On the target machine:</para>
 
-	  <para>At this stage we simply need to bootstrap a compiler
-	  from the intermediate C files we generated above.  It is
-	  possible to follow the instructions for bootstrapping from C
-	  files in <xref linkend="sec-booting-from-hc">, but we find
-	  that the script <literal>hc-build</literal> is more suited
-	  to booting a registerised compiler on an already-working
-	  platform.  The following instructions duplicate some of what
-	  the <literal>hc-build</literal> script does, but the process
-	  is made simpler by just aiming to get a working compiler,
-	  then using this to bootstrap a completely fresh tree.</para>
-
-	  <itemizedlist>
-	    <listitem>
-<screen>
-$ cd <replaceable>T</replaceable>/.. && tar xvzf ghc-*-hc.tar.gz
-</screen>
-	    </listitem>
-
-	    <listitem>
-	      <para>Create
-	      <filename><replaceable>T</replaceable>/mk/build.mk</filename>,
-	      with the following contents:</para>
-
-<programlisting>
-GhcUnregisterised = YES
-GhcLibWays =
-SplitObjs = NO
-GhcWithNativeCodeGen = NO
-GhcWithInterpreter = NO
-</programlisting>
-	    </listitem>
-
-	    <listitem>
-	      <para>Bootstrap GHC from the .hc files:</para>
+	    <para>At this stage we simply need to bootstrap a compiler
+	    from the intermediate C files we generated above.  The
+	    process of bootstrapping from C files is automated by the
+	    script in <literal>distrib/hc-build</literal>, and is
+	    described in <xref linkend="sec-booting-from-hc">.</para>
 
 <screen>
-$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
-$ make -C glafp-utils boot all
-$ make -C ghc boot
-$ make -C libraries boot all
-$ make -C ghc all
+$ ./distrib/hc-build --enable-hc-boot-unregisterised
 </screen>
-	    </listitem>
 
-	    <listitem>
-	      <para>You should now have a working GHC binary.  You
-              might want to try using this GHC to compile a Hello
-              World, to make sure it's doing something
-              reasonable:</para>
+	    <para>However, since this is a bootstrap on a new machine,
+	    the automated process might not run to completion the
+	    first time.  For that reason, you might want to treat the
+	    <literal>hc-build</literal> script as a list of
+	    instructions to follow, rather than as a fully automated
+	    script.  This way you'll be able to restart the process
+	    part-way through if you need to fix anything on the
+	    way.</para>
+
+	    <para>Don't bother with running
+	    <literal>make&nbsp;install</literal> in the newly
+	    bootstrapped tree; just use the compiler in that tree to
+	    build a fresh compiler from scratch, this time without
+	    booting from C files.  Before doing this, you might want
+	    to check that the bootstrapped compiler is generating
+	    working binaries:</para>
 
 <screen>
 $ cat >hello.hs
@@ -3932,39 +3923,17 @@ main = putStrLn "Hello World!\n"
 ^D
 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
 $ ./hello
-Hello World!\n
+Hello World!
 </screen>
-	    </listitem>
 
-	    <listitem>
-	      <para>Now, use this compiler
-	      (<filename><replaceable>T</replaceable>/ghc/compiler/ghc-inplace</filename>)
-	      to build another GHC tree from scratch, as
-	      normal.</para>
-	    </listitem>
-	  </itemizedlist>
+	    <para>Once you have the unregisterised compiler up and
+	    running, you can use it to start a registerised port.  The
+	    following sections describe the various parts of the
+	    system that will need architecture-specific tweaks in
+	    order to get a registerised build going.</para>
+
 	  </listitem>
 	</itemizedlist>
-
-	<para>The build may not go through cleanly.  We've tried to
-	stick to writing portable code in most parts of the compiler,
-	so it should compile on any POSIXish system with gcc, but in
-	our experience most systems differ from the standards in one
-	way or another.  Deal with any problems as they arise - if you
-	get stuck, ask the experts on
-	<email>glasgow-haskell-users@haskell.org</email>.</para>
-	
-	<para>Once you have the unregisterised compiler up and
-	running, you can use it to start a registerised port.  The
-	following sections describe the various parts of the system
-	that will need architecture-specific tweaks in order to get a
-	registerised build going.</para>
-
-	<para>Lots of useful information about the innards of GHC is
-	available in the <ulink
-	url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
-	Commentary</ulink>, which might be helpful if you run into
-	some code which needs tweaking for your system.</para>
       </sect3>
 
       <sect3>