+++ /dev/null
-% Building and installing the Glasgow Functional Programming Tools Suite
-%
-% Version 3.00
-% July 1997
-
-
-\begin{onlystandalone}
-\documentstyle[11pt,literate]{article}
-\begin{document}
-\title{Building and installing the Glasgow Functional Programming Tools Suite\\
-Version~3.00}
-\author{The GHC Team\\
-Department of Computing Science\\
-University of Glasgow\\
-Glasgow, Scotland\\
-G12 8QQ\\
-\\
-Email: glasgow-haskell-\{users,bugs\}\@dcs.gla.ac.uk}
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\clearpage
-\end{onlystandalone}
-
-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.
-
-\section{Getting the Glasgow @fptools@ suite}
-
-Building the Glasgow tools {\em can} be complicated, mostly because
-there are so many permutations of what/why/how, e.g., ``Build Happy
-with HBC, everything else with GHC, leave out profiling, and test it
-all on the `real' NoFib programs.'' Yeeps!
-
-Happily, such complications don't apply to most people. A few common
-``strategies'' serve most purposes. Pick one and proceed
-as suggested:
-
-\begin{description}
-
-\item[Binary distribution.] If your only purpose is to install some
-of the @fptools@ suite then the easiest thing to do is to get a binary
-distribution. In the binary distribution everything is pre-compiled
-for your particular machine architecture and operating system, so all
-you should have to do is install the binaries and libraries in
-suitable places. Section~\ref{installing-bin-distrib} describes
-how to do this.
-
-A binary distribution may not work for you for two reasons. First, we
-may not have built the suite for the particular architecture/OS
-platform you want. That may be due to lack of time and energy (in
-which case you can get a source distribution and build from it; see
-below). Alternatively, it may be because we haven't yet ported the
-suite to your architecture, in which case you are considerably worse
-off.
-
-The second reason a binary distribution may not be what you want is
-if you want to read or modify the souce code.
-
-\item[Source distribution.]
-You have a supported platform, but (a)~you like the warm fuzzy feeling
-of compiling things 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@ 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
-is considered a major release, i.e., a release that we have some
-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.
-
-\item[Build GHC from intermediate C \tr{.hc} files:]
-You need a working GHC to use a source distribution. What if you don't
-have a working GHC? Then you have no choice but to ``bootstrap'' up
-from the intermediate C (\tr{.hc}) files that we provide.
-Building GHC on an unsupported platform falls into this category.
-Please see \sectionref{booting-from-C}.
-
-Once you have built GHC, you can build the other Glasgow tools with
-it.
-
-In theory, you can (could?) build GHC with another Haskell compiler
-(e.g., HBC). We haven't tried to do this for ages and it almost
-certainly doesn't work any more (for tedious reasons).
-
-\item[The CVS repository.]
-
-We make source distributions slightly more often than binary
-distributions; but still infrequently. If you want more up-to-the
-minute (but less tested) source code then you need to get access to
-our CVS repository.
-
-All the @fptools@ source code is held in a CVS repository. CVS is a
-pretty good source-code control system, and best of all it works over
-the network.
-
-The repository holds source code only. It holds no mechanically
-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!
-\end{description}
-
-If you are going to do any building from sources (either from a source
-distribution or the CVS repository) then you need to read all of this
-manual in detail.
-
-%************************************************************************
-%* *
-\section{Things to check before you start typing}
-%* *
-%************************************************************************
-
-Here's a list of things to check before you get started.
-\begin{enumerate}
-\item
-\index{disk space needed}
-Disk space needed: About 30MB (five hamburgers' worth) of disk space
-for the most basic binary distribution of GHC; more for some
-platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
-Haskell libraries) might take you to 8--10 hamburgers.
-
-You'll need over 100MB (say, 20 hamburgers' worth) if you need to
-build the basic stuff from scratch.
-
-
-All of the above are {\em estimates} of disk-space needs.(I don't yet
-know the disk requirements for the non-GHC tools).
-
-\item
-Use an appropriate machine, compilers, and things.
-
-SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
-or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
-in pretty good shape. \Sectionref{port-info} gives the full run-down
-on ports or lack thereof.
-
-\item
-Be sure that the ``pre-supposed'' utilities are installed.
-Section~\ref{sect_std-utils} elaborates.
-
-\item If you have any problem when building or installing the Glasgow
-tools, please check the ``known pitfalls''
-(\sectionref{build-pitfalls}). Also check the ``known bugs'' web page
-for GHC:
-
-\begin{center}
-@http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html@
-\end{center}
-
-If you feel there is still some shortcoming in our procedure or
-instructions, please report it.
-
-For GHC, please see the bug-reporting section of the User's guide
-(separate document), to maximise the usefulness of your report.
-
-If in doubt, please send a message to @glasgow-haskell-bugs@@dcs.gla.ac.uk@.
-\end{enumerate}
-
-
-%************************************************************************
-%* *
-\section[port-info]{What machines the Glasgow tools run on}
-\index{ports, GHC}
-\index{GHC ports}
-\index{supported platforms}
-\index{platforms, supported}
-%* *
-%************************************************************************
-
-The main question is whether or not the Haskell compiler (GHC) runs on
-your platform.
-
-A ``platform'' is a architecture/manufacturer/operating-system
-combination, such as @sparc-sun-solaris2@. Other common ones are
-@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
-@i386-unknown-solaris2@, @i386-unknown-freebsd@,
-@i386-unknown-cygwin32@, @m68k-sun-sunos4@, @mips-sgi-irix5@,
-@sparc-sun-sunos4@, @sparc-sun-solaris2@, @powerpc-ibm-aix@.
-
-Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
-work on all machines for which basic Haskell compiling is supported.
-
-Some libraries may only work on a limited number of platforms; for
-example, a sockets library is of no use unless the operating system
-supports the underlying BSDisms.
-
-%************************************************************************
-%* *
-\subsection{What platforms the Haskell compiler (GHC) runs on}
-%* *
-%************************************************************************
-\index{fully-supported platforms}
-\index{native-code generator}
-\index{registerised ports}
-\index{unregisterised ports}
-
-The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
-generator; (b)~next best is a ``registerised''
-port; (c)~the bare minimum is an ``unregisterised'' port.
-(``Unregisterised'' is so terrible that we won't say more about it).
-
-We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
-running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
-unsurprisingly. Both have native-code generators, for quicker
-compilations. The native-code generator for iX86 platforms (e.g.,
-Linux ELF) is {\em nearly} working; but is not turned on by default.
-
-Here's everything that's known about GHC ports. We identify platforms
-by their ``canonical'' CPU/Manufacturer/OS triple.
-
-Note that some ports are fussy about which GCC version you use; or
-require GAS; or ...
-
-\begin{description}
-%-------------------------------------------------------------------
-\item[\tr{alpha-dec-osf1}:]
-\index{alpha-dec-osf1: fully supported}
-(We have OSF/1 V2.0.) Fully supported, including native-code generator.
-We recommend GCC 2.6.x or later.
-
-%-------------------------------------------------------------------
-\item[\tr{sparc-sun-sunos4}:]
-\index{sparc-sun-sunos4: fully supported}
-Fully supported, including native-code generator.
-
-%-------------------------------------------------------------------
-\item[\tr{sparc-sun-solaris2}:]
-\index{sparc-sun-solaris2: fully supported}
-Fully supported, including native-code generator. A couple of quirks,
-though: (a)~the profiling libraries are bizarrely huge; (b)~the
-default \tr{xargs} program is atrociously bad for building GHC
-libraries (see \sectionref{Pre-supposed} for details).
-
-%-------------------------------------------------------------------
-\item[HP-PA box running HP/UX 9.x:]
-\index{hppa1.1-hp-hpux: registerised port}
-Works registerised. No native-code generator.
-For GCC, you're best off with one of the Utah releases of
-GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
-We think a straight GCC 2.7.x works, too.
-
-Concurrent/Parallel Haskell probably don't work (yet).
-\index{hppa1.1-hp-hpux: concurrent---no}
-\index{hppa1.1-hp-hpux: parallel---no}
-
-%-------------------------------------------------------------------
-\item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
-\index{i386-*-linux: registerised port}
-GHC works registerised.
-You {\em must} have GCC 2.7.x or later.
-The iX86 native-code generator is {\em nearly} there, but it
-isn't turned on by default.
-
-Profiling works, and Concurrent Haskell works.
-\index{i386-*-linux: profiling---yes}
-\index{i386-*-linux: concurrent---yes}
-Parallel Haskell probably works.
-\index{i386-*-linux: parallel---maybe}
-
-On old Linux a.out systems: should be the same.
-\index{i386-*-linuxaout: registerised port}
-
-%-------------------------------------------------------------------
-\item[\tr{i386-*-freebsd} (PCs running FreeBSD 2.2 or higher, and
-NetBSD/OpenBSD using FreeBSD emulation):]
-\index{i386-*-freebsd:registerised port}
-GHC works registerised. Supports same set of bundles as the above.
-
-\index{i386-*-freebsd: profiling---yes}
-\index{i386-*-freebsd: concurrent---yes}
-\index{i386-*-freebsd: parallel---maybe}
-
-%-------------------------------------------------------------------
-\item[\tr{i386-unknown-cygwin32}:]
-\index{i386-unknown-cygwin32: fully supported}
-Fully supported under Win95/NT, including a native
-code generator. Requires the @cygwin32@ compatibility library and
-a healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
-Profiling works, so does Concurrent Haskell.
-\index{i386-*-cygwin32: profiling---yes}
-\index{i386-*-cygwin32: concurrent---yes}
-
-% ToDo: more documentation on this is reqd here.
-
-%-------------------------------------------------------------------
-\item[\tr{mips-sgi-irix5}:]
-\index{mips-sgi-irix5: registerised port}
-GHC works registerised (no native-code generator).
-I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
-was built with \tr{--with-gnu-as}; turns out that is important!
-
-Concurrent/Parallel Haskell probably don't work (yet).
-Profiling might work, but it is untested.
-\index{mips-sgi-irix5: concurrent---no}
-\index{mips-sgi-irix5: parallel---no}
-\index{mips-sgi-irix5: profiling---maybe}
-
-%-------------------------------------------------------------------
-\item[\tr{mips-sgi-irix6}:]
-\index{mips-sgi-irix6: registerised port}
-Thanks to the fine efforts of Tomasz Cholewo
-\tr{<tjchol01@mecca.spd.louisville.edu>}, GHC works registerised
-(no native code generator) under IRIX 6.2 and 6.3. Depends on having
-specially tweaked version of gcc-2.7.2 around, which can be downloaded
-from
-
-\begin{verbatim}
- http://mecca.spd.louisville.edu/~tjchol01/software/
-\end{verbatim}
-
-Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
-\index{mips-sgi-irix6: concurrent---maybe}
-\index{mips-sgi-irix6: parallel---maybe}
-\index{mips-sgi-irix6: profiling---yes}
-
-%-------------------------------------------------------------------
-\item[\tr{powerpc-ibm-aix}:]
-\index{powerpc-ibm-aix: registerised port}
-GHC works registerised (no native-code generator..yet).
-I suspect 2.7.x is what you need together with this.
-
-Concurrent/Parallel Haskell probably don't work (yet).
-Profiling might work, but it is untested.
-\index{mips-sgi-irix5: concurrent---no}
-\index{mips-sgi-irix5: parallel---no}
-\index{mips-sgi-irix5: profiling---maybe}
-
-%-------------------------------------------------------------------
-\item[\tr{m68k-apple-macos7} (Mac, using MPW):]
-\index{m68k-apple-macos7: historically ported}
-Once upon a time, David Wright in Tasmania has actually
-gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
-You may be able to get Thomson's from here. (Not sure that it will
-excite you to death, but...)
-
-No particularly recent GHC is known to work on a Mac.
-
-%-------------------------------------------------------------------
-\item[\tr{m68k-next-nextstep3}:]
-\index{m68k-next-nextstep3: historically ported}
-Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
-There's probably a little bit-rot since then, but otherwise it should
-still be fine.
-
-Concurrent/Parallel Haskell probably won't work (yet).
-\index{m68k-next-nextstep3: concurrent---no}
-\index{m68k-next-nextstep3: parallel---no}
-
-%-------------------------------------------------------------------
-\item[\tr{m68k-sun-sunos4} (Sun3):]
-\index{m68k-sun-sunos4: registerised port}
-GHC 2.0x hasn't been tried on a Sun3. GHC~0.26 worked registerised.
-No native-code generator.
-
-Concurrent/Parallel Haskell probably don't work (yet).
-\index{m68k-sun-sunos4: concurrent---no}
-\index{m68k-sun-sunos4: parallel---no}
-\end{description}
-
-%************************************************************************
-%* *
-\subsection{What machines the other tools run on}
-%* *
-%************************************************************************
-
-Unless you hear otherwise, the other tools work if GHC works.
-
-Haggis requires Concurrent Haskell to work.
-\index{Haggis, Concurrent Haskell}
-
-
-%************************************************************************
-%* *
-\section[installing-bin-distrib]{Installing from binary distributions}
-\index{binary installations}
-\index{installation, of binaries}
-%* *
-%************************************************************************
-
-Installing from binary distributions is easiest, and recommended!
-(Why binaries? Because GHC is a Haskell compiler written in Haskell,
-so you've got to ``bootstrap'' it, somehow. We provide
-machine-generated C-files-from-Haskell for this purpose, but it's
-really quite a pain to use them. If you must build GHC from its
-sources, using a binary-distributed GHC to do so is a sensible way to
-proceed. For the other @fptools@ programs, many are written in Haskell,
-so binary distributions allow you to install them without having a Haskell compiler.)
-
-
-\subsection{Bundle structure}
-
-Binary distributions come in ``bundles,''\index{bundles of binary stuff}
-one bundle per file called \tr{<bundle>-<platform>.tar.gz}.
-(See Section~\ref{port-info} for what a platform is.)
-Suppose that you untar a binary-distribution bundle, thus:
-\begin{verbatim}
- % cd /your/scratch/space
- % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
-\end{verbatim}
-Then you should find a single directory, @fptools@, with the following
-structure:
-\begin{description}
-\item[@Makefile.in@] the raw material from which the @Makefile@ will be made (\sectionref{sect_install}).
-\item[@configure@] the configuration script (\sectionref{sect_install}).
-\item[@README@] Contains this file summary.
-\item[@INSTALL@] Contains this description of how to install the bundle.
-\item[@ANNOUNCE@] The announcement message for the bundle.
-\item[@NEWS@] release notes for the bundle -- a longer version of
-@ANNOUNCE@. For GHC, the release notes are contained in the User
-Guide and this file isn't present.
-\item[@bin/<platform>@] contains platform-specific executable files to be invoked
-directly by the user. These are the files that must end up in your path.
-\item[@lib/<platform>@] contains platform-specific support files for the installation.
-Typically there is a subdirectory for each @fptools@ project, whose name is
-the name of the project with its version number. For example, for GHC
-there would be a sub-directory @ghc-x.xx/@ where @x.xx@ is the version
-number of GHC in the bundle.
-
-These sub-directories have the following general structure:
-\begin{description}
-\item[@libHS.a@ etc:] supporting library archives.
-\item[@ghc-iface.prl@ etc:] support scripts.
-\item[@import/@] Interface files (@.hi@) for the prelude.
-\item[@include/@] A few C @#include@ files.
-\end{description}
-
-\item[@share/@] contains platform-independent support files for the installation.
-Again, there is a sub-directory for each @fptools@ project.
-
-\item[@info/@] contains Emacs info documentation files (one sub-directory per project).
-\item[@html/@] contains HTML documentation files (one sub-directory per project).
-\item[@man/@] contains Unix manual pages.
-\end{description}
-This structure is designed so that you can unpack multiple bundles (including
-ones from different releases or platforms) into a single @fptools@ directory:
-\begin{verbatim}
- % cd /your/scratch/space
- % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
- % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -
-\end{verbatim}
-When you do multiple unpacks like this, the top level @Makefile@, @README@,
-and @INSTALL@ get overwritten each time. That's fine -- they should be the same.
-Likewise, the @ANNOUNCE-<bundle>@ and @NEWS-<bundle>@ files will be duplicated
-across multiple platforms, so they will be harmlessly overwritten when you do
-multiple unpacks.
-Finally, the @share/@ stuff will get harmlessly overwritten when you do multiple
-unpacks for one bundle on different platforms.
-
-\subsection[sect_install]{Installing}
-
-OK, so let's assume that you have unpacked your chosen bundles into a
-scratch directory @fptools@. What next? Well, you will at least need
-to run the @configure@ script by changing your directory to @fptools@
-and typing @./configure@. That should convert @Makefile.in@ to
-@Makefile@.
-
-You can now either start using the tools {\em in-situ} without going
-through any installation process, just type @make in-place@ to set the
-tools up for this (where @make@ is GNU make - you might have to type
-@gmake@ to get it). You'll also want to add the path which @make@ will
-now echo to your @PATH@ environment variable. This option is useful if
-you simply want to try out the package and/or you don't have the
-necessary priviledges (or inclination) to properly install the tools
-locally. Note that if you do decide to install the package `properly'
-at a later date, you have to go through the installation steps that
-follows.
-
-To install an @fptools@ package, you'll have to do the following:
-
-\begin{enumerate}
-\item Edit the @Makefile@ and check the settings of the following variables:
-\begin{description}
-\item[@platform@] the platform you are going to install for.
-\item[@bindir@] the directory in which to install user-invokable binaries.
-\item[@libdir@] the directory in which to install platform-dependent support files.
-\item[@datadir@] the directory in which to install platform-independent support files.
-\item[@infodir@] the directory in which to install Emacs info files.
-\item[@htmldir@] the directory in which to install HTML documentation.
-\item[@dvidir@] the directory in which to install DVI documentation.
-\end{description}
-The values for these variables can be set through invocation of the
-@configure@ script that comes with the distribution, but doing an optical
-diff to see if the values match your expectations is always a Good Idea.
-
-{\em Instead of running @configure@, it is perfectly OK to copy
-@Makefile.in@ to @Makefile@ and set all these variables directly
-yourself. But do it right!}
-
-\item Run @make install@. This {\em should} work with ordinary Unix
-@make@ -- no need for fancy stuff like GNU @make@.
-
-\item \tr{rehash} (t?csh users), so your shell will see the new stuff
-in your bin directory.
-
-\item
-Once done, test your ``installation'' as suggested in
-\sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you
-can see exactly what pathnames it's using.
-
-If things don't work as expected, check the list of know pitfalls
-\sectionref{build-pitfalls}.
-\end{enumerate}
-
-When installing the user-invokable binaries, this installation
-procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version
-number of GHC. It will also make a link (in the binary installation
-directory) from @ghc@ to @ghc-x.xx@. If you install multiple versions
-of GHC then the last one ``wins'', and ``@ghc@'' will invoke the last
-one installed. You can change this manually if you want. But
-regardless, @ghc-x.xx@ should always invoke GHC version @x.xx@.
-
-\subsection{What bundles there are}
-
-There are plenty of ``non-basic'' GHC bundles. The files for them are
-called \tr{ghc-x.xx-<bundle>-<platform>.tar.gz}, where the
-\tr{<platform>} is as above, and \tr{<bundle>} is one of these:
-\begin{description}
-\item[\tr{prof}:] Profiling with cost-centres. You probably want this.
-
-\item[\tr{conc}:] Concurrent Haskell features. You may want this.
-
-\item[\tr{par}:] Parallel Haskell features (sits on top of PVM).
-You'll want this if you're into that kind of thing.
-
-\item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
-(hmm... mainly for implementors).
-
-\item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
-information about ``what happened when I ran this program''---really
-for implementors.
-
-\item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
-
-\item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell.
-\end{description}
-
-One likely scenario is that you will grab {\em three} binary
-bundles---basic, profiling, and concurrent.
-
-
-
-%************************************************************************
-%* *
-\subsection[GHC_test]{Test that GHC seems to be working}
-\index{testing a new GHC}
-%* *
-%************************************************************************
-
-The way to do this is, of course, to compile and run {\em this} program
-(in a file \tr{Main.hs}):
-\begin{verbatim}
-main = putStr "Hello, world!\n"
-\end{verbatim}
-
-First, give yourself a convenient way to execute the driver script
-\tr{ghc/driver/ghc}, perhaps something like...
-\begin{verbatim}
-% ln -s /local/src/ghc-x.xx/ghc/driver/ghc ~/bin/alpha/ghc
-% rehash
-\end{verbatim}
-
-Compile the program, using the \tr{-v} (verbose) flag to verify that
-libraries, etc., are being found properly:
-\begin{verbatim}
-% ghc -v -o hello Main.hs
-\end{verbatim}
-
-Now run it:
-\begin{verbatim}
-% ./hello
-Hello, world!
-\end{verbatim}
-
-Some simple-but-profitable tests are to compile and run the
-notorious \tr{nfib} program, using different numeric types. Start
-with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
-\tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
-for this is distributed in \tr{ghc/misc/examples/nfib/}.
-
-For more information on how to ``drive'' GHC,
-either do \tr{ghc -help} or consult the User's Guide (distributed in
-\tr{ghc/docs/users_guide}).
-
-
-%************************************************************************
-%* *
-\section[Pre-supposed]{Installing pre-supposed utilities}
-\index{pre-supposed utilities}
-\index{utilities, pre-supposed}
-%* *
-%************************************************************************
-
-\label{sect_std-utils}
-
-Here are the gory details about some utility programs you may need;
-\tr{perl} and \tr{gcc} are the only important ones. (PVM is important
-if you're going for Parallel Haskell.) The \tr{configure} script will
-tell you if you are missing something.
-
-\begin{description}
-\item[Perl:]
-\index{pre-supposed: Perl}
-\index{Perl, pre-supposed}
-{\em You have to have Perl to proceed!} Perl is a language quite good
-for doing shell-scripty tasks that involve lots of text processing.
-It is pretty easy to install.
-
-Perl~5 is the current version; GHC should be Perl~4 friendly though.
-For Win32 platforms, Perl~5 is recommended, we even strongly suggest
-you pick up a port of Perl~5 for \tr{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 \tr{#!}
-script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
-we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
-be less than 32 characters long.
-
-\item[GNU C (\tr{gcc}):]
-\index{pre-supposed: GCC (GNU C compiler)}
-\index{GCC (GNU C compiler), pre-supposed}
-The current version is 2.7.2.
-
-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 \tr{iX86} boxes---you may need to fiddle with GHC's
-\tr{-monly-N-regs} option; ask if confused...)
-
-\item[PVM version 3:]
-\index{pre-supposed: PVM3 (Parallel Virtual Machine)}
-\index{PVM3 (Parallel Virtual Machine), pre-supposed}
-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 \tr{research.att.com}, in
-\tr{netlib}.
-
-A PVM installation is slightly quirky, but easy to do. Just follow
-the \tr{Readme} instructions.
-
-\item[\tr{xargs} on Solaris2:]
-\index{xargs, presupposed (Solaris only)}
-\index{Solaris: alternative xargs}
-The GHC libraries are put together with something like:
-\begin{verbatim}
-find bunch-of-dirs -name '*.o' -print | xargs ar q ...
-\end{verbatim}
-Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
-of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
-time---with near-infinite rebuilding of the symbol table in
-the \tr{.a} file.
-
-The best solution is to install a sane \tr{xargs} from the GNU
-findutils distribution. You can unpack, build, and install the GNU
-version in the time the Solaris \tr{xargs} mangles just one GHC
-library.
-
-\item[\tr{bash} (Parallel Haskell only):]
-\index{bash, presupposed (Parallel Haskell only)}
-Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
-to PostScript, is written in Bash (GNU's Bourne Again shell).
-This bug will be fixed (someday).
-
-\item[Makeindex:]
-\index{pre-supposed: makeindex}
-\index{makeindex, pre-supposed}
-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.
-
-\item[Tgrind:]
-\index{pre-supposed: tgrind}
-\index{tgrind, pre-supposed}
-This is required only if you remake lots of our documents {\em and}
-you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate
-programming), to do ``fancy'' typesetting of your code. {\em
-Unlikely.}
-
-\item[Flex:]
-\index{pre-supposed: flex}
-\index{flex, pre-supposed}
-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@.
-
-\item[Yacc:]
-\index{pre-supposed: non-worthless Yacc}
-\index{Yacc, pre-supposed}
-If you mess with the Haskell parser, you'll need a Yacc that can cope.
-The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK;
-Berkeley yacc, \tr{byacc}, is not OK.
-
-\item[@sed@]
-\index{pre-supposed: sed}
-\index{sed, pre-supposed}
-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..)
-\end{description}
-
-Two @fptools@ projects are worth a quick note at this point, because
-they are useful for all the others:
-\begin{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.
-\end{itemize}
-
-
-
-%************************************************************************
-%* *
-\section[building-from-source]{Building from source}
-\index{Building from source}
-%* *
-%************************************************************************
-
-You've been rash enough to want to build some of
-the Glasgow Functional Programming tools (GHC, Happy,
-nofib, etc) from source. You've slurped the source,
-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!
-
-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.
-
-\subsection{Your source tree}
-\label{source-tree}
-
-The source code is held in your {\em source tree}.
-The root directory of your source tree {\em must}
-contain the following directories and files:
-\begin{itemize}
-\item @Makefile@: the root Makefile.
-\item @mk/@: the directory that contains the
-main Makefile code, shared by all the
-@fptools@ software.
-\item @configure.in@, @config.sub@, @config.guess@:
-these files support the configuration process.
-\item @install-sh@.
-\end{itemize}
-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 @happy@ to build
-@ghc@. You can either grab @happy@ too, or else you can use
-a version of @happy@ that's already installed on your system, or
-grab a binary distribution of @happy@ and install it.
-
-The important thing to remember is that even if you want only one
-project (@happy@, say), you must have a source tree whose root
-directory contains @Makefile@, @mk/@, @configure.in@, and the
-project(s) you want (@happy/@ in this case). You cannot get by with
-just the @happy/@ directory.
-
-\subsection{Build trees}
-
-While you can build a system in the source tree, we don't recommend it.
-We often want to build multiple versions of our software
-for different architectures, or with different options (e.g. profiling).
-It's very desirable to share a single copy of the source code among
-all these builds.
-
-So for every source tree we have zero or more {\em build trees}. Each
-build tree is initially an exact copy of the source tree, except that
-each file is a symbolic link to the source file, rather than being a
-copy of the source file. There are ``standard'' Unix utilities that
-make such copies, so standard that they go by different names:
-@lndir@, @mkshadowdir@ are two (If you don't have either, the source
-distribution includes sources for the \tr{X11} \tr{lndir} --- check
-out \tr{fptools/glafp-utils/lndir} ).
-
-The build tree does not need to be anywhere near the source tree in
-the file system. Indeed, one advantage of separating the build tree
-from the source is that the build tree can be placed in a
-non-backed-up partition, saving your systems support people from
-backing up untold megabytes of easily-regenerated, and
-rapidly-changing, gubbins. The golden rule is that (with a single
-exception -- Section~\ref{sect_build-config}) {\em absolutely
-everything in the build tree is either a symbolic link to the source
-tree, or else is mechanically generated}. It should be perfectly OK
-for your build tree to vanish overnight; an hour or two compiling and
-you're on the road again.
-
-You need to be a bit careful, though, that any new files you create
-(if you do any development work) are in the source tree, not a build tree!
-
-Remember, that the source files in the build tree are {\em symbolic
-links} to the files in the source tree. (The build tree soon
-accumulates lots of built files like @Foo.o@, as well.) You can {\em
-delete} a source file from the build tree without affecting the source
-tree (though it's an odd thing to do). On the other hand, if you {\em
-edit} a source file from the build tree, you'll edit the source-tree
-file directly. (You can set up Emacs so that if you edit a source
-file from the build tree, Emacs will silently create an edited copy of
-the source file in the build tree, leaving the source 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 @$(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 @$(FPTOOLS_TOP)/ghc/mk/target.mk@.
-
-
-\subsection{Getting the build you want}
-\label{sect_build-config}
-
-When you build @fptools@ you will be compiling code on a particular
-{\em host platform}, to run on a particular {\em target platform}
-(usually the same as the host platform)\index{platform}. The
-difficulty is that there are minor differences between different
-platforms; minor, but enough that the code needs to be a bit different
-for each. There are some big differences too: for a different
-architecture we need to build GHC with a different native-code
-generator.
-
-There are also knobs you can turn to control how the @fptools@
-software is built. For example, you might want to build GHC optimised
-(so that it runs fast) or unoptimised (so that you can compile it fast
-after you've modified it. Or, you might want to compile it with
-debugging on (so that extra consistency-checking code gets included)
-or off. And so on.
-
-All of this stuff is called the {\em configuration} of your build.
-You set the configuration using an exciting three-step process.
-\begin{description}
-
-\item[Step 1: get ready for configuration.] Change directory to
-@$(FPTOOLS)@ and issue the command @autoconf@ (with no
-arguments). This GNU program converts @$(FPTOOLS)/configure.in@ to a
-shell script called @$(FPTOOLS)/configure@.
-
-Both these steps are completely platform-independent; they just mean
-that the human-written file (@configure.in@) can be short, although
-the resulting shell script, @configure@, and @mk/config.h.in@, are
-long.
-
-In case you don't have @autoconf@ we distribute the results,
-@configure@, and @mk/config.h.in@, with the source distribution. They
-aren't kept in the repository, though.
-
-\item[Step 2: system configuration.]
-Runs the newly-created @configure@ script, thus:
-\begin{verbatim}
- ./configure
-\end{verbatim}
-@configure@'s mission
-is to scurry round your computer working out what architecture it has,
-what operating system, whether it has the @vfork@ system call,
-where @yacc@ is kept, whether @gcc@ is available, where various
-obscure @#include@ files are, whether it's a leap year, and
-what the systems manager had for lunch.
-It communicates these snippets of information in two ways:
-\begin{itemize}
-\item It translates @mk/config.mk.in@ to @mk/config.mk@,
-substituting for things between ``{\tt @@@@}'' brackets. So,
-``{\tt @@HaveGcc@@}'' will be replaced by ``@YES@'' or ``@NO@''
-depending on what @configure@ finds.
-@mk/config.mk@ is included by every Makefile (directly or indirectly),
-so the configuration information is thereby communicated to
-all Makefiles.
-
-\item It translates @mk/config.h.in@ to @mk/config.h@.
-The latter is @#include@d by various C programs, which
-can thereby make use of configuration information.
-\end{itemize}
-@configure@ caches the results of its run in @config.cache@.
-Quite often you don't want that; you're running @configure@ a second time
-because something has changed. In that case, simply delete @config.cache@.
-
-\item[Step 3: build configuration.] Next, you say how this build
-of @fptools@ is to differ from the standard defaults by creating a new
-file @mk/build.mk@
-{\em in the build tree}. This file is the one and only
-file you edit in the build tree, precisely because it says how
-this build differs from the source. (Just in case your build tree
-does die, you might want to keep a private directory of @build.mk@ files,
-and use a symbolic link in each build tree to point to the appropriate one.)
-So @mk/build.mk@ never
-exists in the source tree --- you create one in each build tree
-from the template. We'll discuss what to put in it shortly.
-\end{description}
-And that's it for configuration. Simple, eh?
-
-What do you put in your build-specific configuration
-file @mk/build.mk@? {\em For almost all purposes all you will do is
-put make variable definitions that override those in @mk/config.mk.in@}.
-The whole point of @mk/config.mk.in@ --- and its derived
-counterpart @mk/config.mk@ --- is to define the build configuration. It is heavily
-commented, as you will see if you look at it.
-So generally, what you do is edit @mk/config.mk.in@ (read-only), and add definitions
-in @mk/build.mk@ that override any of the @config.mk@ definitions that you
-want to change. (The override occurs because the main boilerplate file,
-@mk/boilerplate.mk@, includes @build.mk@ after @config.mk@.)
-
-For example, @config.mk.in@ contains the definition:
-\begin{verbatim}
- ProjectsToBuild = glafp-utils literate happy ghc hslibs
-\end{verbatim}
-The accompanying comment explains that this is the list of enabled
-projects; that is, if (after configuring) you type @gmake all@
-in @FPTOOLS_TOP@ three specified projects will be made.
-If you want to add @green-card@, you can add this line to @build.mk@:
-\begin{verbatim}
- ProjectsToBuild += green-card
-\end{verbatim}
-or, if you prefer,
-\begin{verbatim}
- ProjectsToBuild = glafp-utils literate happy ghc hslibs green-card
-\end{verbatim}
-(GNU @make@ allows existing definitions to have new text appended using
-the ``@+=@'' operator, which is quite a convenient feature.)
-
-When reading @config.mk.in@, remember that anything between ``{\tt @@...@@}'' signs
-is going to be substituted by @configure@ later. You {\em can} override
-the resulting definition if you want,
-but you need to be a bit surer what you are doing.
-For example, there's a line that says:
-\begin{verbatim}
- YACC = @Yacc@
-\end{verbatim}
-This defines the Make variables @YACC@ to the pathname for a Yacc that
-@configure@ finds somewhere. If you have your own pet Yacc you want
-to use instead, that's fine. Just add this line to @mk/build.mk@:
-\begin{verbatim}
- YACC = myyacc
-\end{verbatim}
-You do not {\em have} to have a @mk/build.mk@ file at all; if you don't,
-you'll get all the default settings from @mk/config.mk.in@.
-
-You can also use @build.mk@ to override anything that @configure@ got
-wrong. One place where this happens often is with the definition of
-@FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
-to the top of your source tree, but if your system uses an automounter
-then the correct directory is hard to find automatically. If you find
-that @configure@ has got it wrong, just put the correct definition in
-@build.mk@.
-
-\subsection{The story so far}
-
-Let's summarise the steps you need to carry to get yourself
-a fully-configured build tree from scratch.
-
-\begin{enumerate}
-\item Get your source tree from somewhere (CVS repository or
-source distribution). Say you call the root directory
-@myfptools@ (it does not have to be called @fptools@).
-Make sure that you have the essential files (see Section~\ref{source-tree}).
-
-\item Use @lndir@ or @mkshadowdir@ to create a build tree.
-\begin{verbatim}
- cd myfptools
- mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
-\end{verbatim}
-You probably want to give the build tree a name that
-suggests its main defining characteristic (in your mind at least),
-in case you later add others.
-
-\item Change directory to the build tree. Everything is going
-to happen there now.
-\begin{verbatim}
- cd /scratch/joe-bloggs/myfptools-sun4
-\end{verbatim}
-\item Prepare for system configuration:
-\begin{verbatim}
- autoconf
-\end{verbatim}
-(You can skip this step if you are starting from a source distribution,
-and you already have @configure@ and @mk/config.h.in@.)
-
-\item Do system configuration:
-\begin{verbatim}
- ./configure
-\end{verbatim}
-
-\item Create the file @mk/build.mk@,
-adding definitions for your desired configuration options.
-\begin{verbatim}
- emacs mk/build.mk
-\end{verbatim}
-\end{enumerate}
-You can make subsequent changes to @mk/build.mk@ as often
-as you like. You do not have to run any further configuration
-programs to make these changes take effect.
-In theory you should, however, say @gmake clean@, @gmake all@,
-because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
-
-\subsection{Making things}
-
-At this point you have made yourself a fully-configured build tree,
-so you are ready to start building real things.
-
-The first thing you need to know is that
-{\em you must use GNU @make@, usually called @gmake@, not standard Unix @make@}.
-If you use standard Unix @make@ you will get all sorts of error messages
-(but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
-extensively.
-
-\subsection[sect_standard-targets]{Standard targets}
-
-In any directory you should be able to make the following:
-\begin{description}
-\item[@boot@:] 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 convert a literate file to illiterate form until you
-have built the @literate@ tools. @boot@ takes care of these
-inter-directory dependencies.
-
-You should say @gmake boot@ right after configuring your build tree,
-but note that this is a one-off, i.e., there's no need to re-do
-@gmake boot@ if you should re-configure your build tree at a later
-stage (no harm caused if you do though).
-
-\item[@all@:] makes all the final target(s) for this Makefile.
-Depending on which directory you are in a ``final target''
-may be an executable program, a library archive, a shell script,
-or a Postscript file.
-Typing @gmake@ alone is generally the same as typing @gmake all@.
-
-\item[@install@:] installs the things built by @all@. Where does it
-install them? That is specified by @mk/config.mk.in@; you can
-override it in @mk/build.mk@.
-
-\item[@uninstall@:] reverses the effect of @install@.
-
-\item[@clean@:] remove all easily-rebuilt files.
-
-\item[@veryclean@:] remove all files that can be rebuilt at all.
-There's a danger here that you may remove a file that needs a more
-obscure
-utility to rebuild it (especially if you started from a source
-distribution).
-
-\item[@check@:] run the test suite.
-\end{description}
-All of these standard targets
-automatically recurse into sub-directories.
-Certain other standard targets do not:
-\begin{description}
-\item[@configure@:] is only available in the root directory @$(FPTOOLS)@;
-it has been discussed in Section~\ref{sect_build-config}.
-
-\item[@depend@:] make a @.depend@ file in each directory that needs
-it. This @.depend@ file contains mechanically-generated dependency
-information; for example, suppose a directory contains a Haskell
-source module @Foo.lhs@ which imports another module @Baz@.
-Then the generated @.depend@ file will contain the dependency:
-\begin{verbatim}
- Foo.o : Baz.hi
-\end{verbatim}
-which says that the object file @Foo.o@ depends on the interface
-file @Baz.hi@ generated by compiling module @Baz@.
-The @.depend@ file is automatically included by every Makefile.
-
-\item[@binary-dist@:] make a binary distribution.
-
-\item[@dist@:] make a source distribution.
-\end{description}
-
-\subsection{Other targets}
-
-Most @Makefiles@ have targets other than these. You can find
-this out by looking in the @Makefile@ itself.
-
-
-
-
-%************************************************************************
-%* *
-\section{The @Makefile@ architecture}
-%* *
-%************************************************************************
-
-
-@make@ is great if everything works --- you type @gmake install@ and, lo,
-the right things get compiled and installed in the right places.
-Our goal is to make this happen often, but somehow it often doesn't;
-instead
-some wierd error message eventually emerges from the bowels of a directory
-you didn't know existed.
-
-The purpose of this section is to give you a road-map to help you figure
-out what is going right and what is going wrong.
-
-\subsection{A small project}
-
-To get started, let us look at the @Makefile@ for an imaginary small
-@fptools@ project, @small@. Each project in @fptools@ has its own
-directory in @FPTOOLS_TOP@, so the @small@ project will have its own
-directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
-will be a @Makefile@, looking something like this:
-\begin{verbatim}
- # Makefile for fptools project "small"
-
- TOP = ..
- include $(TOP)/mk/boilerplate.mk
-
- SRCS = $(wildcard *.lhs) $(wildcard *.c)
- HS_PROG = small
-
- include $(TOP)/target.mk
-\end{verbatim}
-This @Makefile@ has three sections:
-\begin{enumerate}
-\item The first section includes\footnote{One of the
-most important features of GNU @make@ that we use is the ability
-for a @Makefile@ to include another named file, very like @cpp@'s @#include@ directive.}
-a file of ``boilerplate'' code from the
-level above (which in this case will be @FPTOOLS_TOP/mk/boilerplate.mk@).
-As its name suggests, @boilerplate.mk@ consists of a large quantity of standard
-@Makefile@ code. We discuss this boilerplate in more detail in Section~\ref{sect_boiler}.
-
-Before the @include@ statement, you must define the @make@ variable
-@TOP@ to be the directory containing the @mk@ directory in which
-the @boilerplate.mk@ file is.
-It is {\em not} OK to simply say
-\begin{verbatim}
- include ../mk/boilerplate.mk # NO NO NO
-\end{verbatim}
-Why? Because the @boilerplate.mk@ file needs to know where it is,
-so that it can, in turn, @include@ other files.
-(Unfortunately, when an @include@d file does an
-@include@, the filename is treated
-relative to the directory in which @gmake@ is being run, not
-the directory in which the @included@ sits.)
-In general,
-{\em every file @foo.mk@
-assumes that @$(TOP)/mk/foo.mk@ refers to itself.}
-It is up to the @Makefile@ doing the @include@ to ensure this
-is the case.
-
-Files intended for inclusion in other @Makefile@s are written to have
-the following property:
-{\em after @foo.mk@ is @include@d, it leaves @TOP@ containing the same
-value as it had just before the @include@ statement}.
-In our example, this invariant guarantees that the @include@
-for @target.mk@ will look in the same directory as that for
-@boilerplate.mk@.
-
-\item The second section
-defines the following standard @make@ variables: @SRCS@ (the source files from
-which is to be built), and @HS_PROG@ (the
-executable binary to be built).
-We will discuss in more detail what the ``standard variables'' are,
-and how they affect what happens, in Section~\ref{sect_targets}.
-
-The definition for @SRCS@ uses the useful GNU @make@
-construct @$(wildcard@~$pat$@)@, which expands to a list of all the
-files matching the pattern $pat$ in the current directory.
-In this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@ files
-in the directory. (Let's suppose there is one of each, @Foo.lhs@
-and @Baz.c@.)
-
-\item The last section includes a second file of standard code,
-called @target.mk@. It contains the rules that tell @gmake@
-how to make the standard targets
-(Section~\ref{sect_standard-targets}).
-Why, you ask, can't this standard code
-be part of @boilerplate.mk@? Good question.
-We discuss the reason later, in Section~\ref{sect_boiler-arch}.
-
-You do not {\em have} to @include@ the @target.mk@ file. Instead,
-you can write rules of your own for all the standard targets.
-Usually, though, you will find quite a big payoff from using
-the canned rules in
-@target.mk@; the price tag is that you have to understand
-what canned rules get enabled, and what they do (Section~\ref{sect_targets}).
-\end{enumerate}
-
-In our example @Makefile@, most of the work is done
-by the two @include@d files. When you say @gmake all@,
-the following things happen:
-\begin{itemize}
-\item @gmake@ figures out that the object files are @Foo.o@ and @Baz.o@.
-\item It uses a boilerplate pattern rule to compile
-@Foo.lhs@ to @Foo.o@ using
-a Haskell compiler. (Which one? That is set in the build configuration.)
-\item It uses another standard pattern rule to compile @Baz.c@ to @Baz.o@,
-using a C compiler. (Ditto.)
-\item It links the resulting @.o@ files together to make @small@,
-using the Haskell compiler to do the link step. (Why not use @ld@? Because
-the Haskell compiler knows what standard librarise to link in. How did @gmake@
-know to use the Haskell compiler to do the link, rather than the C compiler?
-Because we set the variable @HS_PROG@ rather than @C_PROG@.)
-\end{itemize}
-All @Makefile@s should follow the above three-section format.
-
-\subsection{A larger project}
-
-Larger projects are usually structured into a nummber of sub-directories,
-each of which has its own @Makefile@. (In very large projects, this
-sub-structure might be iterated recursively, though that is rare.)
-To give you the idea, here's part of the directory structure for
-the (rather large) @ghc@ project:
-\begin{verbatim}
- $(FPTOOLS_TOP)/ghc/
- Makefile
-
- mk/
- boilerplate.mk
- rules.mk
-
- docs/
- Makefile
- ...source files for documentation...
-
- driver/
- Makefile
- ...source files for driver...
-
- compiler/
- Makefile
- parser/...source files for parser...
- renamer/...source files for renamer...
- ...etc...
-\end{verbatim}
-The sub-directories @docs@, @driver@, @compiler@, and so on, each contains
-a sub-component of @ghc@, and each has its own @Makefile@.
-There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@.
-It does most of its work by recursively invoking @gmake@
-on the @Makefile@s in the sub-directories.
-We say that @ghc/Makefile@ is a {\em non-leaf @Makefile@},
-because it does little except organise its children, while the @Makefile@s
-in the sub-directories are all {\em leaf @Makefile@s}. (In principle
-the sub-directories might themselves contain a non-leaf @Makefile@ and
-several sub-sub-directories, but that does not happen in @ghc@.)
-
-The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
-though the @ghc/compiler@ has sub-directories, because these sub-directories
-do not themselves have @Makefile@ in them. They are just used to structure
-the collection of modules that make up @ghc@, but all are managed by the
-single @Makefile@ in @ghc/compiler@.
-
-You will notice that @ghc/@ also contains a directory @ghc/mk/@.
-It contains @ghc@-specific @Makefile@ boilerplate code.
-More precisely:
-\begin{itemize}
-\item @ghc/mk/boilerplate.mk@ is included at the top of @ghc/Makefile@,
-and of all the leaf @Makefile@s in the sub-directories.
-It in turn @include@s the main boilerplate file @mk/boilerplate.mk@.
-
-\item @ghc/mk/target.mk@ is @include@d at the bottom of @ghc/Makefile@,
-and of all the leaf @Makefiles@ in the sub-directories.
-It in turn @include@s the file @mk/target.mk@.
-\end{itemize}
-So these two files are the place to look for @ghc@-wide customisation
-of the standard boilerplate.
-
-
-
-\subsection{Boilerplate architecture}
-\label{sect_boiler-arch}
-
-Every @Makefile@ includes a @boilerplate.mk@ file at the top,
-and @target.mk@ file at the bottom. In this section we discuss
-what is in these files, and why there have to be two of them.
-In general:
-\begin{itemize}
-\item @boilerplate.mk@ consists of:
-\begin{itemize}
-\item {\em Definitions of millions of @make@ variables} that collectively
-specify the build configuration. Examples: @HC_OPTS@, the options to
-feed to the Haskell compiler; @NoFibSubDirs@, the sub-directories to
-enable within the @nofib@ project; @GhcWithHc@, the name of the
-Haskell compiler to use when compiling @GHC@ in the @ghc@ project.
-\item {\em Standard pattern rules} that tell @gmake@ how to construct
-one file from another.
-\end{itemize}
-@boilerplate.mk@ needs to be @include@d at the {\em top} of each
-@Makefile@, so that the
-user can replace the boilerplate definitions or pattern rules by simply
-giving a new definition or pattern rule in the @Makefile@. @gmake@ simply
-takes the last definition as the definitive one.
-
-Instead of {\em replacing} boilerplate definitions, it is also quite
-common to {\em augment} them. For example, a @Makefile@ might say:
-\begin{verbatim}
- SRC_HC_OPTS += -O
-\end{verbatim}
-thereby adding ``@-O@'' to the end of @SRC_HC_OPTS@.
-
-\item @target.mk@ contains @make@ rules for the standard targets described
-in Section~\ref{sect_standard-targets}.
-These rules are selectively included, depending on the setting of
-certain @make@ variables. These variables are usually set in the middle
-section of the @Makefile@ between the two @include@s.
-
-@target.mk@ must be included at the end (rather than being part of @boilerplate.mk@)
-for several tiresome reasons:
-\begin{itemize}
-\item @gmake@ commits target and dependency lists earlier than it should.
-For example, @target.mk@ has a rule that looks like this:
-\begin{verbatim}
- $(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@
-\end{verbatim}
-If this rule was in @boilerplate.mk@ then @$(HS_PROG)@ and @$(OBJS)@
-would not have their final values at the moment @gmake@ encountered the
-rule. Alas, @gmake@ takes a snapshot of their current values, and
-wires that snapshot into the rule.
-(In contrast, the commands executed when the rule ``fires'' are
-only substituted at the moment of firing.)
-So, the rule must follow the definitions given in the @Makefile@ itself.
-
-\item Unlike pattern rules, ordinary rules cannot be overriden or
-replaced by subsequent rules for the same target (at least not without an
-error message). Including ordinary rules in @boilerplate.mk@ would
-prevent the user from writing rules for specific targets in specific cases.
-
-\item There are a couple of other reasons I've forgotten, but it doesn't
-matter too much.
-\end{itemize}
-\end{itemize}
-
-\subsection{The main @mk/boilerplate.mk@ file}
-\label{sect_boiler}
-
-If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find that
-it consists of the following sections, each held in a separate file:
-\begin{description}
-\item[@config.mk@] is the build configuration file we discussed at length
-in Section~\ref{sect_build-config}.
-
-\item[@paths.mk@] defines @make@ variables for pathnames and file
-lists. In particular, it gives definitions for:
-\begin{description}
-\item[@SRCS@:] all source files in the current directory.
-\item[@HS_SRCS@:] all Haskell source files in the current directory.
-It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
-@HS_SRCS@ will follow suit.
-\item[@C_SRCS@:] similarly for C source files.
-\item[@HS_OBJS@:] the @.o@ files derived from @$(HS_SRCS)@.
-\item[@C_OBJS@:] similarly for @$(C_SRCS)@.
-\item[@OBJS@:] the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
-\end{description}
-Any or all of these definitions can easily be overriden by giving new
-definitions in your @Makefile@. For example,
-if there are things in the current directory that look like source files
-but aren't, then you'll need to set @SRCS@ manually in your @Makefile@.
-The other definitions will then work from this new definition.
-
-What, exactly, does @paths.mk@ consider a ``source file'' to be.
-It's based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc),
-but this is the kind of detail that changes
-more rapidly, so rather than enumerate the source suffices here the best thing
-to do is to look in @paths.mk@.
-
-\item[@opts.mk@] defines @make@ variables for option strings to
-pass to each program. For example, it defines @HC_OPTS@, the
-option strings to pass to the Haskell compiler. See \sectionref{sect_suffix}.
-
-\item[@suffix.mk@] defines standard pattern rules -- see \sectionref{sect_suffix}
-\end{description}
-Any of the variables and pattern rules defined by the boilerplate file
-can easily be overridden in any particular @Makefile@, because
-the boilerplace @include@ comes first. Definitions after this
-@include@ directive simply override the default ones in @boilerplate.mk@.
-
-\subsection[sect_suffix]{Pattern rules and options}
-
-The file @suffix.mk@ defines standard {\em pattern rules} that say how to build one kind
-of file from another, for example, how to build a @.o@ file from a @.c@ file.
-(GNU @make@'s {\em pattern rules} are more powerful and easier to use than
-Unix @make@'s {\em suffix rules}.)
-
-Almost all the rules look something like this:
-\begin{verbatim}
-%.o : %.c
- @$(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@
-\end{verbatim}
-Here's how to understand the rule. It says that $something@.o@$ (say @Foo.o@)
-can be built from $something@.c@$ (@Foo.c@), by invoking the C compiler
-(path name held in @$(CC)@), passing to it the options @$(CC_OPTS)@ and the rule's
-dependent
-file of the rule @$<@ (@Foo.c@ in this case), and putting the result in
-the rule's target @$@@@ (@Foo.o@ in this case).
-
-Every program is held in a @make@ variable defined in @mk/config.mk@ --- look in @mk/config.mk@ for
-the complete list. One important one is the Haskell compiler, which is called @$(HC)@.
-
-Every programs options are are held in a @make@ variables called @<prog>_OPTS@.
-the @<prog>_OPTS@ variables are defined in @mk/opts.mk@. Almost all of them are defined
-like this:
-\begin{verbatim}
- CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
-\end{verbatim}
-The four variables from which @CC_OPTS@ is built have the following meaning:
-\begin{description}
-\item[@SRC_CC_OPTS@:] options passed to all C compilations.
-\item[@WAY_<way>_CC_OPTS@:] options passed to C compilations for way @<way>@. For example,
-@WAY_mp_CC_OPTS@ gives options to pass to the C compiler when compiling way @mp@.
-The variable @WAY_CC_OPTS@ holds options to pass to the C compiler when compiling the standard way.
-(Section~\ref{sect_ways} dicusses multi-way compilation.)
-\item[@<module>_CC_OPTS@:] options to pass to the C compiler that are specific to module @<module>@.
-For example, @SMap_CC_OPTS@ gives the specific options to pass to the C compiler when compiling
-@SMap.c@.
-\item[@EXTRA_CC_OPTS@:] extra options to pass to all C compilations. This is intended for command
-line use, thus;
-\begin{verbatim}
- gmake libHS.a EXTRA_CC_OPTS="-v"
-\end{verbatim}
-\end{description}
-
-
-\subsection{The main @mk/target.mk@ file}
-\label{sect_targets}
-
-@target.mk@ contains canned rules for all the standard targets described in
-Section~\ref{sect_standard-targets}. It is complicated by the fact
-that you don't want all of these rules to be active in every @Makefile@.
-Rather than have a plethora of tiny files which you can include selectively,
-there is a single file, @target.mk@, which selectively includes rules
-based on whether you have defined certain variables in your @Makefile@.
-This section explains what rules you get, what variables control them, and
-what the rules do. Hopefully, you will also get enough of an idea of what is supposed
-to happen that you can read and understand any wierd special cases yourself.
-
-\begin{description}
-\item[@HS_PROG@.] If @HS_PROG@ is defined, you get rules with the
-following targets:
-\begin{description}
-\item[@HS_PROG@] itself. This rule links @$(OBJS)@ with the Haskell
-runtime system to get an executable called @$(HS_PROG)@.
-\item[@install@] installs @$(HS_PROG)@ in @$(bindir)@ with the execute bit set.
-\end{description}
-
-\item[@C_PROG@] is similar to @HS_PROG@, except that the link step
-links @$(C_OBJS)@ with the C runtime system.
-
-\item[@LIBRARY@] is similar to @HS_PROG@, except
-that it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@,
-and @install@ installs it in @$(libdir)@, with the execute bit not set.
-
-\item[@LIB_DATA@] ...
-\item[@LIB_EXEC@] ...
-
-\item[@HS_SRCS@, @C_SRCS@.] If @HS_SRCS@ is defined and non-empty, a rule for
-the target @depend@ is included, which generates dependency information for
-Haskell programs. Similarly for @C_SRCS@.
-\end{description}
-
-All of these rules are ``double-colon'' rules, thus
-\begin{verbatim}
- install :: $(HS_PROG)
- ...how to install it...
-\end{verbatim}
-GNU @make@ treats double-colon rules as separate entities. If there
-are several double-colon rules for the same target it takes each in turn
-and fires it if its dependencies say to do so. This means that you can,
-for example, define both @HS_PROG@ and @LIBRARY@, which will generate two
-rules for @install@. When you type @gmake install@ both rules will be fired,
-and both the program and the library will be installed, just as you wanted.
-
-\subsection{Recursion}
-\label{sect_subdirs}
-
-In leaf @Makefiles@ the variable @SUBDIRS@ is undefined. In non-leaf
-@Makefiles@, @SUBDIRS@ is set to the list of sub-directories that contain subordinate
-@Makefile@s. {\em It is up to you to set @SUBDIRS@ in the @Makefile@.}
-There is no automation here --- @SUBDIRS@ is too important automate.
-
-When @SUBDIRS@ is defined, @target.mk@ includes a rather neat rule for
-the standard targets (Section~\ref{sect_standard-targets}) that
-simply invokes @make@ recursively in each of the sub-directories.
-
-{\em These recursive invocations are guaranteed to occur in the order in
-which the list of directories is specified in @SUBDIRS@.} This guarantee can
-be important. For example, when you say @gmake boot@ it can be important
-that the recursive invocation of @make boot@ is done in one sub-directory (the include
-files, say) before another (the source files).
-Generally, put the most independent sub-directory first, and the most dependent
-last.
-
-\subsection{Way management}
-\label{sect_ways}
-
-We sometimes want to build essentially the same system in several different
-``ways''. For example, we want to build @ghc@'s @Prelude@ libraries with
-and without profiling, with and without concurrency, and so on, so that
-there is an appropriately-built library archive to link with when the user compiles
-his program.
-It would be possible to have a completely separate build tree for each such ``way'',
-but it would be horribly bureaucratic, especially since often only parts of the
-build tree need to be constructed in multiple ways.
-
-Instead, the @template.mk@ contains some clever magic to allow you to build
-several versions of a system; and to control locally how many versions are built
-and how they differ. This section explains the magic.
-
-The files for a particular way are distinguished by munging the suffix.
-The ``normal way'' is always built, and its files have the standard suffices
-@.o@, @.hi@, and so on. In addition, you can build one or more extra ways,
-each distinguished by a {\em way tag}. The object files and interface files
-for one of these extra ways are distinguished by their suffix. For example,
-way @mp@ has files @.mp_o@ and @.mp_hi@. Library archives have their way
-tag the other side of the dot, for boring reasons; thus, @libHS_mp.a@.
-
-A @make@ variable called @way@ holds the current way tag. {\em @way@ is only ever
-set on the command line of a recursive invocation of @gmake@.} It is
-never set inside a @Makefile@. So it is a global constant for any one invocation
-of @gmake@. Two other @make@ variables, @way_@ and @_way@ are immediately derived
-from @$(way)@ and never altered. If @way@ is not set, then neither are @way_@
-and @_way@, and the invocation of @make@ will build the ``normal way''.
-If @way@ is set, then the other two variables are set in sympathy.
-For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
-and @_way@ is set to ``@_mp@''. These three variables are then used
-when constructing file names.
-
-So how does @make@ ever get recursively invoked with @way@ set? There
-are two ways in which this happens:
-\begin{itemize}
-\item For some (but not all) of the standard targets, when in a leaf sub-directory,
-@make@ is recursively invoked for each way tag in @$(WAYS)@. You set @WAYS@ to
-the list of way tags you want these targets built for. The mechanism here is
-very much like the recursive invocation of @make@ in sub-directories
-(Section~\ref{sect_subdirs}).
-
-It is up to you to set @WAYS@ in your @Makefile@; this is how you control
-what ways will get built.
-\item For a useful collection of targets (such as @libHS_mp.a@, @Foo.mp_o@)
-there is a rule which recursively invokes @make@ to make the specified
-target, setting the @way@ variable. So if you say @gmake Foo.mp_o@
-you should see a recursive invocation @gmake Foo.mp_o way=mp@,
-and {\em in this recursive invocation the pattern rule for compiling a Haskell
-file into a @.o@ file will match}. The key pattern rules (in @suffix.mk@)
-look like this:
-\begin{verbatim}
- %.$(way_)o : %.lhs
- $(HC) $(HC_OPTS) $< -o $@
-\end{verbatim}
-Neat, eh?
-\end{itemize}
-
-
-\subsection{When the canned rule isn't right}
-
-Sometimes the canned rule just doesn't do the right thing. For example, in
-the @nofib@ suite we want the link step to print out timing information.
-The thing to do here is {\em not} to define @HS_PROG@ or @C_PROG@, and instead
-define a special purpose rule in your own @Makefile@.
-By using different variable names you will avoid the canned rules being included,
-and conflicting with yours.
-
-
-%************************************************************************
-%* *
-\section[booting-from-C]{Booting/porting from C (\tr{.hc}) files}
-\index{building GHC from .hc files}
-\index{booting GHC from .hc files}
-%* *
-%************************************************************************
-
-This section is for people trying to get GHC going by using the
-supplied intermediate C (\tr{.hc}) files. This would probably be
-because no binaries have been provided, or because the machine
-is not ``fully supported.''
-
-The intermediate C files are normally made available together with a
-source release, please check the announce message for exact directions
-of where to find them. If we've haven't made them available or you
-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
-\sectionref{building-from-source} for setting up a build tree and
-configuring it. The only extra thing to remember when booting from
-\tr{.hc} files is to add the following line to the \tr{build.mk}
-file:
-
-\begin{verbatim}
-GhcWithHscBuiltViaC=YES
-\end{verbatim}
-
-and proceed with doing a \tr{make boot} followed by a \tr{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.)
-
-
-%************************************************************************
-%* *
-\section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
-\index{problems, building}
-\index{pitfalls, in building}
-\index{building pitfalls}
-%* *
-%************************************************************************
-
-WARNINGS about pitfalls and known ``problems'':
-
-\begin{enumerate}
-%------------------------------------------------------------------------
-\item
-One difficulty that comes up from time to time is running out of space
-in \tr{/tmp}. (It is impossible for the configuration stuff to
-compensate for the vagaries of different sysadmin approaches re temp
-space.)
-
-The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or
-even \tr{setenv TMPDIR .} (or the equivalent incantation with the
-shell of your choice).
-
-The best way around it is to say
-\begin{verbatim}
-export TMPDIR=<dir>
-\end{verbatim}
-in your @build.mk@ file.
-Then GHC and the other @fptools@ programs will use the appropriate directory
-in all cases.
-
-%------------------------------------------------------------------------
-\item
-In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and
-even in \tr{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 incompatible pointer type'' out of GCC. Harmless.
-
-%------------------------------------------------------------------------
-\item
-Similarly, \tr{ar}chiving warning messages like the following are not
-a problem:
-\begin{verbatim}
-ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
-ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
-...
-\end{verbatim}
-
-%------------------------------------------------------------------------
-\item
-Also harmless are some specialisation messages that you may see when
-compiling GHC; e.g.:
-\begin{verbatim}
-SPECIALISATION MESSAGES (Desirable):
-*** INSTANCES
-{-# SPECIALIZE instance Eq [Class] #-}
-{-# SPECIALIZE instance Eq (Class, [Class]) #-}
-{-# SPECIALIZE instance Outputable [ClassOp] #-}
-{-# SPECIALIZE instance Outputable [Id] #-}
-\end{verbatim}
-
-%------------------------------------------------------------------------
-\item
-In compiling the compiler proper (in \tr{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 \tr{-H} flag to the @<module>_HC_OPTS@
-@make@ variable in the appropriate @Makefile@;
-(2)~try again: \tr{gmake}.
-(Section~\ref{sect_suffix}.)
-
-Alternatively, just cut to the chase scene:
-\begin{verbatim}
-% cd ghc/compiler
-% make EXTRA_HC_OPTS=-H32m # or some nice big number
-\end{verbatim}
-
-%------------------------------------------------------------------------
-\item
-Not too long into the build process, you may get a huge complaint
-of the form:
-\begin{verbatim}
-Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
-\end{verbatim}
-This indicates that your \tr{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 lots of things from \tr{/usr/include/math.h}, then your GCC
-was mis-installed. \tr{fixincludes} wasn't run when it should've
-been.
-
-As \tr{fixincludes} is now automagically run as part of GCC
-installation, this bug also suggests that you have an old GCC.
-
-
-%------------------------------------------------------------------------
-\item
-You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
-\begin{verbatim}
-% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
-% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
-? ranlib $i
-? # or, on some machines: ar s $i
-? end
-\end{verbatim}
-We'd be interested to know if this is still necessary.
-
-%------------------------------------------------------------------------
-\item
-If you end up making documents that involve (La)TeX and/or \tr{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 \tr{make -n whatever.dvi} to see the intended commands,
-then try to muddle through, doing them by hand.
-
-%------------------------------------------------------------------------
-\item
-GHC's sources go through \tr{cpp}
-before being compiled, and \tr{cpp} varies a bit from one Unix to another.
-One particular gotcha is macro calls like this:
-\begin{verbatim}
- SLIT("Hello, world")
-\end{verbatim}
-Some \tr{cpp}s treat the comma inside the string as separating two macro arguments,
-so you get
-\begin{verbatim}
- :731: macro `SLIT' used with too many (2) args
-\end{verbatim}
-Alas, \tr{cpp} doesn't tell you the offending file!
-
-Workaround: don't put wierd things in string args to \tr{cpp} macros.
-\end{enumerate}
-
-\begin{onlystandalone}
-\printindex
-\end{document}
-\end{onlystandalone}
-
--- /dev/null
+<!doctype linuxdoc system>
+<article>
+
+<title>Building and Installing the Glasgow Functional Programming Tools Suite
+Version 3.00
+<author>The GHC Team,
+Department of Computing Science,
+University of Glasgow,
+Glasgow, Scotland,
+G12 8QQ.
+
+Email: @glasgow-haskell-{users,bugs}@@dcs.gla.ac.uk@
+<date>November 1997</date>
+
+<abstract>
+
+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>
+
+<sect>Getting the Glasgow @fptools@ suite
+<label id="sec:getting">
+<p>
+
+Building the Glasgow tools <em/can/ be complicated, mostly because
+there are so many permutations of what/why/how, e.g., ``Build Happy
+with HBC, everything else with GHC, leave out profiling, and test it
+all on the `real' NoFib programs.'' Yeeps!
+
+Happily, such complications don't apply to most people. A few common
+``strategies'' serve most purposes. Pick one and proceed
+as suggested:
+
+<descrip>
+
+<tag><idx>Binary distribution</idx>.</tag>
+ If your only purpose is to install some of the @fptools@ suite
+then the easiest thing to do is to get a binary distribution. In the
+binary distribution everything is pre-compiled for your particular
+machine architecture and operating system, so all you should have to
+do is install the binaries and libraries in suitable places. Section
+<ref id="sec:installing-bin-distrib" name="Installing a Binary
+Distribution"> describes how to do this.
+
+A binary distribution may not work for you for two reasons. First, we
+may not have built the suite for the particular architecture/OS
+platform you want. That may be due to lack of time and energy (in
+which case you can get a source distribution and build from it; see
+below). Alternatively, it may be because we haven't yet ported the
+suite to your architecture, in which case you are considerably worse
+off.
+
+The second reason a binary distribution may not be what you want is
+if you want to read or modify the souce code.
+
+<tag><idx>Source distribution</idx>.</tag> You have a supported
+platform, but (a)~you like the warm fuzzy feeling of compiling things
+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.
+
+We make source distributions more frequently than binary
+distributions; a release that comes with pre-compiled binaries
+is considered a major release, i.e., a release that we have some
+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.
+
+<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
+have a working GHC? Then you have no choice but to ``bootstrap'' up
+from the intermediate C (@.hc@) files that we provide. Building GHC
+on an unsupported platform falls into this category. Please see
+Section <ref id="sec:booting-from-C" name="Booting From C">.
+
+Once you have built GHC, you can build the other Glasgow tools with
+it.
+
+In theory, you can (could?) build GHC with another Haskell compiler
+(e.g., HBC). We haven't tried to do this for ages and it almost
+certainly doesn't work any more (for tedious reasons).
+
+<tag/The CVS repository./
+
+We make source distributions slightly more often than binary
+distributions; but still infrequently. If you want more up-to-the
+minute (but less tested) source code then you need to get access to
+our CVS repository.
+
+All the @fptools@ source code is held in a CVS repository. CVS is a
+pretty good source-code control system, and best of all it works over
+the network.
+
+The repository holds source code only. It holds no mechanically
+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!
+</descrip>
+
+If you are going to do any building from sources (either from a source
+distribution or the CVS repository) then you need to read all of this
+manual in detail.
+
+<sect>Things to check before you start typing
+<p>
+
+Here's a list of things to check before you get started.
+<enum>
+<item>
+<idx>Disk space needed</idx>: About 30MB (five hamburgers' worth) of disk space
+for the most basic binary distribution of GHC; more for some
+platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
+Haskell libraries) might take you to 8--10 hamburgers.
+
+You'll need over 100MB (say, 20 hamburgers' worth) if you need to
+build the basic stuff from scratch.
+
+
+All of the above are <em/estimates/ of disk-space needs.(I don't yet
+know the disk requirements for the non-GHC tools).
+
+<item>
+Use an appropriate machine, compilers, and things.
+
+SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
+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.
+
+<item> Be sure that the ``pre-supposed'' utilities are installed.
+Section <ref id="sec:pre-supposed" name="Installing Pre-Supposed
+Utilities"> elaborates.
+
+<item> If you have any problem when building or installing the Glasgow
+tools, please check the ``known pitfalls'' (Section <ref
+id="sec:build-pitfalls" name="Building Pitfalls">). Also check the
+known bugs page: <url
+url="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html">.
+<nidx/known bugs/
+<nidx/bugs, known/
+
+If you feel there is still some shortcoming in our procedure or
+instructions, please report it.
+
+For GHC, please see the bug-reporting section of the User's guide
+(separate document), to maximise the usefulness of your report.
+<nidx/bugs, reporting/
+
+If in doubt, please send a message to @glasgow-haskell-bugs@@dcs.gla.ac.uk@.
+<nidx/bugs, mailing list/
+</enum>
+
+
+<sect>What machines the Glasgow tools run on
+<label id="sec:port-info">
+<p>
+<nidx>ports, GHC</nidx>
+<nidx>GHC ports</nidx>
+<nidx>supported platforms</nidx>
+<nidx>platforms, supported</nidx>
+
+The main question is whether or not the Haskell compiler (GHC) runs on
+your platform.
+
+A ``platform'' is a architecture/manufacturer/operating-system
+combination, such as @sparc-sun-solaris2@. Other common ones are
+@alpha-dec-osf2@, @hppa1.1-hp-hpux9@, @i386-unknown-linux@,
+@i386-unknown-solaris2@, @i386-unknown-freebsd@,
+@i386-unknown-cygwin32@, @m68k-sun-sunos4@, @mips-sgi-irix5@,
+@sparc-sun-sunos4@, @sparc-sun-solaris2@, @powerpc-ibm-aix@.
+
+Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
+work on all machines for which basic Haskell compiling is supported.
+
+Some libraries may only work on a limited number of platforms; for
+example, a sockets library is of no use unless the operating system
+supports the underlying BSDisms.
+
+<sect1>What platforms the Haskell compiler (GHC) runs on
+<p>
+<nidx>fully-supported platforms</nidx>
+<nidx>native-code generator</nidx>
+<nidx>registerised ports</nidx>
+<nidx>unregisterised ports</nidx>
+
+The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
+generator; (b)~next best is a ``registerised''
+port; (c)~the bare minimum is an ``unregisterised'' port.
+(``Unregisterised'' is so terrible that we won't say more about it).
+
+We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and
+Linux, and DEC~Alphas running OSF/1~V2.0, so those are the
+``fully-supported'' platforms, unsurprisingly. All have native-code
+generators, for quicker compilations. The native-code generator for
+iX86 platforms (e.g., Linux ELF) is <em/nearly/ working; but is not
+turned on by default.
+
+Here's everything that's known about GHC ports. We identify platforms
+by their ``canonical'' CPU/Manufacturer/OS triple.
+
+Note that some ports are fussy about which GCC version you use; or
+require GAS; or ...
+
+<descrip>
+<tag/alpha-dec-osf1:/
+<nidx>alpha-dec-osf1: fully supported</nidx>
+
+(We have OSF/1 V3.0.) Fully supported, including native-code
+generator. We recommend GCC 2.6.x or later.
+
+<tag/sparc-sun-sunos4:/
+<nidx>sparc-sun-sunos4: fully supported</nidx>
+
+Fully supported, including native-code generator.
+
+<tag/sparc-sun-solaris2:/
+<nidx>sparc-sun-solaris2: fully supported</nidx>
+
+Fully supported, including native-code generator. A couple of quirks,
+though: (a)~the profiling libraries are bizarrely huge when compiled
+with object splitting; (b)~the default @xargs@<ncdx/xargs/ program is
+atrociously bad for building GHC libraries (see Section <ref
+id="sec:pre-supposed" name="Installing Pre-Supposed Utilities"> for
+details).
+
+<tag/HP-PA box running HP/UX 9.x:/
+<nidx>hppa1.1-hp-hpux: registerised port</nidx>
+
+Works registerised. No native-code generator. For GCC, you're best
+off with one of the Utah releases of GCC~2.6.3 (`u3' or later), from
+@jaguar.cs.utah.edu@. We think a straight GCC 2.7.x works,
+too.
+
+Concurrent/Parallel Haskell probably don't work (yet).
+<nidx>hppa1.1-hp-hpux: concurrent---no</nidx>
+<nidx>hppa1.1-hp-hpux: parallel---no</nidx>
+
+<tag/i386-*-linux (PCs running Linux---ELF format):/
+<nidx>i386-*-linux: registerised port</nidx>
+
+GHC works registerised. You <em/must/ have GCC 2.7.x or later. The
+iX86 native-code generator is <em/nearly/ there, but it isn't turned
+on by default.
+
+Profiling works, and Concurrent Haskell works.
+<nidx>i386-*-linux: profiling---yes</nidx>
+<nidx>i386-*-linux: concurrent---yes</nidx>
+Parallel Haskell probably works.
+<nidx>i386-*-linux: parallel---maybe</nidx>
+
+On old Linux a.out systems: should be the same.
+<nidx>i386-*-linuxaout: registerised port</nidx>
+
+<tag>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and
+NetBSD/OpenBSD using FreeBSD emulation):</tag>
+<nidx>i386-*-freebsd:registerised port</nidx>
+
+GHC works registerised. Supports same set of bundles as the above.
+
+<nidx>i386-*-freebsd: profiling---yes</nidx>
+<nidx>i386-*-freebsd: concurrent---yes</nidx>
+<nidx>i386-*-freebsd: parallel---maybe</nidx>
+
+<tag/i386-unknown-cygwin32:/
+<nidx>i386-unknown-cygwin32: fully supported</nidx>
+
+Fully supported under Win95/NT, including a native code
+generator. Requires the @cygwin32@ compatibility library and a
+healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.)
+Profiling works, so does Concurrent Haskell.
+
+<nidx>i386-*-cygwin32: profiling---yes</nidx>
+<nidx>i386-*-cygwin32: concurrent---yes</nidx>
+
+<tag/mips-sgi-irix5:/
+<nidx>mips-sgi-irix5: registerised port</nidx>
+
+GHC works registerised (no native-code generator). I suspect any
+GCC~2.6.x (or later) is OK. The GCC that I used was built with
+@--with-gnu-as@; turns out that is important!
+
+Concurrent/Parallel Haskell probably don't work (yet).
+Profiling might work, but it is untested.
+<nidx>mips-sgi-irix5: concurrent---no</nidx>
+<nidx>mips-sgi-irix5: parallel---no</nidx>
+<nidx>mips-sgi-irix5: profiling---maybe</nidx>
+
+<tag/mips-sgi-irix6:/
+<nidx>mips-sgi-irix6: registerised port</nidx>
+
+Thanks to the fine efforts of Tomasz Cholewo <htmlurl
+url="mailto:tjchol01@@mecca.spd.louisville.edu"
+name="<tjchol01@@mecca.spd.louisville.edu>">, GHC works registerised
+(no native code generator) under IRIX 6.2 and 6.3. Depends on having
+specially tweaked version of gcc-2.7.2 around, which can be downloaded
+from <url url="http://mecca.spd.louisville.edu/~tjchol01/software/">.
+
+Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
+<nidx>mips-sgi-irix6: concurrent---maybe</nidx>
+<nidx>mips-sgi-irix6: parallel---maybe</nidx>
+<nidx>mips-sgi-irix6: profiling---yes</nidx>
+
+<tag/powerpc-ibm-aix:/
+<nidx>powerpc-ibm-aix: registerised port</nidx>
+GHC works registerised (no native-code generator..yet).
+I suspect 2.7.x is what you need together with this.
+
+Concurrent/Parallel Haskell probably don't work (yet).
+Profiling might work, but it is untested.
+<nidx>mips-sgi-irix5: concurrent---no</nidx>
+<nidx>mips-sgi-irix5: parallel---no</nidx>
+<nidx>mips-sgi-irix5: profiling---maybe</nidx>
+
+<tag/m68k-apple-macos7 (Mac, using MPW):/
+<nidx>m68k-apple-macos7: historically ported</nidx>
+Once upon a time, David Wright in Tasmania has actually
+gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
+You may be able to get Thomson's from here. (Not sure that it will
+excite you to death, but...)
+
+No particularly recent GHC is known to work on a Mac.
+
+<tag/m68k-next-nextstep3:/
+<nidx>m68k-next-nextstep3: historically ported</nidx>
+Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29.
+There's probably a little bit-rot since then, but otherwise it should
+still be fine.
+
+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.
+
+Concurrent/Parallel Haskell probably don't work (yet).
+<nidx>m68k-sun-sunos4: concurrent---no</nidx>
+<nidx>m68k-sun-sunos4: parallel---no</nidx>
+</descrip>
+
+<sect1>What machines the other tools run on
+<p>
+
+Unless you hear otherwise, the other tools work if GHC works.
+
+Haggis requires Concurrent Haskell to work.
+<nidx>Haggis, Concurrent Haskell</nidx>
+
+
+<sect>Installing from binary distributions
+<p>
+<label id="sec:installing-bin-distrib">
+<nidx>binary installations</nidx>
+<nidx>installation, of binaries</nidx>
+
+Installing from binary distributions is easiest, and recommended!
+(Why binaries? Because GHC is a Haskell compiler written in Haskell,
+so you've got to ``bootstrap'' it, somehow. We provide
+machine-generated C-files-from-Haskell for this purpose, but it's
+really quite a pain to use them. If you must build GHC from its
+sources, using a binary-distributed GHC to do so is a sensible way to
+proceed. For the other @fptools@ programs, many are written in Haskell,
+so binary distributions allow you to install them without having a Haskell compiler.)
+
+
+<sect1>Bundle structure<p>
+<nidx>bundles of binary stuff</nidx>
+
+Binary distributions come in ``bundles,'' one bundle per file called
+@<bundle>-<platform>.tar.gz@. (See Section <ref
+id="sec:port-info" name="Porting Information"> for what a platform
+is.) Suppose that you untar a binary-distribution bundle, thus:
+
+<tscreen><verb>
+ % cd /your/scratch/space
+ % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
+</verb></tscreen>
+
+Then you should find a single directory, @fptools@, with the following
+structure:
+
+<nidx>binary distribution, layout</nidx>
+<nidx>directory layout (binary distributions)</nidx>
+<descrip>
+
+<tag>@Makefile.in@</tag> the raw material from which the @Makefile@
+will be made (Section <ref id="sec:install" name="Installation">).
+
+<tag>@configure@</tag> the configuration script (Section <ref
+id="sec:install" name="Installing">).
+
+<tag>@README@</tag> Contains this file summary.
+
+<tag>@INSTALL@</tag> Contains this description of how to install
+the bundle.
+
+<tag>@ANNOUNCE@</tag> The announcement message for the bundle.
+
+<tag>@NEWS@</tag> release notes for the bundle -- a longer version
+of @ANNOUNCE@. For GHC, the release notes are contained in the User
+Guide and this file isn't present.
+
+<tag>@bin/<platform>@</tag> contains platform-specific executable
+files to be invoked directly by the user. These are the files that
+must end up in your path.
+
+<tag>@lib/<platform>/@</tag> contains platform-specific support
+files for the installation. Typically there is a subdirectory for
+each @fptools@ project, whose name is the name of the project with its
+version number. For example, for GHC there would be a sub-directory
+@ghc-x.xx@/ where @x.xx@ is the version number of GHC in the bundle.
+
+These sub-directories have the following general structure:
+
+<descrip>
+<tag>@libHS.a@ etc:</tag> supporting library archives.
+<tag>@ghc-iface.prl@ etc:</tag> support scripts.
+<tag>@import/@</tag> <idx>Interface files</idx> (@.hi@) for the prelude.
+<tag>@include/@</tag> A few C @#include@ files.
+</descrip>
+
+<tag>@share/@</tag> contains platform-independent support files
+for the installation. Again, there is a sub-directory for each
+@fptools@ project.
+
+<tag>@info/@</tag> contains Emacs info documentation files (one
+sub-directory per project).
+
+<tag>@html/@</tag> contains HTML documentation files (one
+sub-directory per project).
+
+<tag>@man/@</tag> contains Unix manual pages.
+
+</descrip>
+
+This structure is designed so that you can unpack multiple bundles
+(including ones from different releases or platforms) into a single
+@fptools@ directory<footnote>this doesn't work at the
+moment</footnote>:
+
+<tscreen><verb>
+ % cd /your/scratch/space
+ % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
+ % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -
+</verb></tscreen>
+
+When you do multiple unpacks like this, the top level @Makefile@,
+@README@, and @INSTALL@ get overwritten each time.
+That's fine -- they should be the same. Likewise, the
+@ANNOUNCE-<bundle>@ and @NEWS-<bundle>@
+files will be duplicated across multiple platforms, so they will be
+harmlessly overwritten when you do multiple unpacks. Finally, the
+@share/@ stuff will get harmlessly overwritten when you do
+multiple unpacks for one bundle on different platforms.
+
+<sect2>Installing<p>
+<label id="sec:install">
+
+OK, so let's assume that you have unpacked your chosen bundles into a
+scratch directory @fptools@. What next? Well, you will at least need
+to run the @configure@<ncdx/configure/ script by changing your
+directory to @fptools@ and typing @./configure@. That should convert
+@Makefile.in@ to @Makefile@.
+
+<nidx/installing in-place/
+<nidx/in-place installation/
+
+You can now either start using the tools <em/in-situ/ without going
+through any installation process, just type @make in-place@ to set the
+tools up for this. You'll also want to add the path which @make@ will
+now echo to your @PATH@ environment variable. This option is useful if
+you simply want to try out the package and/or you don't have the
+necessary priviledges (or inclination) to properly install the tools
+locally. Note that if you do decide to install the package `properly'
+at a later date, you have to go through the installation steps that
+follows.
+
+To install an @fptools@ package, you'll have to do the following:
+
+<enum>
+<item> Edit the @Makefile@ and check the settings of the following variables:
+
+<nidx/directories, installation/
+<nidx/installation directories/
+
+<descrip>
+<tag>@platform@</tag> the platform you are going to install for.
+
+<tag>@bindir@</tag> the directory in which to install user-invokable
+binaries.
+
+<tag>@libdir@</tag> the directory in which to install
+platform-dependent support files.
+
+<tag>@datadir@</tag> the directory in which to install
+platform-independent support files.
+
+<tag>@infodir@</tag> the directory in which to install Emacs info
+files.
+
+<tag>@htmldir@</tag> the directory in which to install HTML
+documentation.
+
+<tag>@dvidir@</tag> the directory in which to install DVI
+documentation.
+</descrip>
+
+The values for these variables can be set through invocation of the
+@configure@<ncdx/configure/ script that comes with the distribution,
+but doing an optical diff to see if the values match your expectations
+is always a Good Idea.
+
+<em>Instead of running @configure@, it is perfectly OK to copy
+@Makefile.in@ to @Makefile@ and set all these variables
+directly yourself. But do it right!</em>
+
+<item>Run @make install@. This <em/ should/ work with ordinary Unix
+@make@ -- no need for fancy stuff like GNU @make@.
+
+<item>@rehash@ (t?csh or zsh users), so your shell will see the new
+stuff in your bin directory.
+
+<item> Once done, test your ``installation'' as suggested in Section
+<ref id="sec:GHC-test" name="Testing GHC">. Be sure to use a @-v@
+option, so you can see exactly what pathnames it's using.
+
+If things don't work as expected, check the list of know pitfalls in
+Section <ref id="sec:build-pitfalls" name="Building Pitfalls">.
+</enum>
+
+<nidx/link, installed as ghc/
+When installing the user-invokable binaries, this installation
+procedure will install GHC as @ghc-x.xx@ where @x.xx@ is the version
+number of GHC. It will also make a link (in the binary installation
+directory) from @ghc@ to @ghc-x.xx@. If you install multiple versions
+of GHC then the last one ``wins'', and ``@ghc@'' will invoke the last
+one installed. You can change this manually if you want. But
+regardless, @ghc-x.xx@ should always invoke GHC version @x.xx@.
+
+<sect1>What bundles there are
+<p>
+
+<nidx/bundles, binary/
+There are plenty of ``non-basic'' GHC bundles. The files for them are
+called @ghc-x.xx-<bundle>-<platform>.tar.gz@, where
+the @<platform>@ is as above, and @<bundle>@ is one
+of these:
+
+<descrip>
+
+<tag>@prof@:</tag> Profiling with cost-centres. You probably want this.
+<nidx/profiling bundles/
+<nidx/bundles, profiling/
+
+<tag>@conc@:</tag> Concurrent Haskell features. You may want this.
+<nidx/concurrent bundles/
+<nidx/bundles, concurrent/
+
+<tag>@par@:</tag> Parallel Haskell features (sits on top of PVM).
+You'll want this if you're into that kind of thing.
+<nidx/parallel bundles/
+<nidx/bundles, parallel/
+
+<tag>@gran@:</tag> The ``GranSim'' parallel-Haskell simulator
+(hmm... mainly for implementors).
+<nidx/bundles, gransim/
+<nidx/gransim bundles/
+
+<tag>@ticky@:</tag> ``Ticky-ticky'' profiling; very detailed
+information about ``what happened when I ran this program''---really
+for implementors.
+<nidx/bundles, ticky-ticky/
+<nidx/ticky-ticky bundles/
+
+<tag>@prof-conc@:</tag> Cost-centre profiling for Concurrent Haskell.
+<nidx/bundles, profiled-concurrent/
+<nidx/profiled-concurrent bundles/
+
+<tag>@prof-ticky@:</tag> Ticky-ticky profiling for Concurrent Haskell.
+<nidx/bundles, profiled-ticky/
+<nidx/ticky-concurrent bundles/
+</descrip>
+
+One likely scenario is that you will grab <em/three/ binary
+bundles---basic, profiling, and concurrent. We don't usually make the
+rest, although you can build them yourself from a source distribution.
+
+<sect1>Testing that GHC seems to be working
+<label id="sec:GHC-test">
+<p>
+<nidx>testing a new GHC</nidx>
+
+The way to do this is, of course, to compile and run <em/this/ program
+(in a file @Main.hs@):
+
+<tscreen><verb>
+main = putStr "Hello, world!\n"
+</verb></tscreen>
+
+Compile the program, using the @-v@ (verbose) flag to verify that
+libraries, etc., are being found properly:
+<tscreen><verb>
+% ghc -v -o hello Main.hs
+</verb></tscreen>
+
+Now run it:
+<tscreen><verb>
+% ./hello
+Hello, world!
+</verb></tscreen>
+
+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.
+
+For more information on how to ``drive'' GHC, either do @ghc -help@ or
+consult the User's Guide (distributed in several pre-compiled formats
+with a binary distribution, or in source form in
+@ghc/docs/users_guide@ in a source distribution).
+
+<sect>Installing pre-supposed utilities
+<label id="sec:pre-supposed">
+<nidx>pre-supposed utilities</nidx>
+<nidx>utilities, pre-supposed</nidx>
+<p>
+
+Here are the gory details about some utility programs you may need;
+@perl@ and @gcc@ are the only important ones. (<idx/PVM/ is important
+if you're going for Parallel Haskell.) The <tt><cdx/configure/</tt>
+script will tell you if you are missing something.
+
+<descrip>
+<tag>Perl:</tag>
+<nidx>pre-supposed: Perl</nidx>
+<nidx>Perl, pre-supposed</nidx>
+<em/You have to have Perl to proceed!/ Perl is a language quite good
+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 should be put somewhere so that it can be invoked by the @#!@
+script-invoking mechanism. (I believe @/usr/bin/perl@ is preferred;
+we use @/usr/local/bin/perl@ at Glasgow.) The full pathname should
+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.
+
+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.
+
+<tag>@xargs@ on Solaris2:</tag>
+<nidx>xargs, presupposed (Solaris only)</nidx>
+<nidx>Solaris: alternative xargs</nidx>
+The GHC libraries are put together with something like:
+<tscreen><verb>
+find bunch-of-dirs -name '*.o' -print | xargs ar q ...
+</verb></tscreen>
+Unfortunately the Solaris @xargs@ (the shell-script equivalent
+of @map@) only ``bites off'' the @.o@ files a few at a
+time---with near-infinite rebuilding of the symbol table in
+the @.a@ file.
+
+The best solution is to install a sane @xargs@ from the GNU
+findutils distribution. You can unpack, build, and install the GNU
+version in the time the Solaris @xargs@ mangles just one GHC
+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@.
+
+<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>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.
+
+<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>
+
+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>
+
+
+
+<sect>Building from source
+<label id="sec:building-from-source">
+<nidx>Building from source</nidx>
+<nidx>Source, building from</nidx>
+<p>
+
+You've been rash enough to want to build some of
+the Glasgow Functional Programming tools (GHC, Happy,
+nofib, etc) from source. You've slurped the source,
+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!
+
+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">
+<p>
+
+The source code is held in your <em/source tree/.
+The root directory of your source tree <em/must/
+contain the following directories and files:
+
+<itemize>
+<item> @Makefile@: the root Makefile.
+<item> @mk/@: the directory that contains the
+main Makefile code, shared by all the
+@fptools@ software.
+<item> @configure.in@, @config.sub@, @config.guess@:
+these files support the configuration process.
+<item> @install-sh@.
+</itemize>
+
+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.
+
+The important thing to remember is that even if you want only one
+project (@happy@, say), you must have a source tree whose root
+directory contains @Makefile@, @mk/@, @configure.in@, and the
+project(s) you want (@happy/@ in this case). You cannot get by with
+just the @happy/@ directory.
+
+<sect1>Build trees
+<nidx/build trees/
+<nidx/link trees, for building/
+<p>
+
+While you can build a system in the source tree, we don't recommend it.
+We often want to build multiple versions of our software
+for different architectures, or with different options (e.g. profiling).
+It's very desirable to share a single copy of the source code among
+all these builds.
+
+So for every source tree we have zero or more <em/build trees/. Each
+build tree is initially an exact copy of the source tree, except that
+each file is a symbolic link to the source file, rather than being a
+copy of the source file. There are ``standard'' Unix utilities that
+make such copies, so standard that they go by different names:
+@lndir@<ncdx/lndir/, @mkshadowdir@<ncdx/mkshadowdir/ are two (If you
+don't have either, the source distribution includes sources for the
+@X11@ @lndir@ --- check out @fptools/glafp-utils/lndir@ ).
+
+The build tree does not need to be anywhere near the source tree in
+the file system. Indeed, one advantage of separating the build tree
+from the source is that the build tree can be placed in a
+non-backed-up partition, saving your systems support people from
+backing up untold megabytes of easily-regenerated, and
+rapidly-changing, gubbins. The golden rule is that (with a single
+exception -- Section~<ref id="sec:build-config" name="Build
+Configuration"> <em/absolutely everything in the build tree is either
+a symbolic link to the source tree, or else is mechanically
+generated/. It should be perfectly OK for your build tree to vanish
+overnight; an hour or two compiling and you're on the road again.
+
+You need to be a bit careful, though, that any new files you create
+(if you do any development work) are in the source tree, not a build tree!
+
+Remember, that the source files in the build tree are <em/symbolic
+links/ to the files in the source tree. (The build tree soon
+accumulates lots of built files like @Foo.o@, as well.) You
+can <em/delete/ a source file from the build tree without affecting
+the source tree (though it's an odd thing to do). On the other hand,
+if you <em/edit/ a source file from the build tree, you'll edit the
+source-tree file directly. (You can set up Emacs so that if you edit
+a source file from the build tree, Emacs will silently create an
+edited copy of the source file in the build tree, leaving the source
+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
+@$(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
+@$(FPTOOLS_TOP)/ghc/mk/target.mk@.
+
+
+<sect1>Getting the build you want
+<label id="sec:build-config">
+<p>
+
+When you build @fptools@ you will be compiling code on a particular
+<em/host platform/, to run on a particular <em/target platform/
+(usually the same as the host platform)<nidx>platform</nidx>. The
+difficulty is that there are minor differences between different
+platforms; minor, but enough that the code needs to be a bit different
+for each. There are some big differences too: for a different
+architecture we need to build GHC with a different native-code
+generator.
+
+There are also knobs you can turn to control how the @fptools@
+software is built. For example, you might want to build GHC optimised
+(so that it runs fast) or unoptimised (so that you can compile it fast
+after you've modified it. Or, you might want to compile it with
+debugging on (so that extra consistency-checking code gets included)
+or off. And so on.
+
+All of this stuff is called the <em/configuration/ of your build.
+You set the configuration using an exciting three-step process.
+<descrip>
+
+<tag>Step 1: get ready for configuration.</tag> Change directory to
+@$(FPTOOLS_TOP)@ and issue the command @autoconf@<ncdx/autoconf/ (with
+no arguments). This GNU program converts @$(FPTOOLS_TOP)/configure.in@
+to a shell script called @$(FPTOOLS_TOP)/configure@.
+
+Both these steps are completely platform-independent; they just mean
+that the human-written file (@configure.in@) can be short, although
+the resulting shell script, @configure@, and @mk/config.h.in@, are
+long.
+
+In case you don't have @autoconf@ we distribute the results,
+@configure@, and @mk/config.h.in@, with the source distribution. They
+aren't kept in the repository, though.
+
+<tag>Step 2: system configuration.</tag>
+Runs the newly-created @configure@ script, thus:
+<tscreen><verb>
+ ./configure
+</verb></tscreen>
+@configure@'s mission is to scurry round your computer working out
+what architecture it has, what operating system, whether it has the
+@vfork@ system call, where @yacc@ is kept, whether @gcc@ is available,
+where various obscure @#include@ files are, whether it's a leap year,
+and what the systems manager had for lunch. It communicates these
+snippets of information in two ways:
+
+<itemize>
+
+<item> It translates @mk/config.mk.in@<ncdx/config.mk.in/ to
+@mk/config.mk@<ncdx/config.mk/, substituting for things between
+``@@@@@@@@}'' brackets. So, ``@@HaveGcc@@'' will be replaced by
+``@YES@'' or ``@NO@'' depending on what @configure@ finds.
+@mk/config.mk@ is included by every Makefile (directly or indirectly),
+so the configuration information is thereby communicated to all
+Makefiles.
+
+<item> It translates @mk/config.h.in@<ncdx/config.h.in/ to
+@mk/config.h@<ncdx/config.h/. The latter is @#include@d by various C
+programs, which can thereby make use of configuration information.
+
+</itemize>
+
+@configure@ caches the results of its run in @config.cache@. Quite
+often you don't want that; you're running @configure@ a second time
+because something has changed. In that case, simply delete
+@config.cache@.
+
+<tag>Step 3: build configuration.</tag>
+
+ Next, you say how this build of @fptools@ is to differ from the
+standard defaults by creating a new file @mk/build.mk@<ncdx/build.mk/
+<em/in the build tree/. This file is the one and only file you edit
+in the build tree, precisely because it says how this build differs
+from the source. (Just in case your build tree does die, you might
+want to keep a private directory of @build.mk@ files, and use a
+symbolic link in each build tree to point to the appropriate one.) So
+@mk/build.mk@ never exists in the source tree --- you create one in
+each build tree from the template. We'll discuss what to put in it
+shortly.
+
+</descrip>
+
+And that's it for configuration. Simple, eh?
+
+What do you put in your build-specific configuration file
+@mk/build.mk@? <em/For almost all purposes all you will do is put
+make variable definitions that override those in/ @mk/config.mk.in@.
+The whole point of @mk/config.mk.in@ --- and its derived counterpart
+@mk/config.mk@ --- is to define the build configuration. It is heavily
+commented, as you will see if you look at it. So generally, what you
+do is look at @mk/config.mk.in@, and add definitions in @mk/build.mk@
+that override any of the @config.mk@ definitions that you want to
+change. (The override occurs because the main boilerplate file,
+@mk/boilerplate.mk@<ncdx/boilerplate.mk/, includes @build.mk@ after
+@config.mk@.)
+
+For example, @config.mk.in@ contains the definition:
+
+<tscreen><verb>
+ ProjectsToBuild = glafp-utils literate ghc hslibs
+</verb></tscreen>
+
+The accompanying comment explains that this is the list of enabled
+projects; that is, if (after configuring) you type @gmake all@ in
+@FPTOOLS_TOP@ four specified projects will be made. If you want to
+add @green-card@, you can add this line to @build.mk@:
+
+<tscreen><verb>
+ ProjectsToBuild += green-card
+</verb></tscreen>
+
+or, if you prefer,
+
+<tscreen><verb>
+ ProjectsToBuild = glafp-utils literate ghc hslibs green-card
+</verb></tscreen>
+
+(GNU @make@ allows existing definitions to have new text appended
+using the ``@+=@'' operator, which is quite a convenient feature.)
+
+When reading @config.mk.in@, remember that anything between
+``@@...@@'' signs is going to be substituted by @configure@
+later. You <em/can/ override the resulting definition if you want,
+but you need to be a bit surer what you are doing. For example,
+there's a line that says:
+
+<tscreen><verb>
+ YACC = @YaccCmd@
+</verb></tscreen>
+
+This defines the Make variables @YACC@ to the pathname for a Yacc that
+@configure@ finds somewhere. If you have your own pet Yacc you want
+to use instead, that's fine. Just add this line to @mk/build.mk@:
+
+<tscreen><verb>
+ YACC = myyacc
+</verb></tscreen>
+
+You do not <em/have/ to have a @mk/build.mk@ file at all; if you
+don't, you'll get all the default settings from @mk/config.mk.in@.
+
+You can also use @build.mk@ to override anything that @configure@ got
+wrong. One place where this happens often is with the definition of
+@FPTOOLS_TOP_ABS@: this variable is supposed to be the canonical path
+to the top of your source tree, but if your system uses an automounter
+then the correct directory is hard to find automatically. If you find
+that @configure@ has got it wrong, just put the correct definition in
+@build.mk@.
+
+<sect1>The story so far
+<p>
+
+Let's summarise the steps you need to carry to get yourself
+a fully-configured build tree from scratch.
+
+<enum>
+
+<item> Get your source tree from somewhere (CVS repository or source
+distribution). Say you call the root directory @myfptools@ (it
+does not have to be called @fptools@). Make sure that you have
+the essential files (see Section~<ref id="sec:source-tree"
+name="Source Tree">).
+
+<item> Use @lndir@ or @mkshadowdir@ to create a build tree.
+<tscreen><verb>
+ cd myfptools
+ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
+</verb></tscreen>
+You probably want to give the build tree a name that
+suggests its main defining characteristic (in your mind at least),
+in case you later add others.
+
+<item> Change directory to the build tree. Everything is going
+to happen there now.
+<tscreen><verb>
+ cd /scratch/joe-bloggs/myfptools-sun4
+</verb></tscreen>
+<item> Prepare for system configuration:
+<tscreen><verb>
+ autoconf
+</verb></tscreen>
+(You can skip this step if you are starting from a source distribution,
+and you already have @configure@ and @mk/config.h.in@.)
+
+<item> Do system configuration:
+<tscreen><verb>
+ ./configure
+</verb></tscreen>
+
+<item> Create the file @mk/build.mk@,
+adding definitions for your desired configuration options.
+<tscreen><verb>
+ emacs mk/build.mk
+</verb></tscreen>
+</enum>
+You can make subsequent changes to @mk/build.mk@ as often
+as you like. You do not have to run any further configuration
+programs to make these changes take effect.
+In theory you should, however, say @gmake clean@, @gmake all@,
+because configuration option changes could affect anything --- but in practice you are likely to know what's affected.
+
+<sect1>Making things
+<p>
+
+At this point you have made yourself a fully-configured build tree,
+so you are ready to start building real things.
+
+The first thing you need to know is that
+<em/you must use GNU @make@, usually called @gmake@, not standard Unix @make@/.
+If you use standard Unix @make@ you will get all sorts of error messages
+(but no damage) because the @fptools@ @Makefiles@ use GNU @make@'s facilities
+extensively.
+
+<sect1>Standard Targets
+<label id="sec:standard-targets">
+<nidx/targets, standard makefile/
+<nidx/makefile targets/
+<p>
+
+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.
+Similarly, you can't convert a literate file to illiterate form until
+you have built the @literate@ tools. @boot@ takes care of these
+inter-directory dependencies.
+
+You should say @gmake boot@ right after configuring your build tree,
+but note that this is a one-off, i.e., there's no need to re-do
+@gmake boot@ if you should re-configure your build tree at a later
+stage (no harm caused if you do though).
+
+<tag>@all@:</tag> makes all the final target(s) for this Makefile.
+Depending on which directory you are in a ``final target'' may be an
+executable program, a library archive, a shell script, or a Postscript
+file. Typing @gmake@ alone is generally the same as typing @gmake
+all@.
+
+<tag>@install@:</tag> installs the things built by @all@. Where does it
+install them? That is specified by @mk/config.mk.in@; you can
+override it in @mk/build.mk@.
+
+<tag>@uninstall@:</tag> reverses the effect of @install@.
+
+<tag>@clean@:</tag> remove all easily-rebuilt files.
+
+<tag>@veryclean@:</tag> remove all files that can be rebuilt at all.
+There's a danger here that you may remove a file that needs a more
+obscure utility to rebuild it (especially if you started from a source
+distribution).
+
+<tag>@check@:</tag> run the test suite.
+
+</descrip>
+
+All of these standard targets automatically recurse into
+sub-directories. Certain other standard targets do not:
+
+<descrip>
+
+<tag>@configure@:</tag> is only available in the root directory
+@$(FPTOOLS_TOP)@; it has been discussed in Section~<ref
+id="sec:build-config" name="Build Configuration">.
+
+<tag>@depend@:</tag> make a @.depend@ file in each directory that needs
+it. This @.depend@ file contains mechanically-generated dependency
+information; for example, suppose a directory contains a Haskell
+source module @Foo.lhs@ which imports another module @Baz@.
+Then the generated @.depend@ file will contain the dependency:
+
+<tscreen><verb>
+ Foo.o : Baz.hi
+</verb></tscreen>
+
+which says that the object file @Foo.o@ depends on the interface file
+@Baz.hi@ generated by compiling module @Baz@. The @.depend@ file is
+automatically included by every Makefile.
+
+<tag>@binary-dist@:</tag> make a binary distribution. This is the
+target we use to build the binary distributions of GHC and Happy.
+
+<tag>@dist@:</tag> make a source distribution. You must be in a
+linked buid tree to make this target.
+</descrip>
+
+Most @Makefiles@ have targets other than these. You can find
+this out by looking in the @Makefile@ itself.
+
+<sect>The @Makefile@ architecture
+<nidx/makefile architecture/
+<p>
+
+@make@ is great if everything works --- you type @gmake install@ and,
+lo, the right things get compiled and installed in the right places.
+Our goal is to make this happen often, but somehow it often doesn't;
+instead some wierd error message eventually emerges from the bowels of
+a directory you didn't know existed.
+
+The purpose of this section is to give you a road-map to help you figure
+out what is going right and what is going wrong.
+
+<sect1>A small project
+<p>
+
+To get started, let us look at the @Makefile@ for an imaginary small
+@fptools@ project, @small@. Each project in @fptools@ has its own
+directory in @FPTOOLS_TOP@, so the @small@ project will have its own
+directory @FPOOLS_TOP/small/@. Inside the @small/@ directory there
+will be a @Makefile@, looking something like this:
+
+<nidx/Makefile, minimal/
+<tscreen><verb>
+ # Makefile for fptools project "small"
+
+ TOP = ..
+ include $(TOP)/mk/boilerplate.mk
+
+ SRCS = $(wildcard *.lhs) $(wildcard *.c)
+ HS_PROG = small
+
+ include $(TOP)/target.mk
+</verb></tscreen>
+
+This @Makefile@ has three sections:
+
+<enum>
+
+<item> The first section includes<footnote>One of the most important
+features of GNU @make@ that we use is the ability for a @Makefile@ to
+include another named file, very like @cpp@'s @#include@
+directive.</footnote> a file of ``boilerplate'' code from the level
+above (which in this case will be
+@FPTOOLS_TOP/mk/boilerplate.mk@<ncdx/boilerplate.mk/). As its name
+suggests, @boilerplate.mk@ consists of a large quantity of standard
+@Makefile@ code. We discuss this boilerplate in more detail in
+Section~<ref id="sec:boiler" name="Boilerplate">.
+<nidx/include, directive in Makefiles/
+<nidx/Makefile inclusion/
+
+Before the @include@ statement, you must define the @make@ variable
+@TOP@<ncdx/TOP/ to be the directory containing the @mk@ directory in
+which the @boilerplate.mk@ file is. It is <em/not/ OK to simply say
+
+<tscreen><verb>
+ include ../mk/boilerplate.mk # NO NO NO
+</verb></tscreen>
+
+Why? Because the @boilerplate.mk@ file needs to know where it is, so
+that it can, in turn, @include@ other files. (Unfortunately, when an
+@include@d file does an @include@, the filename is treated relative to
+the directory in which @gmake@ is being run, not the directory in
+which the @included@ sits.) In general, <em>every file @foo.mk@
+assumes that @$(TOP)/mk/foo.mk@ refers to itself.</em> It is up to the
+@Makefile@ doing the @include@ to ensure this is the case.
+
+Files intended for inclusion in other @Makefile@s are written to have
+the following property: <em/after @foo.mk@ is @include@d, it leaves
+@TOP@ containing the same value as it had just before the @include@
+statement/. In our example, this invariant guarantees that the
+@include@ for @target.mk@ will look in the same directory as that for
+@boilerplate.mk@.
+
+<item> The second section defines the following standard @make@
+variables: @SRCS@<ncdx/SRCS/ (the source files from which is to be
+built), and @HS_PROG@<ncdx/HS_PROG/ (the executable binary to be
+built). We will discuss in more detail what the ``standard
+variables'' are, and how they affect what happens, in Section~<ref
+id="sec:targets" name="Targets">.
+
+The definition for @SRCS@ uses the useful GNU @make@ construct
+@$(wildcard@~$pat$@)@<ncdx/wildcard/, which expands to a list of all
+the files matching the pattern @pat@ in the current directory. In
+this example, @SRCS@ is set to the list of all the @.lhs@ and @.c@
+files in the directory. (Let's suppose there is one of each,
+@Foo.lhs@ and @Baz.c@.)
+
+<item> The last section includes a second file of standard code,
+called @target.mk@<ncdx/target.mk/. It contains the rules that tell
+@gmake@ how to make the standard targets (Section~<ref
+id="sec:standard-targets" name="Standard Targets">). Why, you ask,
+can't this standard code be part of @boilerplate.mk@? Good question.
+We discuss the reason later, in Section~<ref id="sec:boiler-arch"
+name="Boilerplate Architecture">.
+
+You do not <em/have/ to @include@ the @target.mk@ file. Instead, you
+can write rules of your own for all the standard targets. Usually,
+though, you will find quite a big payoff from using the canned rules
+in @target.mk@; the price tag is that you have to understand what
+canned rules get enabled, and what they do (Section~<ref
+id="sec:targets" name="Targets">.
+
+</enum>
+
+In our example @Makefile@, most of the work is done by the two
+@include@d files. When you say @gmake all@, the following things
+happen:
+
+<itemize>
+
+<item> @gmake@ figures out that the object files are @Foo.o@ and
+@Baz.o@.
+
+<item> It uses a boilerplate pattern rule to compile @Foo.lhs@ to
+@Foo.o@ using a Haskell compiler. (Which one? That is set in the
+build configuration.)
+
+<item> It uses another standard pattern rule to compile @Baz.c@ to
+@Baz.o@, using a C compiler. (Ditto.)
+
+<item> It links the resulting @.o@ files together to make @small@,
+using the Haskell compiler to do the link step. (Why not use @ld@?
+Because the Haskell compiler knows what standard librarise to link in.
+How did @gmake@ know to use the Haskell compiler to do the link,
+rather than the C compiler? Because we set the variable @HS_PROG@
+rather than @C_PROG@.)
+
+</itemize>
+
+All @Makefile@s should follow the above three-section format.
+
+<sect1>A larger project
+<p>
+
+Larger projects are usually structured into a nummber of sub-directories,
+each of which has its own @Makefile@. (In very large projects, this
+sub-structure might be iterated recursively, though that is rare.)
+To give you the idea, here's part of the directory structure for
+the (rather large) @ghc@ project:
+
+<tscreen><verb>
+ $(FPTOOLS_TOP)/ghc/
+ Makefile
+
+ mk/
+ boilerplate.mk
+ rules.mk
+
+ docs/
+ Makefile
+ ...source files for documentation...
+
+ driver/
+ Makefile
+ ...source files for driver...
+
+ compiler/
+ Makefile
+ parser/...source files for parser...
+ renamer/...source files for renamer...
+ ...etc...
+</verb></tscreen>
+
+The sub-directories @docs@, @driver@, @compiler@, and so on, each
+contains a sub-component of @ghc@, and each has its own @Makefile@.
+There must also be a @Makefile@ in @$(FPTOOLS_TOP)/ghc@. It does most
+of its work by recursively invoking @gmake@ on the @Makefile@s in the
+sub-directories. We say that @ghc/Makefile@ is a <em/non-leaf
+@Makefile@/, because it does little except organise its children,
+while the @Makefile@s in the sub-directories are all <em/leaf
+@Makefile@s/. (In principle the sub-directories might themselves
+contain a non-leaf @Makefile@ and several sub-sub-directories, but
+that does not happen in @ghc@.)
+
+The @Makefile@ in @ghc/compiler@ is considered a leaf @Makefile@ even
+though the @ghc/compiler@ has sub-directories, because these sub-directories
+do not themselves have @Makefile@s in them. They are just used to structure
+the collection of modules that make up @ghc@, but all are managed by the
+single @Makefile@ in @ghc/compiler@.
+
+You will notice that @ghc/@ also contains a directory @ghc/mk/@. It
+contains @ghc@-specific @Makefile@ boilerplate code. More precisely:
+
+<itemize>
+
+<item> @ghc/mk/boilerplate.mk@ is included at the top of
+@ghc/Makefile@, and of all the leaf @Makefile@s in the
+sub-directories. It in turn @include@s the main boilerplate file
+@mk/boilerplate.mk@.
+
+
+<item> @ghc/mk/target.mk@ is @include@d at the bottom of
+@ghc/Makefile@, and of all the leaf @Makefiles@ in the
+sub-directories. It in turn @include@s the file @mk/target.mk@.
+
+</itemize>
+
+So these two files are the place to look for @ghc@-wide customisation
+of the standard boilerplate.
+
+<sect1>Boilerplate architecture
+<nidx/boilerplate architecture/
+<label id="sec:boiler-arch">
+<p>
+
+Every @Makefile@ includes a @boilerplate.mk@<ncdx/boilerplate.mk/ file
+at the top, and @target.mk@<ncdx/target.mk/ file at the bottom. In
+this section we discuss what is in these files, and why there have to
+be two of them. In general:
+
+<itemize>
+
+<item> @boilerplate.mk@ consists of:
+<itemize>
+<item> <em/Definitions of millions of @make@ variables/ that
+collectively specify the build configuration. Examples:
+<tt><cdx/HC_OPTS/</tt>, the options to feed to the Haskell compiler;
+<tt><cdx/NoFibSubDirs/</tt>, the sub-directories to enable within the
+@nofib@ project; <tt><cdx/GhcWithHc/</tt>, the name of the Haskell
+compiler to use when compiling @GHC@ in the @ghc@ project. <item>
+<em/Standard pattern rules/ that tell @gmake@ how to construct one
+file from another.
+</itemize>
+
+@boilerplate.mk@ needs to be @include@d at the <em/top/
+of each @Makefile@, so that the user can replace the
+boilerplate definitions or pattern rules by simply giving a new
+definition or pattern rule in the @Makefile@. @gmake@
+simply takes the last definition as the definitive one.
+
+Instead of <em/replacing/ boilerplate definitions, it is also quite
+common to <em/augment/ them. For example, a @Makefile@ might say:
+
+<tscreen><verb>
+ SRC_HC_OPTS += -O
+</verb></tscreen>
+
+thereby adding ``@-O@'' to the end of <tt><cdx/SRC_HC_OPTS/</tt>.
+
+<item> @target.mk@ contains @make@ rules for the standard
+targets described in Section~<ref id="sec:standard-targets"
+name="Standard Targets">. These rules are selectively included,
+depending on the setting of certain @make@ variables. These
+variables are usually set in the middle section of the
+@Makefile@ between the two @include@s.
+
+@target.mk@ must be included at the end (rather than being part of
+@boilerplate.mk@) for several tiresome reasons:
+
+<itemize>
+<item> @gmake@ commits target and dependency lists earlier than
+it should. For example, @target.mk@ has a rule that looks like
+this:
+
+<tscreen><verb>
+ $(HS_PROG) : $(OBJS)
+ $(HC) $(LD_OPTS) $< -o $@
+</verb></tscreen>
+
+If this rule was in @boilerplate.mk@ then @$(HS_PROG)@<ncdx/HS_PROG/
+and @$(OBJS)@<ncdx/OBJS/ would not have their final values at the
+moment @gmake@ encountered the rule. Alas, @gmake@ takes a snapshot
+of their current values, and wires that snapshot into the rule. (In
+contrast, the commands executed when the rule ``fires'' are only
+substituted at the moment of firing.) So, the rule must follow the
+definitions given in the @Makefile@ itself.
+
+<item> Unlike pattern rules, ordinary rules cannot be overriden or
+replaced by subsequent rules for the same target (at least not without an
+error message). Including ordinary rules in @boilerplate.mk@ would
+prevent the user from writing rules for specific targets in specific cases.
+
+<item> There are a couple of other reasons I've forgotten, but it doesn't
+matter too much.
+</itemize>
+</itemize>
+
+<sect1>The main @mk/boilerplate.mk@ file
+<label id="sec:boiler">
+<ncdx/boilerplate.mk/
+<p>
+
+If you look at @$(FPTOOLS_TOP)/mk/boilerplate.mk@ you will find
+that it consists of the following sections, each held in a separate
+file:
+
+<descrip>
+
+<tag><tt><cdx/config.mk/</tt></tag> is the build configuration file we
+discussed at length in Section~<ref id="sec:build-config" name="Build
+Configuration">.
+
+<tag><tt><cdx/paths.mk/</tt></tag> defines @make@ variables for
+pathnames and file lists. In particular, it gives definitions for:
+
+<descrip>
+<tag><tt><cdx/SRCS/</tt>:</tag> all source files in the current directory.
+<tag><tt><cdx/HS_SRCS/</tt>:</tag> all Haskell source files in the current directory.
+It is derived from @$(SRCS)@, so if you override @SRCS@ with a new value
+@HS_SRCS@ will follow suit.
+<tag><tt><cdx/C_SRCS/</tt>:</tag> similarly for C source files.
+<tag><tt><cdx/HS_OBJS/</tt>:</tag> the @.o@ files derived from @$(HS_SRCS)@.
+<tag><tt><cdx/C_OBJS/</tt>:</tag> similarly for @$(C_SRCS)@.
+<tag><tt><cdx/OBJS/</tt>:</tag> the concatenation of @$(HS_OBJS)@ and @$(C_OBJS)@.
+</descrip>
+
+Any or all of these definitions can easily be overriden by giving new
+definitions in your @Makefile@. For example, if there are things in
+the current directory that look like source files but aren't, then
+you'll need to set @SRCS@ manually in your @Makefile@. The other
+definitions will then work from this new definition.
+
+What, exactly, does @paths.mk@ consider a ``source file'' to be. It's
+based the file's suffix (e.g. @.hs@, @.lhs@, @.c@, @.lc@, etc), but
+this is the kind of detail that changes more rapidly, so rather than
+enumerate the source suffices here the best thing to do is to look in
+@paths.mk@.
+
+<tag><tt><cdx/opts.mk/</tt></tag> defines @make@ variables for option
+strings to pass to each program. For example, it defines
+<tt><cdx/HC_OPTS/</tt>, the option strings to pass to the Haskell
+compiler. See Section~<ref id="sec:suffix" name="Pattern Rules and
+Options">.
+
+<tag><tt><cdx/suffix.mk/</tt></tag> defines standard pattern rules --
+see Section~<ref id="sec:suffix" name="Pattern Rules and Options">.
+</descrip>
+
+Any of the variables and pattern rules defined by the boilerplate file
+can easily be overridden in any particular @Makefile@, because the
+boilerplace @include@ comes first. Definitions after this @include@
+directive simply override the default ones in @boilerplate.mk@.
+
+<sect1>Pattern rules and options
+<label id="sec:suffix">
+<nidx/Pattern rules/
+<p>
+
+The file @suffix.mk@<ncdx/suffix.mk/ defines standard <em/pattern
+rules/ that say how to build one kind of file from another, for
+example, how to build a @.o@ file from a @.c@ file. (GNU @make@'s
+<em/pattern rules/ are more powerful and easier to use than Unix
+@make@'s <em/suffix rules/.)
+
+Almost all the rules look something like this:
+
+<tscreen><verb>
+%.o : %.c
+ $(RM) $@
+ $(CC) $(CC_OPTS) -c $< -o $@
+</verb></tscreen>
+
+Here's how to understand the rule. It says that
+<em/something/@.o@ (say @Foo.o@) can be built from
+<em/something/@.c@ (@Foo.c@), by invoking the C compiler
+(path name held in @$(CC)@), passing to it the options
+@$(CC_OPTS)@ and the rule's dependent file of the rule
+@$<@ (@Foo.c@ in this case), and putting the result in
+the rule's target @$@@@ (@Foo.o@ in this case).
+
+Every program is held in a @make@ variable defined in
+@mk/config.mk@ --- look in @mk/config.mk@ for the
+complete list. One important one is the Haskell compiler, which is
+called @$(HC)@.
+
+Every programs options are are held in a @make@ variables called
+@<prog>_OPTS@. the @<prog>_OPTS@ variables are defined in
+@mk/opts.mk@. Almost all of them are defined like this:
+
+<tscreen><verb>
+ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
+</verb></tscreen>
+
+The four variables from which @CC_OPTS@ is built have the following meaning:
+
+<descrip>
+
+<tag><tt><cdx/SRC_CC_OPTS/</tt>:</tag> options passed to all C
+compilations.
+
+<tag>@WAY_<way>_CC_OPTS@:</tag> options passed to C
+compilations for way @<way>@. For example,
+@WAY_mp_CC_OPTS@ gives options to pass to the C compiler when
+compiling way @mp@. The variable @WAY_CC_OPTS@ holds
+options to pass to the C compiler when compiling the standard way.
+(Section~<ref id="sec:ways" name="Ways"> dicusses multi-way
+compilation.) <tag>@<module>_CC_OPTS@:</tag> options to
+pass to the C compiler that are specific to module @<module>@. For example, @SMap_CC_OPTS@ gives the specific options
+to pass to the C compiler when compiling @SMap.c@.
+
+<tag><tt><cdx/EXTRA_CC_OPTS/</tt>:</tag> extra options to pass to all
+C compilations. This is intended for command line use, thus;
+
+<tscreen><verb>
+ gmake libHS.a EXTRA_CC_OPTS="-v"
+</verb></tscreen>
+</descrip>
+
+<sect1>The main @mk/target.mk@ file
+<label id="sec:targets">
+<ncdx/target.mk/
+<p>
+
+@target.mk@ contains canned rules for all the standard targets
+described in Section~<ref id="sec:standard-targets" name="Standard
+Targets">. It is complicated by the fact that you don't want all of
+these rules to be active in every @Makefile@. Rather than have a
+plethora of tiny files which you can include selectively, there is a
+single file, @target.mk@, which selectively includes rules based on
+whether you have defined certain variables in your @Makefile@. This
+section explains what rules you get, what variables control them, and
+what the rules do. Hopefully, you will also get enough of an idea of
+what is supposed to happen that you can read and understand any wierd
+special cases yourself.
+
+<descrip>
+<tag><tt><cdx/HS_PROG/</tt>.</tag> If @HS_PROG@ is defined, you get
+rules with the following targets:
+<descrip>
+<tag><tt><cdx/HS_PROG/</tt></tag> itself. This rule links @$(OBJS)@
+with the Haskell runtime system to get an executable called
+@$(HS_PROG)@.
+<tag><tt><cdx/install/</tt></tag> installs @$(HS_PROG)@
+in @$(bindir)@ with the execute bit set.
+</descrip>
+
+<tag><tt><cdx/C_PROG/</tt></tag> is similar to @HS_PROG@, except that
+the link step links @$(C_OBJS)@ with the C runtime system.
+
+<tag><tt><cdx/LIBRARY/</tt></tag> is similar to @HS_PROG@, except that
+it links @$(LIB_OBJS)@ to make the library archive @$(LIBRARY)@, and
+@install@ installs it in @$(libdir)@, with the execute bit not set.
+
+<tag><tt><cdx/LIB_DATA/</tt></tag> ...
+<tag><tt><cdx/LIB_EXEC/</tt></tag> ...
+
+<tag><tt><cdx/HS_SRCS/</tt>, <tt><cdx/C_SRCS/</tt>.</tag> If @HS_SRCS@
+is defined and non-empty, a rule for the target @depend@ is included,
+which generates dependency information for Haskell programs.
+Similarly for @C_SRCS@.
+</descrip>
+
+All of these rules are ``double-colon'' rules, thus
+
+<tscreen><verb>
+ install :: $(HS_PROG)
+ ...how to install it...
+</verb></tscreen>
+
+GNU @make@ treats double-colon rules as separate entities. If there
+are several double-colon rules for the same target it takes each in
+turn and fires it if its dependencies say to do so. This means that
+you can, for example, define both @HS_PROG@ and @LIBRARY@, which will
+generate two rules for @install@. When you type @gmake install@ both
+rules will be fired, and both the program and the library will be
+installed, just as you wanted.
+
+<sect1>Recursion
+<label id="sec:subdirs">
+<nidx/recursion, in makefiles/
+<nidx/Makefile, recursing into subdirectories/
+<p>
+
+In leaf @Makefiles@ the variable @SUBDIRS@<ncdx/SUBDIRS/ is undefined.
+In non-leaf @Makefiles@, @SUBDIRS@ is set to the list of
+sub-directories that contain subordinate @Makefile@s. <em/It is up to
+you to set @SUBDIRS@ in the @Makefile@./ There is no automation here
+--- @SUBDIRS@ is too important automate.
+
+When @SUBDIRS@ is defined, @target.mk@ includes a rather
+neat rule for the standard targets (Section~<ref
+id="sec:standard-targets" name="Standard Targets"> that simply invokes
+@make@ recursively in each of the sub-directories.
+
+<em/These recursive invocations are guaranteed to occur in the order
+in which the list of directories is specified in @SUBDIRS@./ This
+guarantee can be important. For example, when you say @gmake boot@ it
+can be important that the recursive invocation of @make boot@ is done
+in one sub-directory (the include files, say) before another (the
+source files). Generally, put the most independent sub-directory
+first, and the most dependent last.
+
+<sect1>Way management
+<label id="sec:ways">
+<nidx/way management/
+<p>
+
+We sometimes want to build essentially the same system in several
+different ``ways''. For example, we want to build @ghc@'s @Prelude@
+libraries with and without profiling, with and without concurrency,
+and so on, so that there is an appropriately-built library archive to
+link with when the user compiles his program. It would be possible to
+have a completely separate build tree for each such ``way'', but it
+would be horribly bureaucratic, especially since often only parts of
+the build tree need to be constructed in multiple ways.
+
+Instead, the @target.mk@<ncdx/target.mk/ contains some clever magic to
+allow you to build several versions of a system; and to control
+locally how many versions are built and how they differ. This section
+explains the magic.
+
+The files for a particular way are distinguished by munging the
+suffix. The ``normal way'' is always built, and its files have the
+standard suffices @.o@, @.hi@, and so on. In addition, you can build
+one or more extra ways, each distinguished by a <em/way tag/. The
+object files and interface files for one of these extra ways are
+distinguished by their suffix. For example, way @mp@ has files
+@.mp_o@ and @.mp_hi@. Library archives have their way tag the other
+side of the dot, for boring reasons; thus, @libHS_mp.a@.
+
+A @make@ variable called @way@ holds the current way tag. <em/@way@
+is only ever set on the command line of a recursive invocation of
+@gmake@./ It is never set inside a @Makefile@. So it is a global
+constant for any one invocation of @gmake@. Two other @make@
+variables, @way_@ and @_way@ are immediately derived from @$(way)@ and
+never altered. If @way@ is not set, then neither are @way_@ and
+@_way@, and the invocation of @make@ will build the ``normal way''.
+If @way@ is set, then the other two variables are set in sympathy.
+For example, if @$(way)@ is ``@mp@'', then @way_@ is set to ``@mp_@''
+and @_way@ is set to ``@_mp@''. These three variables are then used
+when constructing file names.
+
+So how does @make@ ever get recursively invoked with @way@ set? There
+are two ways in which this happens:
+
+<itemize>
+
+<item> For some (but not all) of the standard targets, when in a leaf
+sub-directory, @make@ is recursively invoked for each way tag in
+@$(WAYS)@. You set @WAYS@ to the list of way tags you want these
+targets built for. The mechanism here is very much like the recursive
+invocation of @make@ in sub-directories (Section~<ref id="sec:subdirs"
+name="Subdirectories">).
+
+It is up to you to set @WAYS@ in your @Makefile@; this is how you
+control what ways will get built. <item> For a useful collection of
+targets (such as @libHS_mp.a@, @Foo.mp_o@) there is a rule which
+recursively invokes @make@ to make the specified target, setting the
+@way@ variable. So if you say @gmake Foo.mp_o@ you should see a
+recursive invocation @gmake Foo.mp_o way=mp@, and <em/in this
+recursive invocation the pattern rule for compiling a Haskell file
+into a @.o@ file will match/. The key pattern rules (in @suffix.mk@)
+look like this:
+
+<tscreen><verb>
+ %.$(way_)o : %.lhs
+ $(HC) $(HC_OPTS) $< -o $@
+</verb></tscreen>
+
+Neat, eh?
+</itemize>
+
+
+<sect1>When the canned rule isn't right
+<p>
+
+Sometimes the canned rule just doesn't do the right thing. For
+example, in the @nofib@ suite we want the link step to print out
+timing information. The thing to do here is <em/not/ to define
+@HS_PROG@ or @C_PROG@, and instead define a special purpose rule in
+your own @Makefile@. By using different variable names you will avoid
+the canned rules being included, and conflicting with yours.
+
+
+<sect>Booting/porting from C (@.hc@) files
+<label id="sec:booting-from-C">
+<nidx>building GHC from .hc files</nidx>
+<nidx>booting GHC from .hc files</nidx>
+<nidx>porting GHC</nidx>
+<p>
+
+This section is for people trying to get GHC going by using the
+supplied intermediate C (@.hc@) files. This would probably be because
+no binaries have been provided, or because the machine is not ``fully
+supported.''
+
+The intermediate C files are normally made available together with a
+source release, please check the announce message for exact directions
+of where to find them. If we've haven't made them available or you
+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:
+
+<tscreen><verb>
+GhcWithHscBuiltViaC=YES
+</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>
+<nidx>pitfalls, in building</nidx>
+<nidx>building pitfalls</nidx>
+<p>
+
+WARNINGS about pitfalls and known ``problems'':
+
+<enum>
+
+<item>
+One difficulty that comes up from time to time is running out of space
+in @/tmp@. (It is impossible for the configuration stuff to
+compensate for the vagaries of different sysadmin approaches re temp
+space.)
+<nidx/tmp, running out of space in/
+
+The quickest way around it is @setenv TMPDIR /usr/tmp@<ncdx/TMPDIR/ or
+even @setenv TMPDIR .@ (or the equivalent incantation with the shell
+of your choice).
+
+The best way around it is to say
+<tscreen><verb>
+export TMPDIR=<dir>
+</verb></tscreen>
+in your @build.mk@ file.
+Then GHC and the other @fptools@ programs will use the appropriate directory
+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.
+
+<item>
+When compiling via C, you'll sometimes get ``warning: assignment from
+incompatible pointer type'' out of GCC. Harmless.
+
+<item>
+Similarly, @ar@chiving warning messages like the following are not
+a problem:
+<tscreen><verb>
+ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
+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>
+
+
+<item>
+Not too long into the build process, you may get a huge complaint
+of the form:
+<tscreen><verb>
+Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
+</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
+lots of things from @/usr/include/math.h@, then your GCC was
+mis-installed. @fixincludes@ wasn't run when it should've been.
+
+As @fixincludes@ is now automagically run as part of GCC installation,
+this bug also suggests that you have an old GCC.
+
+
+<item>
+You <em/may/ need to re-@ranlib@<ncdx/ranlib/ your libraries (on Sun4s).
+
+<tscreen><verb>
+% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
+% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
+? ranlib $i
+? # or, on some machines: ar s $i
+? end
+</verb></tscreen>
+
+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:
+
+<tscreen><verb>
+ SLIT("Hello, world")
+</verb></tscreen>
+
+Some @cpp@s treat the comma inside the string as separating two macro
+arguments, so you get
+
+<tscreen><verb>
+ :731: macro `SLIT' used with too many (2) args
+</verb></tscreen>
+
+Alas, @cpp@ doesn't tell you the offending file!
+
+Workaround: don't put wierd things in string args to @cpp@ macros.
+</enum>
+
+</article>
projects / ghc-hetmet.git / commitdiff