[project @ 1998-08-25 18:07:57 by sof]

[ghc-hetmet.git] / docs / installing.vsgml

diff --git a/docs/installing.vsgml b/docs/installing.vsgml
index 08515a7..0ce9476 100644 (file)
--- a/docs/installing.vsgml
+++ b/docs/installing.vsgml
@@ -2,7 +2,7 @@
 <article>
 
 <title>Building and Installing the Glasgow Functional Programming Tools Suite
 <article>
 
 <title>Building and Installing the Glasgow Functional Programming Tools Suite

-Version 3.00
+Version 3.02

 <author>The GHC Team,
 Department of Computing Science,
 University of Glasgow,
 <author>The GHC Team,
 Department of Computing Science,
 University of Glasgow,

@@ -10,7 +10,7 @@ Glasgow, Scotland,
 G12 8QQ.
 
 Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@
 G12 8QQ.
 
 Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@

-<date>November 1997</date>
+<date>April 1998</date>

 
 <abstract>
 
 
 <abstract>
 

@@ -18,9 +18,6 @@ This guide is intended for people who want to install or modify
 programs from the Glasgow @fptools@ suite (as distinct from those
 who merely want to <em/run/ them).
 
 programs from the Glasgow @fptools@ suite (as distinct from those
 who merely want to <em/run/ them).
 

-The whole install-and-make system was completely re-done between GHC
-2.01 and 2.02, so it will be worth your while to re-read this guide
-even if you have read earlier versions.

 </abstract>
 
 <toc>
 </abstract>
 
 <toc>

@@ -83,10 +80,9 @@ confidence will work well by having tested it (more) thoroughly.
 
 Source-only distributions are either bugfix releases or snapshots of
 current state of development. The release has undergone some testing.
 
 Source-only distributions are either bugfix releases or snapshots of
 current state of development. The release has undergone some testing.

-Source releases of 2.0x can be compiled up using 2.07 (or subsequent
-bugfix releases) or the Good Old Compiler, GHC~0.29. Compiling with
-0.29 is recommended if you're a performance junkie, as 0.29 (still)
-generates zippier code, but GHC~2.0x is catching up.
+Source releases of 3.xx can be compiled up using 2.10 or later.
+Compiling with version 0.29 won't work any more: we use Haskell 1.4
+features in the compiler.

 
 <tag/Build GHC from intermediate C @.hc@ files<nidx/hc files/:/ You
 need a working GHC to use a source distribution. What if you don't
 
 <tag/Build GHC from intermediate C @.hc@ files<nidx/hc files/:/ You
 need a working GHC to use a source distribution. What if you don't

@@ -357,10 +353,9 @@ Concurrent/Parallel Haskell probably won't work (yet).
 <nidx>m68k-next-nextstep3: concurrent---no</nidx>
 <nidx>m68k-next-nextstep3: parallel---no</nidx>
 
 <nidx>m68k-next-nextstep3: concurrent---no</nidx>
 <nidx>m68k-next-nextstep3: parallel---no</nidx>
 

-<tag/m68k-sun-sunos4 (Sun3):/
-<nidx>m68k-sun-sunos4: registerised port</nidx>
-GHC 2.0x hasn't been tried on a Sun3.  GHC~0.26 worked registerised.
-No native-code generator.
+<tag/m68k-sun-sunos4 (Sun3):/ <nidx>m68k-sun-sunos4: registerised
+port</nidx> GHC 2.0x and 3.0x haven't been tried on a Sun3.  GHC~0.26
+worked registerised.  No native-code generator.

 
 Concurrent/Parallel Haskell probably don't work (yet).
 <nidx>m68k-sun-sunos4: concurrent---no</nidx>
 
 Concurrent/Parallel Haskell probably don't work (yet).
 <nidx>m68k-sun-sunos4: concurrent---no</nidx>

@@ -641,8 +636,8 @@ Hello, world!
 Some simple-but-profitable tests are to compile and run the notorious
 @nfib@<ncdx/nfib/ program, using different numeric types.  Start with
 @nfib :: Int -> Int@, and then try @Integer@, @Float@, @Double@,
 Some simple-but-profitable tests are to compile and run the notorious
 @nfib@<ncdx/nfib/ program, using different numeric types.  Start with
 @nfib :: Int -> Int@, and then try @Integer@, @Float@, @Double@,

-@Rational@ and maybe @Complex Float@.  Code for this is distributed in
-@ghc/misc/examples/nfib/@ in a source distribution.
+@Rational@ and perhaps the overloaded version.  Code for this is
+distributed in @ghc/misc/examples/nfib/@ in a source distribution.

 
 For more information on how to ``drive'' GHC, either do @ghc -help@ or
 consult the User's Guide (distributed in several pre-compiled formats
 
 For more information on how to ``drive'' GHC, either do @ghc -help@ or
 consult the User's Guide (distributed in several pre-compiled formats

@@ -738,23 +733,24 @@ Sadly, the @gr2ps@ script, used to convert ``parallelism profiles''
 to PostScript, is written in Bash (GNU's Bourne Again shell).
 This bug will be fixed (someday).
 
 to PostScript, is written in Bash (GNU's Bourne Again shell).
 This bug will be fixed (someday).
 

-<tag>Flex:</tag>
-<nidx>pre-supposed: flex</nidx>
+<tag>Flex:</tag> 
+<nidx>pre-supposed: flex</nidx> 

 <nidx>flex, pre-supposed</nidx>
 <nidx>flex, pre-supposed</nidx>

-This is a quite-a-bit-better-than-Lex lexer.  Used in the
-literate-programming stuff.  You won't need it unless you're hacking
-on some of our more obscure stuff.  On our machines, the version in
-@/bin@ doesn't work; you need the GNU version.  Find out by saying
-@flex --version@ (our current version is 2.5.3, but maybe earlier ones
-will work).  If it doesn't know about the @--version@ flag, it ain't
-the right @flex@.
+
+This is a quite-a-bit-better-than-Lex lexer.  Used to build GHC's
+lexer, and a couple of utilities in @glafp-utils@.  On our machines,
+the version in @/bin@ doesn't work; you need the GNU version.  Find
+out by saying @flex --version@ (our current version is 2.5.3, but
+maybe earlier ones will work).  If it doesn't know about the
+@--version@ flag, it ain't the right @flex@.

 
 <tag>Yacc:</tag>
 <nidx>pre-supposed: non-worthless Yacc</nidx>
 <nidx>Yacc, pre-supposed</nidx>
 
 <tag>Yacc:</tag>
 <nidx>pre-supposed: non-worthless Yacc</nidx>
 <nidx>Yacc, pre-supposed</nidx>

+

 If you mess with the Haskell parser, you'll need a Yacc that can cope.
 If you mess with the Haskell parser, you'll need a Yacc that can cope.

-The unbundled @/usr/lang/yacc@ is OK; the GNU @bison@ is OK;
-Berkeley yacc, @byacc@, is not OK.
+The unbundled @/usr/lang/yacc@ is OK; the GNU @bison@ is OK; Berkeley
+yacc, @byacc@, is not OK.

 
 <tag>@sed@</tag>
 <nidx>pre-supposed: sed</nidx>
 
 <tag>@sed@</tag>
 <nidx>pre-supposed: sed</nidx>

@@ -846,9 +842,7 @@ All the other directories are individual <em/projects/ of the
 @fptools@ system --- for example, the Glasgow Haskell Compiler
 (@ghc@), the Happy parser generator (@happy@), the @nofib@ benchmark
 suite, and so on.  You can have zero or more of these.  Needless to
 @fptools@ system --- for example, the Glasgow Haskell Compiler
 (@ghc@), the Happy parser generator (@happy@), the @nofib@ benchmark
 suite, and so on.  You can have zero or more of these.  Needless to

-say, some of them are needed to build others.  For example, you need
-@literate@ (or an installed copy of the tools) in order to format the
-GHC documentation.
+say, some of them are needed to build others.

 
 The important thing to remember is that even if you want only one
 project (@happy@, say), you must have a source tree whose root
 
 The important thing to remember is that even if you want only one
 project (@happy@, say), you must have a source tree whose root

@@ -1016,7 +1010,7 @@ change.  (The override occurs because the main boilerplate file,
 For example, @config.mk.in@ contains the definition:
 
 <tscreen><verb>
 For example, @config.mk.in@ contains the definition:
 
 <tscreen><verb>

-  ProjectsToBuild = glafp-utils literate ghc hslibs
+  ProjectsToBuild = glafp-utils ghc

 </verb></tscreen>
 
 The accompanying comment explains that this is the list of enabled
 </verb></tscreen>
 
 The accompanying comment explains that this is the list of enabled

@@ -1031,7 +1025,7 @@ add @green-card@, you can add this line to @build.mk@:
 or, if you prefer,
 
 <tscreen><verb>
 or, if you prefer,
 
 <tscreen><verb>

-  ProjectsToBuild = glafp-utils literate ghc hslibs green-card
+  ProjectsToBuild = glafp-utils ghc green-card

 </verb></tscreen>
 
 (GNU @make@ allows existing definitions to have new text appended
 </verb></tscreen>
 
 (GNU @make@ allows existing definitions to have new text appended

@@ -1138,13 +1132,16 @@ extensively.
 
 In any directory you should be able to make the following:
 <descrip>
 
 In any directory you should be able to make the following:
 <descrip>

-<tag>@boot@:</tag> does the one-off preparation required to get ready
-for the real work.  Notably, it does @gmake depend@ in all directories
-that contain programs.  But @boot@ does more.  For example, you can't
-do @gmake depend@ in a directory of C program until you have converted
-the literate @.lh@ header files into standard @.h@ header files.
+
+<tag>@boot@:</tag> 
+
+does the one-off preparation required to get ready for the real work.
+Notably, it does @gmake depend@ in all directories that contain
+programs.  But @boot@ does more.  For example, you can't do @gmake
+depend@ in a directory of C program until you have converted the
+literate @.lh@ header files into standard @.h@ header files.

 Similarly, you can't convert a literate file to illiterate form until
 Similarly, you can't convert a literate file to illiterate form until

-you have built the @literate@ tools.  @boot@ takes care of these
+you have built the @unlit@ tool.  @boot@ takes care of these

 inter-directory dependencies.
 
 You should say @gmake boot@ right after configuring your build tree,
 inter-directory dependencies.
 
 You should say @gmake boot@ right after configuring your build tree,

@@ -1819,22 +1816,41 @@ can't find them, please ask.
 Assuming you've got them, unpack them on top of a fresh source tree.
 Then follow the `normal' instructions in Section~<ref
 id="sec:building-from-source" name="Buiding From Source"> for setting
 Assuming you've got them, unpack them on top of a fresh source tree.
 Then follow the `normal' instructions in Section~<ref
 id="sec:building-from-source" name="Buiding From Source"> for setting

-up a build tree and configuring it. The only extra thing to remember
-when booting from @.hc@ files is to add the following line to the
-@build.mk@ file:
+up a build tree. When you invoke the configure script, you'll have
+to tell the script about your intentions:

 
 <tscreen><verb>
 
 <tscreen><verb>

-GhcWithHscBuiltViaC=YES
+foo% ./configure --enable-hc-boot
+</verb></tscreen>
+<ncdx/--enable-hc-boot/
+<ncdx/--disable-hc-boot/
+
+Assuming it configures OK and you don't need to create @mk/build.mk@
+for any other purposes, the next step is to proceed with a @make boot@
+followed by @make all@. At the successful completion of @make all@,
+you should end up with a binary of the compiler proper,
+@ghc/compiler/hsc@, plus archives (but no @.hi@ files!) of the prelude
+libraries. To generate the Prelude interface files (and test drive the
+bootstrapped compiler), re-run the @configure@ script, but this time
+witout the @--enable-hc-boot@ option. After that re-create the
+contents of @ghc/lib@:
+
+<tscreen><verb>
+foo% ./configure
+ ....
+foo% cd ghc/lib
+foo% make clean
+foo% make boot
+foo% make all

 </verb></tscreen>
 </verb></tscreen>

-<ncdx/GhcWithHscBuiltViaC/

 
 

-and proceed with doing a @make boot@ followed by a @make all@.

 
 That's the mechanics of the boot process, but, of course, if you're
 trying to boot on a platform that is not supported and significantly
 `different' from any of the supported ones, this is only the start of
 the adventure...(ToDo: porting tips - stuff to look out for, etc.)
 
 
 That's the mechanics of the boot process, but, of course, if you're
 trying to boot on a platform that is not supported and significantly
 `different' from any of the supported ones, this is only the start of
 the adventure...(ToDo: porting tips - stuff to look out for, etc.)
 

+

 <sect>Known pitfalls in building Glasgow Haskell
 <label id="sec:build-pitfalls">
 <nidx>problems, building</nidx>
 <sect>Known pitfalls in building Glasgow Haskell
 <label id="sec:build-pitfalls">
 <nidx>problems, building</nidx>