[ghc-hetmet.git] / ghc / docs / install_guide / installing.lit

%
% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/install_guide/Attic/installing.lit,v 1.3 1996/06/30 16:45:00 partain Exp $
%
\begin{onlystandalone}
\documentstyle[11pt,literate]{article}
\begin{document}
\title{Installing the Glasgow Functional Programming Tools\\
Version~0.26}
\author{The AQUA Team (scribe: Will Partain)\\
Department of Computing Science\\
University of Glasgow\\
Glasgow, Scotland\\
G12 8QQ\\
\\
Email: glasgow-haskell-\{users,bugs\}-request\@dcs.glasgow.ac.uk}
\maketitle
\begin{rawlatex}
\tableofcontents
\end{rawlatex}
\clearpage
\end{onlystandalone}

%************************************************************************
%*                                                                      *
\section[install-intro]{Introduction}
%*                                                                      *
%************************************************************************

For most people, it should be easy to install one or more of the
Glasgow functional-programming tools (the `Glasgow tools'), most often
just the Glasgow Haskell compiler (GHC).  This document will guide you
through the installation process, and point out the known pitfalls.

Note: As of version~0.26, this document describes how to build {\em
all} of the Glasgow tools, not just the Haskell compiler.  The
\tr{configure} script, etc., has changed to cope with this wider
mandate; something to bear in mind...

%************************************************************************
%*                                                                      *
\subsection[install-strategy]{What to install?  Starting from what?}
%*                                                                      *
%************************************************************************

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[Install from binary ``bundles'':] You have one of the supported
platforms (e.g., Sun4 or DEC Alpha), and you just want a Haskell
compiler, and you don't want to do anything fancy...  This choice
is for you.  Proceed to
\sectionref{installing-bin-distrib}.  HIGHLY RECOMMENDED!

\item[Build some Glasgow tools using GHC itself:] 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.

In this case, you should install a binary distribution
(as described in \sectionref{installing-bin-distrib}),
then build GHC with it (as described in \sectionref{building-GHC}).

\item[Build GHC from intermediate C \tr{.hc} files:] You cannot get a
pre-built GHC, so 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.

\item[Build GHC with another Haskell compiler (e.g., HBC):] Not
recommended, but see \sectionref{building-with-HBC}.
\end{description}

%************************************************************************
%*                                                                      *
\subsection[port-info]{What machines the Glasgow tools, version~0.26, 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 machine.

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.

%************************************************************************
%*                                                                      *
\subsubsection{What machines 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'' Haskell programs are much bigger and slower,
but the port is much easier to get going.

With GHC~0.26, we add ``registerised'' support for some HP-PA, iX86,
and MIPS platforms.

We use Sun4s running SunOS~4.1.3 and DEC~Alphas running OSF/1~V2.0,
so those are the ``fully-supported'' platforms, unsurprisingly.  Both
have native-code generators, for quicker compilations.

Here's everything that's known about GHC ports, as of 0.26. We
identify platforms by their ``canonical GNU-style'' names.  We
identify

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}
GHC~0.26 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 don't know if straight GCC 2.7.x works or not.

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-*-linuxaout} (PCs running Linux---\tr{a.out} format):]
\index{i386-*-linuxaout: registerised port}
GHC~0.26 works registerised (no native-code generator).
You {\em must} have GCC 2.7.x or later.

Concurrent/Parallel Haskell probably don't work (yet).
\index{i386-*-linuxaout: concurrent---no}
\index{i386-*-linuxaout: parallel---no}
\index{i386-*-linuxaout: profiling---maybe}
Profiling might work, but it is untested.

%-------------------------------------------------------------------
\item[\tr{mips-sgi-irix5}:]
\index{mips-sgi-irix5: registerised port}
GHC~0.26 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}.

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.19.
There's probably a little bit-rot since then, but otherwise it should
still be fine.  Had a report that things were basically OK at 0.22.

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~0.26 works 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}

%************************************************************************
%*                                                                      *
\subsubsection{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}

%************************************************************************
%*                                                                      *
\subsection{Things to check before you start typing}
%*                                                                      *
%************************************************************************

\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.

I don't yet know the disk requirements for the non-GHC tools.

All of the above are {\em estimates} of disk-space needs.

\item
Use an appropriate machine, compilers, and things.

SPARC boxes and DEC Alphas running OSF/1 are fully supported.
\Sectionref{port-info} gives the full run-down on ports or lack
thereof.

\item
Be sure that the ``pre-supposed'' utilities are installed.

For GHC, you must have \tr{perl} to get anywhere at all.  If you're
going for Parallel Haskell, you'll need PVM, version 3.  You will
probably need a reasonably up-to-date GCC (GNU C compiler),
too---\sectionref{port-info} lists any specific requirements in this
regard.

If you are going to be making documents [unlikely], you'll need
\tr{makeindex} as well, and maybe \tr{tgrind} [unlikely].  If you edit
the one or two \tr{flex} files in GHC, you'll need \tr{flex}, too
[unlikely].

If you end up yacc'ing the Haskell parser [unlikely], Sun's standard
\tr{/bin/yacc} won't cut it.  Either the unbundled \tr{/usr/lang/yacc}
or \tr{bison} will do fine.  Berkeley yacc (\tr{byacc}) won't do.

\item
If you have any problem when building or installing the Glasgow tools,
please check the ``known pitfalls'' (\sectionref{build-pitfalls}).  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
\tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}.
\end{enumerate}

%************************************************************************
%*                                                                      *
\section[installing-bin-distrib]{Installing from binary distributions (the most common case)}
\index{binary installations}
\index{installation, of binaries}
%*                                                                      *
%************************************************************************

Installing from binary distributions is easiest, and recommended!

%************************************************************************
%*                                                                      *
\subsection[GHC-bin-distrib]{GHC from binary distributions}
\index{GHC installation, from binaries}
\index{installation, GHC from binaries}
%*                                                                      *
%************************************************************************

(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.)

Binary distributions come in ``bundles,''\index{bundles of binary stuff}
one bundle per \tr{.tar.gz} file.

A basic GHC ``bundle'' gives you the compiler and the standard,
sequential libraries.  The files are called
\tr{ghc-0.26-<platform>.tar.gz}, where \tr{<platform>} is one of:
alpha-dec-osf2, hppa1.1-hp-hpux9, i386-unknown-linuxaout,
% i386-unknown-solaris2,
m68k-sun-sunos4, mips-sgi-irix5,
sparc-sun-sunos4, sparc-sun-solaris2.

There are plenty of ``non-basic'' GHC bundles.  The files for them are
called \tr{ghc-0.26-<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.  Once you have them,
unpack them all together in the same place, thusly:

\begin{verbatim}
cd /put/them/in/here
gunzip < ghc-0.26-sparc-sun-sunos4.tar.gz      | tar xf -
gunzip < ghc-0.26-prof-sparc-sun-sunos4.tar.gz | tar xf -
gunzip < ghc-0.26-conc-sparc-sun-sunos4.tar.gz | tar xf -
\end{verbatim}

If you unpacked the files in a way that does {\em not} preserve
modification times (e.g., used the \tr{m} option to \tr{tar}---why on
earth you might do this, I cannot imagine), then please unpack them
again :-)  The timestamps on the files are (regrettably) important.

%To check that you have all the pre-supposed utilities, please see
%\sectionref{Pre-supposed}.

Here's what to do with the stuff in each directory, once unpacked.
% (If your binary distribution, doesn't look like this---don't despair!
% It may be a ``dumped-from-a-build'' distribution; please see
% \sectionref{dumped-from-build}.)

\begin{description}
%---------------------------------------------------------------------
\item[\tr{bin/<platform>} (sometimes just \tr{bin/}):]
Copy these executables so that they will be in users' PATHs.

%---------------------------------------------------------------------
\item[\tr{lib}:]
Move this directory, in toto, to wherever you want it to live.
It should still be called \tr{lib}.

%---------------------------------------------------------------------
\item[\tr{docs}:]
This is the full \tr{docs} tree.  Just follow the normal instructions,
in \sectionref{make-docs}.
\end{description}

Things you need to fiddle so the tools will spring to life:
\begin{enumerate}
\item
\tr{rehash} (csh users), so your shell will see the new stuff in your
bin directory.

\item
CHOICE \#1 (BETTER):
Edit your \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts:
(a)~Create a correct \tr{#!...perl} first line in each one. (Ask a
Unix-friendly person to help you, if you don't know what a
\tr{#!}-line is.)  (b)  Find the line that looks something like:
\begin{verbatim}
# $ENV{'GLASGOW_HASKELL_ROOT'} = '/some/absolute/path/name';
\end{verbatim}
Remote the comment symbol (\tr{#}) on the front, and change the
path name to be the right thing.

So, if your ``lib'' files are now in \tr{/home/myself/lib/ghc/...},
then you should set \tr{GLASGOW_HASKELL_ROOT} to \tr{/home/myself}.

\item
CHOICE \#2:
Set your \tr{GLASGOW_HASKELL_ROOT} environment variable, and
don't edit the \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts
at all.

It's better to edit the scripts; that way, it's once for all.

\item
You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
\begin{verbatim}
% cd <wherever-the-lib-files-are-now>/ghc/0.26/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}

\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, double-check your hand-edited path
names.  Things will go catastrophically wrong as long as they are
incorrect.
\end{enumerate}

%************************************************************************
%*                                                                      *
\subsection[non-GHC-bin-distrib]{Other tools from binary distributions}
%*                                                                      *
%************************************************************************

NOT DONE YET.

All of the above is for GHC bundles.  For other tools, the same
principles apply: get the binary bundles you want, then unpack them
all together in the same place.

%************************************************************************
%*                                                                      *
%\subsection[dumped-from-build]{Installing a ``dumped-from-build'' binary distribution (some platforms)}
%*                                                                      *
%************************************************************************
%#% 
%#% Sometimes, a binary distribution is taken directly from a GHC
%#% ``build.''  An example is the Solaris distribution.  You can tell from
%#% the layout of the files.
%#% 
%#% The setup required is nearly the same as a ``regular'' binary
%#% distribution; only some names are different.
%#% \begin{enumerate}
%#% \item
%#% Get the user-executable scripts into your PATH, either by copying it
%#% or by linking to it.  These are in:
%#% \begin{verbatim}
%#% <topdir>/ghc/driver/ghc
%#% <topdir>/ghc/utils/mkdependHS/mkdependHS
%#% <topdir>/ghc/utils/hstags/hstags
%#% \end{verbatim}
%#% 
%#% \item
%#% Set the \tr{GLASGOW_HASKELL_ROOT} environment variable for the three
%#% scripts above, in the manner outlined in the previous section.
%#% 
%#% \item
%#% Possibly re-\tr{ranlib}'ing  your \tr{*.a} files:
%#% \begin{verbatim}
%#% % cd <topdir>
%#% % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
%#% %    ranlib $i
%#% %    # or, on some machines: ar s $i
%#% % end
%#% \end{verbatim}
%#% 
%#% \item
%#% Don't forget to test it!
%#% \end{enumerate}

%************************************************************************
%*                                                                      *
\section[checklist]{Building Glasgow tools from source: a checklist}
%*                                                                      *
%************************************************************************

\begin{enumerate}
\item
Install any pre-supposed utility programs that you do not have at your
site.  You have to do this ``by hand.''  It's not hard, and these are
things you want to have anyway.  Please see \sectionref{Pre-supposed}.

\item
Be sure you have a suitable Haskell compiler, or else the intermediate
C (\tr{.hc}) files.  In some cases, you might want an alternative set
of interface (\tr{.hi}) files (quicker than generating a fresh set).
\Sectionref{install-strategy} lists the various strategies you might
adopt.

If you don't have a Haskell compiler, the most painless option is to
use a binary-distributed GHC to compile Glasgow tools (including GHC
itself) from source.  Installing a binary distribution (the first
step) is described in \sectionref{installing-bin-distrib}.

\item
You might want to write-protect your source files at this point:
\begin{verbatim}
cd <the-very-top-dir>
find . -type f \! -name \*.hi \! -name \*.hc \! -name \*.jm -print \
        | xargs chmod a-w
\end{verbatim}

\item
Run the \tr{configure} script.  It is a shell script that looks around
to find out things about your system.  You can see the \tr{configure}
options by passing it a \tr{--help} flag, or by reading
\sectionref{Configuring}.

\item
Once configured, build the basic support utilities and make your
Makefiles, including the automagically-created dependencies between
files.  The near-universal incantation is:
\begin{verbatim}
% cd <the-very-top-dir>
% sh < STARTUP >& startup.log   # and chk the log afterwards!
\end{verbatim}

\item
Build the Glasgow tools you are interested in, as \tr{STARTUP} suggests:
\begin{verbatim}
% cd <the-very-top-dir>/<tool>
% make all >& make.log          # time to go to lunch!
\end{verbatim}
Consult the list of known pitfalls (\sectionref{build-pitfalls}) if
something goes wrong.

\item
Test what you've built, enough to know that it's working.

\item
Actually install the tools, if you wish:
\begin{verbatim}
% cd <the-very-top-dir>/<tool>
% make install
\end{verbatim}

\item
Make and/or install the documentation.

\item
Save a copy of your \tr{config.status} file, for the next
even-more-wonderful release!

\item
If you're finished, tidy up after yourself [\tr{make clean}], if you
want to.

Alternatively, \tr{/bin/rm -rf <tool>} :-)
\end{enumerate}

%************************************************************************
%*                                                                      *
\section[building-GHC]{Building the Glasgow Haskell Compiler (GHC)}
\index{GHC installation, from sources}
%*                                                                      *
%************************************************************************

%************************************************************************
%*                                                                      *
\downsection
\section{Building GHC from source, compiling it with itself}
\index{building GHC with itself}
\index{booting GHC with itself}
%*                                                                      *
%************************************************************************

This section describes how to build GHC from source.  You would do
this if (a)~there is no ``canned'' binary distribution for your
machine, (b)~the binary distribution omits features that you want,
(c)~you want to make changes to GHC and them build them in, or
(d)~you like torturing yourself.

This blow-by-blow description follows the general checklist in
\sectionref{checklist}.

%************************************************************************
%*                                                                      *
\subsection[Right-compiler-and-files]{Do you have a suitable compiler and/or \tr{.hc} files and/or \tr{.hi} files?}
\index{booting GHC, files needed}
%*                                                                      *
%************************************************************************

We now proceed through each installation step, carefully.

Because the compiler heart of Glorious Glasgow Haskell is written in
Haskell, you have to use some ``bootstrapping'' mechanism.

Your best choice, if available, is to use a binary distribution for
your platform; i.e., compile GHC~0.26 with a GHC~0.26 that we have
provided.  Please see \sectionref{installing-bin-distrib} for how to
install a binary distribution.

Your remaining choice is to use the intermediate C (\tr{.hc}) files that we
supply.  This is the {\em only} choice for anyone trying to port to
a new or weakly-supported system.

The main drawback of the supplied-\tr{.hc} approach is that you will
have a lot of very bulky intermediate files on your disk for a while.

One obscure note: if you're going to build GHC to have a native-code
generator, you're well advised to get a suitable set of interface
files (to save making them yourself).  Please see \sectionref{Compiler_reconfig}
if you plan to end up with a native-code generator.

% If you have to boot from C (\tr{.hc}) files, you should follow the
% directions in \sectionref{booting-from-C}.

% We also supply parts of the system pre-compiled to C (in \tr{.hc}
% files).  This is partly to save you work (you don't have to wait for
% them to compile yourself) and partly because this is how we will
% eventually supply the self-compiling compiler (when that's ready).
% In any case, if you slurped the \tr{.tar.gz} file, you should, {\em in
% the same directory as before}, do...
% \begin{verbatim}
% % gunzip -c ghc-<version>-hc-files.tar.gz | tar xfv -
% \end{verbatim}

%************************************************************************
%*                                                                      *
\subsection{Write-protecting your source files}
\index{write-protecting source files}
%*                                                                      *
%************************************************************************

At this point, some people like to write-protect their source files against
inadvertent change:
\begin{verbatim}
cd <very-top-dir>
find . -type f \! -name '*.hi' \! -name \*.hc \! -name '*.jm' -print \
        | xargs chmod a-w
\end{verbatim}

%************************************************************************
%*                                                                      *
\subsection{Running \tr{configure} and \tr{STARTUP} for GHC}
\index{configure, for GHC}
\index{STARTUP, for GHC}
%*                                                                      *
%************************************************************************

The \tr{configure} script finds out things about your machine.  It
also allows you to specify features to include/exclude from your GHC
installation.

Please see \sectionref{Configuring} for all about \tr{configure}, and
\sectionref{Configuring-GHC} for details of GHC configuring (including
examples).

Once \tr{configure} runs successfully, do as it says and do
\tr{sh < STARTUP}.

%************************************************************************
%*                                                                      *
\subsection{Build the compiler!}
\index{make all, for GHC}
%*                                                                      *
%************************************************************************

Do the main GHC build, just as \tr{STARTUP} suggests:
\begin{verbatim}
% cd ghc
% make all >& make.log
\end{verbatim}
If this fails or something seems suspicious, check the ``known
pitfalls'' (\sectionref{build-pitfalls}).  If you can't figure out how
to proceed, please get in touch with us.

If you have to restart the build, for whatever reason, you are just as
well to make the whole thing; i.e., re-do as described above.  (Well,
the \tr{compiler} and \tr{lib} subdirectories are the last two; if the
build ``dies'' in one of them, it is usually safe to finish the job by
hand.)

%************************************************************************
%*                                                                      *
\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-0.26/ghc/driver/ghc ~/bin/sun4/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 -fhaskell-1.3 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}).

%************************************************************************
%*                                                                      *
\subsection[GHC_install]{Actually installing GHC}
\index{make install, GHC}
\index{installing, GHC}
%*                                                                      *
%************************************************************************

``Installing GHC'' means copying the files required to run it to their
``permanent home.''  You can then delete, or at least tidy up, your
source directory.

If you have no reason to install GHC, you can execute directly out of
the source tree, as sketched in the section above
(\sectionref{GHC_test}).

Assuming that everything's OK so far, all you need to do is:
\begin{verbatim}
% cd <very-top>/ghc
% make install
\end{verbatim}

If you're a little dubious (as I usually am), you can always do a
``trial run'' first:
\begin{verbatim}
% cd <very-top>/ghc
% make -n install >& temp-log-file-to-look-at
\end{verbatim}

In both cases, if something breaks, it's a {\em bug}.


%************************************************************************
%*                                                                      *
\subsection[make-docs]{Installing the GHC documentation (optional)}
\index{documentation, making}
\index{make docs, GHC}
\index{installing documentation}
%*                                                                      *
%************************************************************************

Because our documentation is in DVI/Info formats, and because there is
no standard practice about how such documents are ``installed,'' we
haven't tried to automate this (at least not enough that we promise it
works).

You can find all the documentation in the distribution with:
\begin{verbatim}
% cd ghc/docs
% find . \( -name '*.dvi' -o -name '*.info' -o -name '*.html' \) -print
\end{verbatim}

If you have a standard place to put such files, just copy
them there.  (Better ideas welcome.)

The following ``man'' pages are hidden around in the distribution:
\begin{verbatim}
ghc/utils/hp2ps/hp2ps.1
literate/info-utils/info.1
glafp-utils/scripts/mkdirhier.man
glafp-utils/scripts/lndir.man
\end{verbatim}
Please install them by hand if you need to.

%There are various pieces of GHC whose code can be formatted
%``literately.''  The usual procedure is...
%\begin{verbatim}
%% cd ghc/<wherever>
%% make depend          # VERY IMPORTANT for literate docs!
%% make docs            # or more directly....
%% make whatever.dvi    # or, for Info freaks,...
%% make whatever.info
%\end{verbatim}

%For ``chunks'' of the compiler proper, in \tr{ghc/compiler}, you will
%need to make a \tr{Makefile} for them first:
%\begin{verbatim}
%cd ghc/compiler
%make Makefile SUBDIRS=prelude  # for example...
%cd prelude
%make depend        # i.e., as before
%make prelude.dvi
%\end{verbatim}
%Directories for which this {\em might} (I emphasize: `MIGHT') work are ...
%\begin{verbatim}
%codeGen/Jmakefile
%coreSyn/Jmakefile
%deSugar/Jmakefile
%podizeCore/Jmakefile
%prelude/Jmakefile
%typecheck/Jmakefile
%\end{verbatim}
%
%Remember: an unpatched perl 4.035 will {\em crash} on making many of
%our ``literate'' Info files.  (The current version, 4.036, will not.)

%$$ Note: Because we make our Info files by going through Texinfo format,
%$$ you can use \tr{texi2html} to produce HTML files.  A
%$$ minisculely-hacked version is in the distribution in
%$$ \tr{literate/texi2html/texi2html}.

%************************************************************************
%*                                                                      *
\subsection[clean-up]{Cleaning up after yourself}
\index{make clean, GHC}
\index{cleaning up afterwards}
%*                                                                      *
%************************************************************************

\tr{make clean} is the basic command to tidy things up.  However: if
you do this, {\em you will not be able to execute directly out of the
source tree thereafter!} (as sketched in \sectionref{GHC_test}).  Nor will
you be able to make documents, etc.---you would have to re-build parts
of GHC first.

If you want to execute out of the source tree but would like to clear
off lots and lots of stuff, you can do:
\begin{verbatim}
% cd ghc/lib    # scrub library C and object files
% rm */*.hc
% find . -name '*.o' -print | xargs /bin/rm

% cd ghc/compiler   # scrub compiler object files
% rm */*.o
% rm */*.hc         # if you have been keeping them around
\end{verbatim}
(You can scrub the object files in \tr{ghc/runtime} similarly---except
\tr{main/TopClosure*.o}.)

%\tr{make veryclean} is the command to clear off everything that can be
%safely cleared off.  Not recommended (inadequately tested).

%************************************************************************
%*                                                                      *
\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.''

To boot from C (\tr{.hc}) files, you need the regular source distribution
(\tr{ghc-0.26-src.tar.gz}) and also some extra files in
\tr{ghc-0.26-hc-files.tar.gz}.  DON'T FORGET any extra \tr{.hc}
files for profiling, concurrent, parallel, ...

Whatever you want to build, just unpack all the files ``together'':
\begin{verbatim}
% cd <wherever>
% gunzip -c ghc-0.26-src.tar.gz      | tar xf -
% gunzip -c ghc-0.26-hc-files.tar.gz | tar xf -      # basic...
% gunzip -c ghc-0.26-prof-hc-files.tar.gz | tar xf - # profiling...
% gunzip -c ghc-0.26-conc-hc-files.tar.gz | tar xf - # concurrent...
... etc ...
\end{verbatim}

For the ``it's been tried before'' machines, the normal
configure/build procedure will probably work; just keep your eyes
peeled for mischief.

WORD OF WISDOM: Be sure you have a suitable GCC (GNU C compiler); please
see \sectionref{port-info} for any specific requirements for your machine.

You'll need plenty of disk space to do this whole procedure!

%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsection[boot-file-fiddling]{Unpack; then fiddle files before booting}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ Unpack the relevant files for booting as described above.
%$$ 
%$$ If you are on a never-seen-before platform, then there is a little
%$$ machine-specific code/stuff scattered around the GHC files, which will
%$$ need to be updated before you get started.
%$$ 
%$$ \begin{description}
%$$ %---------------------------------------------------------------------
%$$ \item[Change \tr{configure}, so it recognizes your machine:]
%$$ Add the obvious stuff if it says ``Unrecognised platform for GHC.''
%$$ 
%$$ If you are teaching GHC how to ``registerise'' on a new platform, you
%$$ will also need to make sure the variable @GhcWithRegisterised@ is set
%$$ correctly.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Change {\em two} copies of \tr{platform.h.in}:]
%$$ In the obvious way.  They are in \tr{ghc/includes/} and \tr{mkworld/}.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Floating-pointness:]
%$$ Grep for \tr{_TARGET} in \tr{ghc/includes/*.*h} and make suitable
%$$ adjustments.
%$$ 
%$$ One change you will certainly make is in \tr{StgMacros.lh}, to decide
%$$ the inclusion of \tr{ieee-flpt.h} and \tr{BIGENDIAN}.
%$$ 
%$$ Please use the CPP symbols defined in \tr{platform.h.in}!
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[64-bitness:]
%$$ Again, grepping for \tr{_TARGET} in \tr{ghc/includes/*.lh} will find
%$$ the places that need adjusting.  \tr{GhcConstants.lh} and
%$$ \tr{StgTypes.lh} are two places that will need tweaking, for example.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[``Registerizing'' magic:]
%$$ This is the platform-specific stuff in \tr{COptJumps.lh},
%$$ \tr{COptWraps.lh}, and \tr{MachRegs.lh} in \tr{ghc/includes}.
%$$ 
%$$ If you are doing an initial unregisterised boot for your platform, you
%$$ don't need to mess with these files at all.
%$$ 
%$$ \Sectionref{real-version-from-init-boot} discusses how to get a
%$$ ``registerised'' version of GHC going.  (Much trickier, but much
%$$ faster. [0.26: and the documentation is OUT-OF-DATE])
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Host/target platforms in the driver:]
%$$ Grep for all occurrences of \tr{$HostPlatform} and \tr{$TargetPlatform}
%$$ in \tr{ghc/driver/*.lprl}.
%$$ 
%$$ Don't worry about the \tr{process_asm_block} stuff in
%$$ \tr{ghc-split.lprl}.  Not used in a straight ``unregisterised''
%$$ version.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Target-specific GCC flags in the driver:]
%$$ 
%$$ The main thing to worry about in \tr{ghc.lprl} is the section on how
%$$ to ``Add on machine-specific C-compiler flags.''
%$$ You may want to add something {\em vaguely} like:
%$$ \begin{verbatim}
%$$ ...
%$$ } elsif ($TargetPlatform =~ /^mips-dec-ultrix/) {
%$$     unshift(@CcBoth_flags,  ('-G0', '-static')) if $GccAvailable;
%$$ \end{verbatim}
%$$ 
%$$ Explanations: (1)~Static linking {\em tends} to give less problems, so
%$$ it is a reasonable choice for an initial attempt.
%$$ 
%$$ (2)~In processing
%$$ the intermediate C (\tr{.hc}) files, you are compiling some {\em huge}
%$$ wads of C.  Sadly, quite a few systems don't cope well with this, and
%$$ more than a few silently produce object files that won't link.  GCC
%$$ usually provides some platform-specific flag that says ``generate code
%$$ that will work no matter how big the files are''.  The \tr{-G0} for
%$$ DEC MIPS boxes is an example.  If your system has such restrictions,
%$$ insert some magic {\em here}!
%$$ \end{description}

%************************************************************************
%*                                                                      *
\subsection{Do \tr{configure}; \tr{sh < STARTUP}; \tr{cd ghc; make all}; test it!}
\index{configure, GHC with .hc files}
\index{make all, GHC with .hc files}
%*                                                                      *
%************************************************************************

Go ahead and try \tr{configure}, as described \Sectionref{Configuring}
(GHC specifics in \Sectionref{Configuring-GHC}).

The key \tr{configure} option is \tr{--with-hc=c}.  A typical
going-via-C invocation might be:

\begin{verbatim}
% ./configure  --prefix=/local/fp --with-hc=c   # basic + profiling
\end{verbatim}

Other common possibilities might be:

\begin{verbatim}
% ./configure --with-hc=c --disable-profiling   # basic only

% ./configure --with-hc=c --enable-concurrent --enable-parallel
        # basic + profiling + concurrent + parallel
\end{verbatim}

%$$ One likely reason it won't work is it will say it never heard of your
%$$ machine.  Just edit the script and carry on!  (As always, please send
%$$ us the changes.)

Next, run \tr{STARTUP} in the usual way, as described in
\Sectionref{STARTUP}.

It's now time to type \tr{cd ghc; make all}!  This ``should'' work,
especially, on a known machine.  Also, it can take a VERY long time
(esp. on oldish machines), so it's good to run overnight, on a quiet
machine, nice'd, etc., etc.

When it's all built, test your alleged GHC system, as suggested in
\sectionref{GHC_test}.

%$$ What you should end up with, built in this order: (1)~a runtime system
%$$ [\tr{ghc/runtime/libHSrts_ap.a}]; (2)~Prelude libraries
%$$ [\tr{ghc/lib/libHS_ap.a} and \tr{ghc/lib/libHShbc_ap.a}]; and (3)~a
%$$ compiler [\tr{ghc/compiler/hsc}] (which needs the first two).
%$$ 
%$$ (Umm... if you are on a supported platform, but compiling via C, then
%$$ the \tr{*.a} suffixes will be \tr{_ap_o.a} (regular) and \tr{_p.a}
%$$ (profiling).)

%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection{A pre-emptive \tr{hello, world} test}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ On an unsupported platform,
%$$ You very well may want to {\em kill the compilation} once
%$$ \tr{libHSrts_ap.a} and \tr{libHS_ap.a} are built, to do a little
%$$ pre-emptive testing:  time to run \tr{Hello, world!}.  Using
%$$ \tr{ghc/CONTRIB/hello.hc}...
%$$ \begin{verbatim}
%$$ % .../ghc/driver/ghc -c -g hello.hc
%$$ % .../ghc/driver/ghc -v -o hello -g hello.o
%$$ % ./hello
%$$ \end{verbatim}
%$$ 
%$$ If you have any trouble to do with ``consistency checking,'' just
%$$ avoid it, with the \tr{-no-link-chk} flag.
%$$ 
%$$ If \tr{hello} crashes/breaks, it's time for Ye Olde Debugger, or
%$$ perhaps Ye Older Cry for Help...
%$$ 
%$$ If things are OK and if you {\em did} kill the compilation, just re-do
%$$ \tr{make} to finish the job (build any other libraries, then the
%$$ compiler binary \tr{ghc/hsc}).
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[init-boot-hsc]{Finishing the initial boot}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ If you manage to get a \tr{ghc/hsc} binary (usually huge), then...
%$$ YOU HAVE A HASKELL COMPILER, albeit big and slow!  So test it,
%$$ ``from the sources,'' before installing it:
%$$ \begin{verbatim}
%$$ % cat > test.hs
%$$ main = print ((10001 - 30002)::Integer)
%$$ -- or any other program(s) you want...
%$$ ^D
%$$ % .../ghc/driver/ghc -v -g -c test.hs
%$$ % .../ghc/driver/ghc -v -g -o test test.o
%$$ % ./test
%$$ \end{verbatim}
%$$ (Note how I fiendishly included a \tr{-g}, in case I had to throw a
%$$ debugger at it...)
%$$ 
%$$ Of course, you {\em may not} have a \tr{ghc/hsc} binary---something
%$$ went wrong.  The most likely cause is a compiler/assembler/linker
%$$ failure due to the HUGE size of this program.  Please revisit the
%$$ discussion about this towards the end of
%$$ \sectionref{boot-file-fiddling}.  Sadly, if you have to tweak
%$$ C-compiler/whatever flags, you may have to rebuild all the
%$$ libraries/compiler again; the following is sufficient to clear
%$$ off everything for a fresh start (NB: don't do \tr{make clean}):
%$$ \begin{verbatim}
%$$ % cd ghc/runtime    # clear off RTS
%$$ % make clean SUBDIRS=foo    # but avoid clearing GMP lib
%$$ % cd ../lib
%$$ % rm */*.o
%$$ % cd ../compiler
%$$ % rm */*.o
%$$ \end{verbatim}
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[installing-init-boot]{`Installing' the initial boot}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ If you are satisfied that things are working, {\em possibly install} the
%$$ initial booted version.  The main point is: save the precious files
%$$ you've just created.
%$$ 
%$$ Should you choose {\em not to install}, be sure to secure these files
%$$ somewhere/somehow:
%$$ \begin{verbatim}
%$$ ghc/compiler/hsc            # compiler
%$$ ghc/runtime/libHSrts_ap.a   # RTS things
%$$ ghc/lib/libHS_ap.a          # prelude library
%$$ \end{verbatim}
%$$ 
%$$ Should you install, the comments about `normal' installing, in
%$$ \Sectionref{GHC_install}, do apply. It should come down to
%$$ something like...
%$$ \begin{verbatim}
%$$ % cd ghc
%$$ % make -n install >& temp-log-file-to-look-at # trial run: chk it out!
%$$ % make install                                    # the real thing...
%$$ \end{verbatim}
%$$ 
%$$ (I'd probably do the install by hand, if at all; let me know if you're
%$$ worried about the exact incantations.)
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[testing-init-boot]{Testing the initial boot}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ It wouldn't be a bad idea, especially on an unusual machine; I usually
%$$ just skip this part, though :-)
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsection[split-libs]{Getting ``splitting'' going on your Prelude libraries}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ ghc-split.lprl
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsection[real-version-from-init-boot]{Getting a ``registerised'' version going}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ Version 0.26: THIS DOCUMENTATION IS OUT-OF-DATE.  (Sigh)
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[registerised-magic-files]{Setting up files for `registerizing'}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ It's time to jiggle some files related to GCC-magic-optimisation.
%$$ {\em This is real work, folks.} What follows is a {\em rough} guide to
%$$ what needs looking at.
%$$ 
%$$ \begin{description}
%$$ %---------------------------------------------------------------------
%$$ \item[\tr{ghc/includes/MachRegs.lh}:]
%$$ This maps ``STG registers'' (Hp, SpA, TagReg, etc.) to machine
%$$ registers on a platform-by-platform basis.
%$$ If you can't figure it out, you'd probably better ask.
%$$ 
%$$ We are using a GCC extension to put C global variables in specific
%$$ registers; see the \tr{Global Reg Vars} node in the GCC documentation.
%$$ 
%$$ You should get the idea from the settings for our ``fully supported''
%$$ platforms, but you will need to know/learn something about your
%$$ hardware and your GCC (e.g., what registers it snaffles for itself).
%$$ 
%$$ One way I went about learning these register secrets was to try the
%$$ following test file (a Sun3 version here, \tr{regs3.hc}):
%$$ \begin{verbatim}
%$$ #define StgPtr long int *
%$$ 
%$$ register StgPtr FooL0 __asm__("a0");
%$$ register StgPtr FooL1 __asm__("a1");
%$$ register StgPtr FooL2 __asm__("a2");
%$$ register StgPtr FooL3 __asm__("a3");
%$$ register StgPtr FooL4 __asm__("a4");
%$$ register StgPtr FooL5 __asm__("a5");
%$$ register StgPtr FooL6 __asm__("a6");
%$$ register StgPtr FooL7 __asm__("a7");
%$$ 
%$$ register StgPtr FooG0 __asm__("d0");
%$$ register StgPtr FooG1 __asm__("d1");
%$$ register StgPtr FooG2 __asm__("d2");
%$$ register StgPtr FooG3 __asm__("d3");
%$$ register StgPtr FooG4 __asm__("d4");
%$$ register StgPtr FooG5 __asm__("d5");
%$$ register StgPtr FooG6 __asm__("d6");
%$$ register StgPtr FooG7 __asm__("d7");
%$$ 
%$$ wurble(x)
%$$ int x;
%$$ {
%$$   return (x + 42);
%$$ }
%$$ \end{verbatim}
%$$ Then compile it repeatedly with your new driver, e.g.,
%$$ \tr{ghc-boot-me -v -S regs3.hc}, removing register declarations that
%$$ offend it.  Note: GCC's error messages about these register things
%$$ can be less than totally enlightening.
%$$ 
%$$ Note: don't worry about warnings that you're stealing a
%$$ ``call-clobbered'' (caller-saves) register.  These are stealable,
%$$ though some extra work may be required.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[\tr{ghc/includes/COptJumps.lh}:]
%$$ The name of the game, essentially, is for the @JMP_@ macro to turn
%$$ into a simple jump instruction.  Also, through fiendish collaboration
%$$ with the assembly-language post-processor in the driver (coming up
%$$ soon...), we're going to rip out all the pushing/popping to do with
%$$ the C stack.
%$$ 
%$$ You {\em may} need to do something as on 680x0s, where we inject
%$$ beginning-of- and end-of-real-code markers, which gives the post-processor
%$$ something to look out for and tidy up around.
%$$ 
%$$ You also need to define some mini-interpreter-related macros.  These
%$$ are discussed under \tr{StgMiniInt.lc} (below).
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[\tr{ghc/includes/COptWraps.lh}:]
%$$ 
%$$ The macro @STGCALL1(f,a)@ is defined here; it almost certainly should
%$$ just be \tr{callWrapper(f,a)} (where the magical routine @callWrapper@
%$$ is yet to come).
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[\tr{ghc/driver/ghc-asm-<arch>.lprl}:]
%$$ This is the notorious ``optimised assembler post-processor.''  You
%$$ need to create a suitable \tr{require}-able file (if you haven't
%$$ already), add a mention in the \tr{Jmakefile}, and add suitable code
%$$ in the driver, \tr{ghc.lprl} to invoke it.
%$$ 
%$$ This is really quite horrible for a SPARC; we have to shut down the
%$$ register-window mechanism {\em entirely}, by ripping out all the
%$$ \tr{save} and \tr{restore} instructions.
%$$ 
%$$ We also go to lots of trouble to move info tables next to entry code,
%$$ elide slow and fast entry-point routines, and probably some things
%$$ I've forgotten about.
%$$ 
%$$ Ask if you are desperately confused...
%$$ 
%$$ Perhaps it will be less gruesome for your machine!
%$$ 
%$$ Don't forget to test it with \tr{-g} turned on (lots of \tr{\.stab?}
%$$ lines suddenly appear)...
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[\tr{CallWrap_C.lc} or \tr{CallWrapper.ls}, in ghc/runtime/c-as-asm/:]
%$$ 
%$$ These files have register saving/restoring code.  For a SPARC, quite a
%$$ bit has to be written in assembly language (\tr{CallWrapper.ls}), to
%$$ avoid register windowing; but, for other machines, the C versions
%$$ (\tr{CallWrap_C.lc}) should work fine.
%$$ 
%$$ Look at the generated assembly-language very carefully!
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[ghc/runtime/c-as-asm/StgMiniInt.lc:]
%$$ 
%$$ You need to manage to create entry points named @miniInterpret@ and
%$$ @miniInterpretEnd@, the former to jump off into threaded code; the
%$$ latter to come back to.
%$$ 
%$$ You may be able to do something quite simple---it's not bad either for
%$$ mc680x0s or SPARCs---but you will want to inspect the assembler output
%$$ before declaring victory.
%$$ 
%$$ In the SPARC case, it uses a macro (@MINI_INTERPRETER_END_IS_HERE@)
%$$ defined in \tr{imports/COptJumps.lh}.
%$$ \end{description}
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[testing-registerisation]{Initial testing of a `registerisation'}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ {\em How to begin testing this registerised stuff:}
%$$ 
%$$ Make sure your imports files are up-to-date:
%$$ \begin{verbatim}
%$$ % cd ghc/includes
%$$ % make
%$$ \end{verbatim}
%$$ 
%$$ Park yourself in your driver subdirectory and ...
%$$ \begin{verbatim}
%$$ % cd ghc/driver                     # park
%$$ % make Makefile                     # if you changed "only4-ghc.ljm"...
%$$ % make                              # just to be sure
%$$ 
%$$ % cp ../compiler/utils/Util.hc temp.hc      # grab a test file;
%$$                                     # you may want to chop it down
%$$ % ghc-boot-me -v -S -ddump-raw-asm temp.hc # see what happens!
%$$ \end{verbatim}
%$$ 
%$$ (The \tr{-ddump-raw-asm} option shows you, on stderr, what comes
%$$ directly out of GCC.  That's what your post-processing mangler has to
%$$ chomp on.)
%$$ 
%$$ {\em Going further on testing this stuff:}
%$$ 
%$$ Another good place to practice is \tr{ghc/runtime}; so, for example:
%$$ \begin{verbatim}
%$$ % cd ghc/runtime
%$$ % make Makefile
%$$ % make clean
%$$ % make libHSrts_ap_o.a
%$$ \end{verbatim}
%$$ 
%$$ The .s output from \tr{main/StgUpdate.lhc} can be particularly
%$$ enlightening, in that, if you are going to have register spills (e.g.,
%$$ because your registerisation choices left GCC with too few with which
%$$ to generate good code), you will see it on this file.
%$$ 
%$$ Don't forget: you need a working \tr{CallWrapper.ls} and
%$$ \tr{StgMiniInt.lc} (both in \tr{c-as-asm}) before this registerised
%$$ stuff will actually run.
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[building-registerized]{Building the basics of a registerised GHC}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ \begin{description}
%$$ %---------------------------------------------------------------------
%$$ \item[What you need to run a registerised program:]
%$$ 
%$$ Once you make a \tr{libHSrts_ap_o.a} in runtime, all you need is a
%$$ prelude library.  You need to do it by hand still.
%$$ \begin{verbatim}
%$$ % cd ghc/lib
%$$ % ghc-boot-me -c -g -O -osuf _ap_o.o */*.hc # takes a while
%$$ %
%$$ % rm libHS_ap_o.a
%$$ % ar clq libHS_ap_o.a */*_ap_o.o
%$$ % ranlib libHS_ap_o.a
%$$ \end{verbatim}
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Testing the registerised GHC:]
%$$ 
%$$ As before, starting with the \tr{.hc} you made in the first round:
%$$ \begin{verbatim}
%$$ % ghc-boot-me -v -g -c test.hc
%$$ % ghc-boot-me -v -g -o test test.o
%$$ % ./test
%$$ \end{verbatim}
%$$ 
%$$ If things are broken, the likely outcome is a core dump, and you'll
%$$ need to throw GDB (or equiv) at it.  Useful breakpoints are
%$$ \tr{main}, \tr{miniInterpret}, \tr{Main_main_entry}, and
%$$ \tr{startStgWorld} (when you're just getting going), and
%$$ \tr{stopStgWorld} and \tr{miniInterpretEnd} (which can show that you
%$$ ``almost made it'').
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[If you get a consistency-checking error:]
%$$ 
%$$ [From the driver] (These are not as terrible as they seem...)
%$$ 
%$$ The driver, notably \tr{driver/ghc-consist.lprl}, runs the SCCS
%$$ program \tr{what} over your executable, and tries to make sense of the
%$$ output.
%$$ 
%$$ If you need to make changes to \tr{ghc-consist.lprl}, just do so, then
%$$ re-\tr{make} in the driver directory.
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Compiling the compiler registerisedly:]
%$$ 
%$$ If you can successfully compile and run {\em some} registerised
%$$ programs, you are probably ready to compile the compiler in that way.
%$$ \begin{verbatim}
%$$ % cd ghc/compiler
%$$ % ghc-boot-me -c -g -O */*.hc           # takes *much more* than a while
%$$ % ghc-boot-me -g -O -o hsc */*.o    # LINK!
%$$ \end{verbatim}
%$$ 
%$$ (Sun3 note: on the particular system I used, I had link troubles.  It
%$$ was apparently a Sun bug, because I got a successful link with the GNU
%$$ linker.)
%$$ 
%$$ %---------------------------------------------------------------------
%$$ \item[Testing the {\em whole} registerised GHC:]
%$$ 
%$$ As before, but now you can try compiling from \tr{.hs} to \tr{.hc}
%$$ files with the newly-registerised \tr{hsc}.
%$$ \end{description}
%$$ 
%$$ %************************************************************************
%$$ %*                                                                  *
%$$ \subsubsection[real-version-fine-tuning]{Fine-tuning of a ``registerised'' version of GHC}
%$$ %*                                                                  *
%$$ %************************************************************************
%$$ 
%$$ NOT FINISHED YET.  Let me know if you get this far :-)
%$$ 
%$$ installing
%$$ 
%************************************************************************
%*                                                                      *
\subsection[Compiler_reconfig]{Building GHC again after you've bootstrapped}
\index{GHC reconfiguration, after booting}
\index{booting, then GHC reconfigure}
\index{native-code generator, after booting}
%*                                                                      *
%************************************************************************

Two reasons why you might want to re-configure and re-build GHC after
an initial boot are: (a)~to get a native-code generator, or (b)~if you
are going to hack on GHC.

The reason you must rebuild to get a native-code generator: The
\tr{.hc} files will {\em not} turn into a native-code generator, and
the distributed \tr{.hi} files ``match'' those \tr{.hc} files.

From here on, I presume you've installed your booted GHC as
\tr{ghc-0.26}.

If you are going for a native-code generator, you can save yourself
some re-compiling by getting a suitable set of interface (\tr{.hi})
files, for GHC for your machine.  You should end up doing, for example:
\begin{verbatim}
cd ghc-0.26/ghc/compiler # note where you are!

rm */*.o    # scrub the old compiler files

gunzip -c ghc-0.26-hi-files-alpha.tar.gz | tar xfv -
\end{verbatim}

Now you can configure as before, but using \tr{--with-hc=ghc-0.26}
(\tr{config.status} records what you did before).

Running \tr{sh < STARTUP} isn't strictly necessary; you only need to
rebuild in \tr{ghc/compiler}:
\begin{verbatim}
cd ghc-0.26/ghc/compiler
make Makefile   # if you didn't STARTUP...

make all EXTRA_HC_OPTS=-fvia-C  # -fvia-C important!
make all EXTRA_HC_OPTS=-fvia-C  # again, until .hi files settle...
\end{verbatim}

You might want to to again test GHC ``out of the build'' before you
type \tr{make install} in \tr{ghc/compiler} to finish the job.

%************************************************************************
%*                                                                      *
\section[building-with-HBC]{Building GHC with HBC or other funny Haskell compilers}
\index{GHC, building with HBC}
\index{GHC, building with old GHCs}
\index{GHC, building with other compilers}
%*                                                                      *
%************************************************************************

GHC~0.26 doesn't build with HBC.  (It could, but we haven't put in
the effort to maintain it.)

