X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Finstalling.vsgml;h=4030811bdc1a6719ce61c468c2077222c1913aee;hb=86f8a058a1cdd8a100136e194e229bcd53bb1837;hp=540a3d116d6d49121d52e6fa93e168bbf8d9a3ef;hpb=3ba543096b52447db29721d4c22140f7074deafe;p=ghc-hetmet.git diff --git a/docs/installing.vsgml b/docs/installing.vsgml index 540a3d1..4030811 100644 --- a/docs/installing.vsgml +++ b/docs/installing.vsgml @@ -2,7 +2,7 @@
Building and Installing the Glasgow Functional Programming Tools Suite -Version 3.00 +Version 4.02 <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@ -<date>November 1997</date> +<date>April 1998</date> <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). -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> @@ -66,15 +63,15 @@ yourself; (b)~you want to build something ``extra''---e.g., a set of libraries with strictness-analysis turned off; or (c)~you want to hack on GHC yourself. -A source distribution contains complete sources for the @fptools@ -suite. Not only that, but the more awkward machine-independent steps -are done for you. For example, if you don't have @flex@<ncdx/flex/ -you'll find it convenient that the source distribution contains the -result of running @flex@ on the lexical analyser specification. If -you don't want to alter the lexical analyser then this saves you -having to find and install @flex@. You will still need a working -version of GHC on your machine in order to compile (most of) the -sources, however. +A source distribution contains complete sources for one or more +projects in the @fptools@ suite. Not only that, but the more awkward +machine-independent steps are done for you. For example, if you don't +have @flex@<ncdx/flex/ you'll find it convenient that the source +distribution contains the result of running @flex@ on the lexical +analyser specification. If you don't want to alter the lexical +analyser then this saves you having to find and install @flex@. You +will still need a working version of GHC on your machine in order to +compile (most of) the sources, however. We make source distributions more frequently than binary distributions; a release that comes with pre-compiled binaries @@ -83,10 +80,7 @@ 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 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 4.xx can be compiled up using 2.10 or later. <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 @@ -118,10 +112,9 @@ generated files at all. So if you check out a source tree from CVS you will need to install every utility so that you can build all the derived files from scratch. -Giving you access to the repository entails some systems administration -at our end; and we are a bit nervous about being submerged in bug reports -about our current working copy (which is, by definition, in flux). So -we are a bit cautious about offering CVS access. Feel free to ask though! +More information about our CVS repository is available at <url +name="The Fptools CVS Cheat Sheet" +url="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html">. </descrip> If you are going to do any building from sources (either from a source @@ -154,6 +147,11 @@ or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are in pretty good shape. Section <ref id="sec:port-info" name="Port Info"> gives the full run-down on ports or lack thereof. +NOTE: as of version 4.00, we lost a few ports. All of the x86 ports +are working, as is the Sparc/Solaris port, but the rest will need a +little work. Please contact us if you can provide hardware cycles +and/or porting expertise. + <item> Be sure that the ``pre-supposed'' utilities are installed. Section <ref id="sec:pre-supposed" name="Installing Pre-Supposed Utilities"> elaborates. @@ -357,10 +355,9 @@ Concurrent/Parallel Haskell probably won't work (yet). <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> @@ -641,8 +638,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@, -@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 @@ -668,10 +665,9 @@ script will tell you if you are missing something. for doing shell-scripty tasks that involve lots of text processing. It is pretty easy to install. -Perl~5 is the current version; GHC is Perl~4 friendly though. For -Win32 platforms, Perl~5 is recommended, we even strongly suggest you -pick up a port of Perl~5 for @cygwin32@, as the common Hip/ActiveWare -port of Perl is not Cool Enough for our purposes. +Perl~5 is required. For Win32 platforms, we strongly suggest you pick +up a port of Perl~5 for @cygwin32@, as the common Hip/ActiveWare port +of Perl is not Cool Enough for our purposes. Perl should be put somewhere so that it can be invoked by the @#!@ script-invoking mechanism. (I believe @/usr/bin/perl@ is preferred; @@ -681,26 +677,25 @@ be less than 32 characters long. <tag>GNU C (@gcc@):</tag> <nidx>pre-supposed: GCC (GNU C compiler)</nidx> <nidx>GCC (GNU C compiler), pre-supposed</nidx> -The current version is 2.7.2. +Version 2.7.2.x is known to work. If your GCC dies with ``internal error'' on some GHC source file, please let us know, so we can report it and get things improved. (Exception: on @iX86@ boxes---you may need to fiddle with GHC's -@-monly-N-regs@ option; ask if confused...) +@-monly-N-regs@ option; see the User's Guide) -<nidx/EGCS/ -EGCS (the Enhanced GNU Compiler Suite) may or may not work, we haven't -tested it fully yet. +<nidx/EGCS/ EGCS (the Enhanced GNU Compiler Suite) may or may not +work, we haven't tested it fully yet. <tag>PVM version 3:</tag> <nidx>pre-supposed: PVM3 (Parallel Virtual Machine)</nidx> <nidx>PVM3 (Parallel Virtual Machine), pre-supposed</nidx> + PVM is the Parallel Virtual Machine on which Parallel Haskell programs -run. (You only need this if you plan to run Parallel Haskell. +run. (You only need this if you plan to run Parallel Haskell. Concurent Haskell, which runs concurrent threads on a uniprocessor -doesn't need it.) -Underneath PVM, you can have (for example) a network of -workstations (slow) or a multiprocessor box (faster). +doesn't need it.) Underneath PVM, you can have (for example) a +network of workstations (slow) or a multiprocessor box (faster). The current version of PVM is 3.3.11; we use 3.3.7. It is readily available on the net; I think I got it from @research.att.com@, in @@ -729,8 +724,10 @@ library. <tag>Autoconf:</tag> <nidx>pre-supposed: Autoconf</nidx> <nidx>Autoconf, pre-supposed</nidx> + GNU Autoconf is used to build the @configure@ script from -@configure.in@ in a source distribution. If you modify @configure.in@, you'll need @autoconf@ to regenerate @configure@. +@configure.in@ in a source distribution. If you modify +@configure.in@, you'll need @autoconf@ to regenerate @configure@. <tag>@bash@ (Parallel Haskell only):</tag> <nidx>bash, presupposed (Parallel Haskell only)</nidx> @@ -738,62 +735,70 @@ 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). -<tag>Makeindex:</tag> -<nidx>pre-supposed: makeindex</nidx> -<nidx>makeindex, pre-supposed</nidx> -You won't need this unless you are re-making our documents. Makeindex -normally comes with a TeX distribution, but if not, we can provide -the latest and greatest. - -<tag>Tgrind:</tag> -<nidx>pre-supposed: tgrind</nidx> -<nidx>tgrind, pre-supposed</nidx> -This is required only if you remake lots of our documents <em/and/ -you use the @-t tgrind@ option with @lit2latex@ (also literate -programming), to do ``fancy'' typesetting of your code. <em/Unlikely./ - -<tag>Flex:</tag> -<nidx>pre-supposed: flex</nidx> +<tag>Flex:</tag> +<nidx>pre-supposed: flex</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.4, 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> + 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> <nidx>sed, pre-supposed</nidx> -You need a working @sed@ if you are going to build from sources. -The build-configuration stuff needs it. -GNU sed version 2.0.4 is no good! It has a bug in it that is tickled -by the build-configuration. 2.0.5 is ok. Others are probably ok too -(assuming we don't create too elaborate configure scripts..) + +You need a working @sed@ if you are going to build from sources. The +build-configuration stuff needs it. GNU sed version 2.0.4 is no good! +It has a bug in it that is tickled by the build-configuration. 2.0.5 +is ok. Others are probably ok too (assuming we don't create too +elaborate configure scripts..) + </descrip> -Two @fptools@ projects are worth a quick note at this point, because -they are useful for all the others: -<itemize> -<item> @glafp-utils@ contains several utilities which aren't -particularly Glasgow-ish, but Occasionally Indispensable. Like -@lndir@ for creating symbolic link trees. - -<item> @literate@ contains the Glasgow-built tools for generating -documentation. (The unoriginal idea is to be able to generate @latex@, @info@, -and program code from a single source file.) To get anywhere you'll -need at least @lit2pgm@, either from the @literate@ project, or -because it's already installed on your system. -</itemize> +One @fptools@ project is worth a quick note at this point, because it +is useful for all the others: @glafp-utils@ contains several utilities +which aren't particularly Glasgow-ish, but Occasionally Indispensable. +Like @lndir@ for creating symbolic link trees. + +<sect1> Tools for building the Documentation +<label id="pre-supposed-doc-tools"> +<p> + +The following additional tools are required if you want to format the +documentation that comes with the @fptools@ projects: +<descrip> +<tag>SGML-Tools:</tag> +<nidx>pre-supposed: SGML-Tools</nidx> +<nidx>SGML-Tools, pre-supposed</nidx> + +All our documentation is written in SGML, using the LinuxDoc DTD that +comes with the SGML-Tools, which is the most shrink-wrapped SGML suite +that we could find. Should unpack and build painlessly on most +architectures, and you can use it to generate HTML, Info, LaTeX (and +hence DVI and Postscript), Groff, and plain text output from any +LinuxDoc source file (including this manual). Sources are available +from <url name="The SGML-Tools Web Page" +url="http://www.sgmltools.org/"> + +<tag>TeX:</tag> +<nidx>pre-supposed: TeX</nidx> +<nidx>TeX, pre-supposed</nidx> +A decent TeX distribution is required if you want to produce printable +documentation. We recomment teTeX, which includes just about +everything you need. +</descrip> <sect>Building from source @@ -809,13 +814,13 @@ from the CVS repository or from a source distribution, and now you're sitting looking at a huge mound of bits, wondering what to do next. -Gingerly, you type @make all@. Wrong already! +Gingerly, you type @make@. Wrong already! -This rest of this guide is intended for duffers like me, who aren't really -interested in Makefiles and systems configurations, but who need -a mental model of the interlocking pieces so that they can -make them work, extend them consistently when adding new -software, and lay hands on them gently when they don't work. +This rest of this guide is intended for duffers like me, who aren't +really interested in Makefiles and systems configurations, but who +need a mental model of the interlocking pieces so that they can make +them work, extend them consistently when adding new software, and lay +hands on them gently when they don't work. <sect1>Your source tree <label id="sec:source-tree"> @@ -839,9 +844,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 -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 @@ -897,9 +900,9 @@ file unchanged; but the danger is that you think you've edited the source file whereas actually all you've done is edit the build-tree copy. More commonly you do want to edit the source file.) -Like the source tree, the top level of your build tree must (a linked -copy of) the root directory of the @fptools@ suite. Inside Makefiles, -the root of your build tree is called +Like the source tree, the top level of your build tree must be (a +linked copy of) the root directory of the @fptools@ suite. Inside +Makefiles, the root of your build tree is called @$(FPTOOLS_TOP)@<ncdx/FPTOOLS_TOP/. In the rest of this document path names are relative to @$(FPTOOLS_TOP)@ unless otherwise stated. For example, the file @ghc/mk/target.mk@ is actually @@ -1009,7 +1012,7 @@ change. (The override occurs because the main boilerplate file, 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 @@ -1024,7 +1027,7 @@ add @green-card@, you can add this line to @build.mk@: 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 @@ -1131,13 +1134,16 @@ extensively. 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 -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, @@ -1201,6 +1207,32 @@ linked buid tree to make this target. Most @Makefiles@ have targets other than these. You can find this out by looking in the @Makefile@ itself. +<sect1>Fast Making +<ncdx/fastmake/ +<nidx/dependencies, omitting/ +<nidx/FAST, makefile variable/ +<p> + +Sometimes the dependencies get in the way: if you've made a small +change to one file, and you're absolutely sure that it won't affect +anything else, but you know that @make@ is going to rebuid everything +anyway, the following hack may be useful: + +<tscreen> <verb> +gmake FAST=YES +</verb> </tscreen> + +This tells the make system to ignore dependencies and just build what +you tell it to. In other words, it's equivalent to temporarily +removing the @.depend@ file in the current directory (where +@mkdependHS@ and friends store their dependency information). + +A bit of history: GHC used to come with a @fastmake@ script that did +the above job, but GNU make provides the features we need to do it +without resorting to a script. Also, we've found that fastmaking is +less useful since the advent of GHC's recompilation checker (see the +User's Guide section on "Separate Compilation"). + <sect>The @Makefile@ architecture <nidx/makefile architecture/ <p> @@ -1786,22 +1818,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 -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> +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> -GhcWithHscBuiltViaC=YES +foo% ./configure + .... +foo% cd ghc/lib +foo% make clean +foo% make boot +foo% make all </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.) + <sect>Known pitfalls in building Glasgow Haskell <label id="sec:build-pitfalls"> <nidx>problems, building</nidx> @@ -1834,9 +1885,9 @@ in all cases. <item> -In compiling some support-code bits, e.g., in @ghc/runtime/gmp@ and -even in @ghc/lib@, you may get a few C-compiler warnings. We think -these are OK. +In compiling some support-code bits, e.g., in @ghc/rts/gmp@ and even +in @ghc/lib@, you may get a few C-compiler warnings. We think these +are OK. <item> When compiling via C, you'll sometimes get ``warning: assignment from @@ -1851,44 +1902,32 @@ ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ ... </verb></tscreen> - -<item> -Also harmless are some specialisation messages that you may see when -compiling GHC; e.g.: -<tscreen><verb> -SPECIALISATION MESSAGES (Desirable): -*** INSTANCES -{-# SPECIALIZE instance Eq [Class] #-} -{-# SPECIALIZE instance Eq (Class, [Class]) #-} -{-# SPECIALIZE instance Outputable [ClassOp] #-} -{-# SPECIALIZE instance Outputable [Id] #-} -</verb></tscreen> - - <item> In compiling the compiler proper (in @compiler/@), you <em/may/ get an ``Out of heap space'' error message. These can vary with the vagaries of different systems, it seems. The solution is simple: -(1)~add a suitable @-H@ flag to the @<module>_HC_OPTS@ @make@ variable -in the appropriate @Makefile@; (2)~try again: @gmake@. (Section~<ref -id="sec:suffix" name="Pattern Rules and Options">.) -Alternatively, just cut to the chase scene: -<tscreen><verb> -% cd ghc/compiler -% make EXTRA_HC_OPTS=-H32m # or some nice big number -</verb></tscreen> +<itemize> +<item> If you're compiling with GHC 4.00 or above, then the +<em/maximum/ heap size must have been reached. This is somewhat +unlikely, since the maximum is set to 64M by default. Anyway, you can +raise it with the @-optCrts-M<size>@ flag (add this flag to +@<module>_HC_OPTS@ @make@ variable in the appropriate @Makefile@). -<item> -Not too long into the build process, you may get a huge complaint -of the form: +<item> For GHC < 4.00, add a suitable @-H@ flag to the @Makefile@, as +above. + +</itemize> + +and try again: @gmake@. (see Section~<ref id="sec:suffix" +name="Pattern Rules and Options"> for information about +@<module>_HC_OPTS@.) + +Alternatively, just cut to the chase scene: <tscreen><verb> -Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27. +% cd ghc/compiler +% make EXTRA_HC_OPTS=-optCrts-M128M </verb></tscreen> -This indicates that your @perl@ was mis-installed; the binary is -unable to find the files for its ``built-in'' library. Speak to your -perl installer, then re-try. - <item> If you try to compile some Haskell, and you get errors from GCC about @@ -1914,14 +1953,6 @@ We'd be interested to know if this is still necessary. <item> -If you end up making documents that involve (La)TeX and/or @tib@ -(Simon's favourite), the odds are that something about your/our setup -will reach out and bite you. Yes, please complain; meanwhile, you can -do @make -n whatever.dvi@ to see the intended commands, then try to -muddle through, doing them by hand. - - -<item> GHC's sources go through @cpp@ before being compiled, and @cpp@ varies a bit from one Unix to another. One particular gotcha is macro calls like this: