<article>
<title>Building and Installing the Glasgow Functional Programming Tools Suite
-Version 3.02
+Version 4.02
<author>The GHC Team,
Department of Computing Science,
University of Glasgow,
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>
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
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
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
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.
<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>
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;
<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.
+
+Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other
+versions at your own risk!
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...)
-
-<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.
-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).
-
-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
-@netlib@.
-
-A PVM installation is slightly quirky, but easy to do. Just follow
-the @Readme@ instructions.
+@-monly-N-regs@ option; see the User's Guide)
<tag>@xargs@ on Solaris2:</tag>
<nidx>xargs, presupposed (Solaris only)</nidx>
<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@.
-
-<tag>@bash@ (Parallel Haskell only):</tag>
-<nidx>bash, presupposed (Parallel Haskell only)</nidx>
-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>Flex:</tag>
-<nidx>pre-supposed: flex</nidx>
-<nidx>flex, pre-supposed</nidx>
-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@.
+GNU Autoconf is needed if you intend to build from the CVS sources, it
+is <em/not/ needed if you just intend to build a standard source
+distribution.
-<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.
+Autoconf builds the @configure@ script from @configure.in@ and
+@aclocal.m4@. If you modify either of these files, you'll need
+Autoconf to rebuild @configure@.
<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>
-One @fptools@ projects is worth a quick note at this point, because
-it is 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.
-</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 parallel GHC (GPH)
+<label id="pre-supposed-gph-tools">
+<p>
+
+<descrip>
+<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.
+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).
+
+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
+@netlib@.
+
+A PVM installation is slightly quirky, but easy to do. Just follow
+the @Readme@ instructions.
+
+<tag>@bash@:</tag>
+<nidx>bash, presupposed (Parallel Haskell only)</nidx>
+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).
+</descrip>
<sect1> Tools for building the Documentation
<label id="pre-supposed-doc-tools">
<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
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.xs4all.nl/~cg/sgmltools/">.
+url="http://www.sgmltools.org/">
<tag>TeX:</tag>
<nidx>pre-supposed: TeX</nidx>
everything you need.
</descrip>
+<sect1> Other useful tools
+<label id="pre-supposed-other-tools">
+<p>
+
+<descrip>
+<tag>Flex:</tag>
+<nidx>pre-supposed: flex</nidx>
+<nidx>flex, pre-supposed</nidx>
+
+This is a quite-a-bit-better-than-Lex lexer. Used to build a couple
+of utilities in @glafp-utils@. Depending on your operating system,
+the supplied @lex@ may or may not work; you should get the GNU
+version.
+</descrip>
<sect>Building from source
<label id="sec:building-from-source">
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">
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
to tell the script about your intentions:
<tscreen><verb>
-foo% ./configure --enable-hc-booting
+foo% ./configure --enable-hc-boot
</verb></tscreen>
-<ncdx/--enable-hc-booting/
-<ncdx/--disable-hc-booting/
+<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@.
+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>
+
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.)
-The end product of this will (hopefully) be a binary of the
-compiler proper, @ghc/compiler/hsc@ plus an archive of the Haskell
-Prelude libraries.
<sect>Known pitfalls in building Glasgow Haskell
<label id="sec:build-pitfalls">
<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
...
</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
<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:
projects / ghc-hetmet.git / blobdiff