GHC~0.26 is best built with itself, GHC~0.26.  We heartily recommend
it.  GHC~0.26 can certainly be built with GHC~0.23 or 0.24, and with
some earlier versions, with some effort.

GHC has never been built with compilers other than GHC and HBC.

%$$ If you are going to build the compiler with HBC,
%$$ please get the appropriate set of \tr{.hi} interface
%$$ files.  If you going to build with an old GHC,
%$$ visit your psychiatrist first.
%$$ 
%$$ If you choose this route,
%$$ you are well advised to get and install a set of \tr{.hi} interface
%$$ files that were created by the same compiler you intend to use.  If
%$$ you intend to use HBC, we may provide a suitable ``spare'' set of \tr{.hi} files,
%$$ in \tr{ghc-0.26-hi-files-hbc.tar.gz}, from an FTP site near you.
%$$ 
%$$ Unpack the \tr{.hi} files in this {\em somewhat unobvious} way:
%$$ \begin{verbatim}
%$$ % cd ghc-0.26/ghc/compiler   # **** this is where you want to be!!! ****
%$$ 
%$$ % gunzip -c ghc-0.26-hi-files-hbc.tar.gz | tar xfv -
%$$ \end{verbatim}

%************************************************************************
%*                                                                      *
\section[Pre-supposed]{Installing pre-supposed utilities}
\index{pre-supposed utilities}
\index{utilities, pre-supposed}
%*                                                                      *
%************************************************************************

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.

