<article>
<title>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,
G12 8QQ.
Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@
-<date>November 1997</date>
+<date>April 1998</date>
<abstract>
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>
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 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>
+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.
+
+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..)
+</descrip>
+
+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>
-<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>
-<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@.
-
-<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.
+<sect1> Tools for building the Documentation
+<label id="pre-supposed-doc-tools">
+<p>
-<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..)
+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>
-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>
+<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">
@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
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
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
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
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,
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>
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>
-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>
-<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>
<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