--- /dev/null
+%
+% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/install_guide/Attic/installing.lit,v 1.1 1996/01/08 20:25:19 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-\{request,bugs\}\@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 GhcBuild_UserWay_a
+%$$ #define GhcBuild_UserWay_a YES
+%$$ GHC_USER_WAY_FLAG_a = -ticky
+%$$ GHC_USER_WAY_OPTS_a = -fstg-reduction-counts -O
+%$$ #endif /* ! GhcBuild_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}
projects / ghc-hetmet.git / blobdiff