(We still assume Perl version 4; experience suggests that Perl~5
is fine, too.)

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.

Perl version 4.035 has a bug to do with recursion that will bite if
you run the \tr{lit2texi} script, when making Info files from
``literate'' files of various sorts.  Either use a more recent version
(4.036, or 5.00n) or an older version
(e.g., perl 4.019).

\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.0, and has no problems that we know of.

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.  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.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.

\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.

\item[Something other than Sun's \tr{/usr/bin/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.
\end{description}

%************************************************************************
%*                                                                      *
\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 use the \tr{--with-tmpdir=<dir>} option
to \tr{configure}.  Then GHC will use the appropriate directory
in all cases.

%------------------------------------------------------------------------
\item
When configuring the support code (mkworld, glafp-utils, etc.), you
will see mention of \tr{NO_SPECIFIC_PROJECT} and
\tr{NO_SPECIFIC_VERSION}.  This is cool.

%------------------------------------------------------------------------
\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
In 0.26, when compiling via C, you'll sometimes get ``warning:
assignment from incompatible pointer type'' out of GCC.  Harmless.

%------------------------------------------------------------------------
%\item
%If you build an ``unregisterised'' build, you will get bazillions of
%warnings about `ANSI C forbids braced-groups within expressions'.
%Especially in \tr{ghc/lib}.  These are OK.

%------------------------------------------------------------------------
\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 \tr{compile}
macro for the offending module,
in \tr{ghc/compiler/Jmakefile} (towards the end);
(2)~re-\tr{make Makefile} in that directory; (3)~try again: \tr{make}.

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
%Sooner or later in your ``make-worlding'' life you will do and see
%something like:
%\begin{verbatim}
%% make Makefile
%        rm -f Makefile.bak; mv Makefile Makefile.bak
%../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=...
%../.././mkworld/jrestoredeps
%==== The new Makefile is for: ====
%make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen
%Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard
%*** Error code 1
%make: Fatal error: Command failed for target `Makefile'
%\end{verbatim}
%
%Don't panic!  It should restore your previous \tr{Makefile}, and
%leave the junk one in \tr{Makefile.bad}.  Snoop around at your leisure.

%------------------------------------------------------------------------
%\item
%If you do corrupt a \tr{Makefile} totally, or you need to glue a new
%directory into the directory structure (in \tr{newdir}---which must
%have a \tr{Jmakefile}, even if empty), here's a neat trick:
%\begin{verbatim}
%#
%# move to the directory just above the one where you want a Makefile...
%cd ..
%#
%# make Makefiles, but lie about the directories below...
%make Makefiles SUBDIRS=newdir
%\end{verbatim}
%
%This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and
%it will be properly wired into the general make-world structure.

%------------------------------------------------------------------------
%\item
%Don't configure/build/install using a variety of machines.  A
%mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to
%build GHC (\tr{make all}) on a Sun3.

%------------------------------------------------------------------------
\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
\end{enumerate}

%************************************************************************
%*                                                                      *
\section[weird-configs]{Making weird GHC configurations}
\index{GHC unusual configurations}
%*                                                                      *
%************************************************************************

The usual way to build a ``weird'' GHC configuration is to turn
various \tr{configure} knobs, e.g., \tr{--enable-concurrent}.
Please see \sectionref{Configuring-GHC} about GHC configuring.

If you want to build some Very Customised GHC libraries, it's
probably best to send email to us, asking how.

%$$ Usually, you will build whatever libraries your chosen ``setup''
%$$ specifies.  However, perhaps you are a hacker, and you want an extra
%$$ ``ticky-ticky profiling'' version of the libraries.  (Or, you want a
%$$ version compiled with your Very Own Optimisation...)
%$$ 
%$$ To create a ``user way'' or setup, put
%$$ something like this somewhere (more on ``somewhere'', below):
%$$ \begin{verbatim}
%$$ #ifndef  Build_UserWay_a
%$$ #define Build_UserWay_a YES
%$$ GHC_USER_WAY_FLAG_a = -ticky
%$$ GHC_USER_WAY_OPTS_a = -fstg-reduction-counts -O
%$$ #endif /*  ! Build_UserWay_a */
%$$ \end{verbatim}
%$$ You'll be able to invoke the driver with a \tr{-ticky} option, which
%$$ will be as if you typed in all that other stuff.  It will also arrange
%$$ that there is a version of the prelude (\tr{libHS_a.a} library,
%$$ \tr{Prelude_a.hi} to match) and runtime system (\tr{libHSrts_a.a}) to
%$$ match.  (Neat, huh?)
%$$ 
%$$ On the ``somewhere'' to specify what to build: If you don't plan
%$$ to re-\tr{configure}, just change \tr{site-ghc.jm}.  If you do plan to
%$$ re-\tr{configure}, change \tr{site-ghc.jm.in} and re-\tr{configure}
%$$ immediately.
%$$ 
%$$ One note about {\em adding} ``user setups'' to an existing build:
%$$ Besides remaking your \tr{Makefiles} straight away, {\em don't forget}
%$$ to remake the driver (in \tr{ghc/driver}) before making any libraries!
%$$ The short cut is:
%$$ \begin{verbatim}
%$$ cd ..../ghc/driver
%$$ make Makefile; make all
%$$ cd ../runtime
%$$ make Makefile; make all
%$$ cd ../lib
%$$ make Makefile; make all
%$$ \end{verbatim}

\upsection

%************************************************************************
%*                                                                      *
\section[building-Haggis]{Building Haggis (Haskell GUI toolkit)}
\index{Haggis, building}
\index{building Haggis}
%*                                                                      *
%************************************************************************

NOT DONE YET.

%************************************************************************
%*                                                                      *
\section[building-Happy]{Building Happy (Haskell parser generator)}
\index{Happy, building}
\index{building Happy}
%*                                                                      *
%************************************************************************

NOT DONE YET.

%************************************************************************
%*                                                                      *
\section[building-NoFib]{Building NoFib (Haskell benchmark suite)}
\index{NoFib suite, building}
\index{building the NoFib suite}
%*                                                                      *
%************************************************************************

NOT DONE YET.

%************************************************************************
%*                                                                      *
\section[Configuring]{Running \tr{configure}}
\index{configure script}
%*                                                                      *
%************************************************************************

The GNU-style \tr{configure} script figures out things which we need
to know to build one or more Glasgow tools for your machine.  Also,
\tr{configure} lets you specify what you want built.

Most people will configure/build one tool at a time.  The
``short-cut'' instructions
for GHC are in \sectionref{Configuring-GHC},
for Haggis in \sectionref{Configuring-Haggis},
for Happy in \sectionref{Configuring-Happy},
and for NoFib in \sectionref{Configuring-NoFib}.

However, \tr{configure} lets you pick and choose, so you can build
several things ``in a one-er''.  Just fling in all the options
at once, and be amazed.

%************************************************************************
%*                                                                      *
\subsection[Configuring-general]{\tr{configure} options for all tools}
\index{Configuring (general)}
%*                                                                      *
%************************************************************************

Many \tr{configure} options apply no matter what tools you are building.

\begin{description}
\item[\tr{--help}:] (a standard GNU option)
\index{--help configure option}
Prints out a long usage message.  The first part is GNU boilerplate;
after that is the Glasgow info.

\item[\tr{--prefix=}{\em directory}:] (a standard GNU option)
\index{--prefix configure option}
Sets the ``root'' directory for where a system should be installed;
defaults to \tr{/usr/local}.

With Happy, for example, the main \tr{happy} binary will end up in
\tr{/usr/local/bin/happy}.

%--------------------------------------------------------------
\item[\tr{--exec-prefix=}{\em directory}:] (a standard GNU option)
\index{--exec-prefix configure option}
Sets the ``root'' directory
for where executables
(e.g., the GHC driver) should be installed; defaults to whatever
\tr{--prefix} is,
meaning that things will be installed in \tr{/usr/local/bin}.

%$$ At Glasgow, we want such executables to go in (e.g.)
%$$ \tr{/local/fp/bin.sun4}, so \tr{--exec-prefix} is no use to us.
%$$ Happily, there's more than one way to do it!---just change
%$$ \tr{InstBinDir_GHC} in \tr{ghc/mkworld/site-ghc.jm.in}...  (We hope
%$$ this doesn't bring back too many bad memories for our
%$$ pre-\tr{configure} users.)

%--------------------------------------------------------------
\item[\tr{--with-hc=}{\em hask}:]
\index{--with-hc configure option}
Use {\em hask} as my ``installed Haskell compiler.''

The name {\em hask} has to be one of \tr{ghc*} (for Glasgow Haskell),
\tr{hbc*} (for Chalmers HBC), or \tr{nhc*} (for Rojemo's NHC).
We hope to add more!

As a special case, \tr{--with-hc=c} means ``I don't have a Haskell
compiler, please compile from intermediate C files (produced by GHC
somewhere else).''

%--------------------------------------------------------------
\item[\tr{--with-tmpdir=}{\em directory}:]
Set the directory where temporary files should be created.  This is
\tr{/tmp} by default, which is Sometimes Uncool (because, e.g.,
\tr{/tmp} is too small).  There's just no telling.

On our Alphas, for example, we use \tr{--with-tmpdir=/usr/tmp}.

%--------------------------------------------------------------
\item[\tr{--with-max-heap=}{\em size}:]
When whatever Haskell compiler is run while building the Glasgow
tools, it will try to use some sane-but-not-too-big heap size.  If you
have a machine with plenty of memory, you might want to say ``Go ahead
and use a great big heap.''  This option allows this.  So, for
example, on our Alphas we might say \tr{--with-max-heap=48m}.
\end{description}

%************************************************************************
%*                                                                      *
\subsection[Configuring-GHC]{GHC-specific things in \tr{configure}}
\index{Configuring for GHC}
%*                                                                      *
%************************************************************************

The easiest way to see all the \tr{configure} options for GHC is to
type \tr{./configure --help}.  (I don't feel like typing the whole
thing again, into this document...)

Some common combinations would be:

\begin{verbatim}
./configure --prefix=/users/fp/partain --with-hc=c --disable-profiling
    # use .hc files; don't bother with profiling

./configure --with-hc=ghc-0.26 --with-readline-library --with-sockets-library
    # simple build with itself; for Sun4s & Alphas, you
    # should grab & use ghc-0.26-hi-files-<blah>.tar.gz
    # (because those machines have a native-code generator).
    # For the extra libraries, you've got to have the right
    # stuff to link to.

./configure --with-hc=ghc-0.26 --disable-hsc-optimised --enable-hsc-debug
    # Don't use -O on GHC itself; turn on -DDEBUG.
    # Slows things way down, but it's the right thing if
    # you're hacking on GHC and doing lots of recompilations.

./configure --with-hc=c --enable-concurrent --enable-parallel --with-tmpdir=/usr/tmp
    # Do everything from .hc files; besides the normal ones,
    # you'll need the "prof", "conc" and "par" .hc files.
    # Use /usr/tmp as TMPDIR...
\end{verbatim}

Remember, if you build \tr{--with-hc=c} on a Sun4 or Alpha, you
do {\em not} have a native-code generator.

%************************************************************************
%*                                                                      *
\subsection[Configuring-Haggis]{Haggis-specific things in \tr{configure}}
\index{Configuring for Haggis}
%*                                                                      *
%************************************************************************

Use \tr{--enable-haggis}.  If you have Haggis and GHC in the same
build tree but only want to build Haggis, use \tr{--disable-ghc}.

MORE TO COME.

%************************************************************************
%*                                                                      *
\subsection[Configuring-Happy]{Happy-specific things in \tr{configure}}
\index{Configuring for Happy}
%*                                                                      *
%************************************************************************

Use \tr{--enable-happy}.  If you have Happy and GHC in the same
build tree but only want to build Happy, use \tr{--disable-ghc}.

MORE TO COME.

%************************************************************************
%*                                                                      *
\subsection[Configuring-NoFib]{NoFib-specific things in \tr{configure}}
\index{Configuring for NoFib}
%*                                                                      *
%************************************************************************

Use \tr{--enable-nofib}.  If you have NoFib and GHC in the same build
tree but only want to build the NoFib suite, use \tr{--disable-ghc}.

You may want to enable or disable various sets of tests, as
suggested by \tr{./configure --help}.  If you use \tr{--enable-all-tests},
be aware that many of them are GHC-specific.  Also, we may not have
given you all of the source :-)

%************************************************************************
%*                                                                      *
\section[STARTUP]{Running \tr{STARTUP}}
\index{STARTUP script}
%*                                                                      *
%************************************************************************

Once you've \tr{configure}d, utter the magic incantation:
\begin{verbatim}
% sh < STARTUP >& startup.log
\end{verbatim}
The reason you might want to pipe the chatter into a file is so you
can check it afterwards.  It should be pretty obvious if it is happy.
Note: it takes a little while.

\tr{STARTUP} is a simple shell script that builds \tr{mkworld}
(Makefile-generating system), \tr{literate} (literate-programming
system), and \tr{glafp-utils} (a few utility programs); then makes the
Makefiles and dependencies for everything.

If you have any problems before getting through \tr{STARTUP}, you
are probably best off re-running \tr{configure} and \tr{STARTUP}
(after fixing what was broken).

%************************************************************************
%*                                                                      *
\section[utils_install]{Installing the support software (optional)}
\index{utilities, installing}
%*                                                                      *
%************************************************************************

By default, the support software that comes with the Glasgow
tools---\tr{mkworld}, \tr{literate}, and \tr{glafp-utils}---is not
installed.  However, they're generally-useful tools, so...

If you did want to install the ``make world'' system, for example:
\begin{verbatim}
% cd <very-top>/mkworld
% make install
\end{verbatim}

If it isn't installing things where you want it to, you can either
fiddle things on the fly...
\begin{verbatim}
% make install prefix=/home/sweet/home
\end{verbatim}

If you want to install just one utility, for example \tr{lndir}:
\begin{verbatim}
% cd <very-top>/glafp-utils/scripts
% make install_lndir
\end{verbatim}

``Make world''---It slices, it dices... it's great!

%************************************************************************
%*                                                                      *
\section[arrangement-of-sources]{Arrangement of the sources}
%*                                                                      *
%************************************************************************

Once you un\tr{tar} the Glorious Haskell Compilation (GHC) system sources
and \tr{cd} into the top directory, here's a bird's-eye view of what
you should see:

\begin{tabular}{ll}
mkworld/        & ``Make world'' sub-system for configuring the system.\\
                & \\
glafp-utils/    & Utility programs and scripts used in building the distribution;\\
                & often acquired from elsewhere. \\
literate/       & Glasgow literate programming sub-system. \\
                & \\
ghc/driver/     & The driver program for GHC; \\
                & currently a perl script, \tr{ghc}. \\
                & \\
ghc/compiler/   & The Haskell compiler proper, called \tr{hsc}; \\
                & source files are in \tr{compiler/*/[A-Z]*.lhs}. \\
                & \\
ghc/runtime/    & The runtime system, including the garbage-collector(s).\\
                & \\
ghc/lib/prelude/& Source for the linked-in code for the ``standard prelude''. \\
ghc/lib/glaExts/ & Source for the linked-in code for our Glasgow extensions. \\
ghc/lib/haskell-1.3/ & Source for the linked-in code for Haskell 1.3 I/O. \\
ghc/lib/hbc/    & Source for the HBC `system library'. \\
ghc/lib/ghc/    & Source for the GHC `system library'.\\
                & \\
ghc/includes/   & The ``public'' .hi files slurped by the parser, \\
                & and .h files \tr{#include}d in generated .hc files come from.\\
                & \\
ghc/docs/       & documents; see the README file there. \\
                & \\
ghc/CONTRIB/    & reserved for contributed things \\
haggis/         & Haggis Haskell X11 GUI toolkit \\
happy/          & Happy Haskell parser generator \\
nofib/          & NoFib Haskell benchmark and test suite \\
\end{tabular}

\begin{onlystandalone}
\printindex
\end{document}
\end{onlystandalone}