+++ /dev/null
-%
-% $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/install_guide/Attic/installing.lit,v 1.5 1997/01/17 00:33:19 simonpj Exp $
-%
-\begin{onlystandalone}
-\documentstyle[11pt,literate]{article}
-\begin{document}
-\title{Installing the Glasgow Functional Programming Tools\\
-Version~2.01}
-\author{The GHC Team\\
-Department of Computing Science\\
-University of Glasgow\\
-Glasgow, Scotland\\
-G12 8QQ\\
-\\
-Email: glasgow-haskell-\{users,bugs\}\@dcs.gla.ac.uk}
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\clearpage
-\end{onlystandalone}
-
-%************************************************************************
-%* *
-\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.
-
-%************************************************************************
-%* *
-\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}.
-
-NB: For GHC~2.01, bootstrapping from \tr{.hc} files means you will get
-an all-2.01 system---possibly unduly slow. Building with GHC~0.29
-will get you a faster compiler...
-
-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~2.01, 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'' is so terrible that we won't say more about it.
-
-We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
-running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
-unsurprisingly. Both have native-code generators, for quicker
-compilations. The native-code generator for iX86 platforms (e.g.,
-Linux ELF) is {\em nearly} working; but is not turned on by default.
-
-Here's everything that's known about GHC ports, as of 2.01. We
-identify platforms by their ``canonical GNU-style'' names.
-
-Note that some ports are fussy about which GCC version you use; or
-require GAS; or ...
-
-\begin{description}
-%-------------------------------------------------------------------
-\item[\tr{alpha-dec-osf1}:]
-\index{alpha-dec-osf1: fully supported}
-(We have OSF/1 V2.0.) Fully supported, including native-code generator.
-We recommend GCC 2.6.x or later.
-
-%-------------------------------------------------------------------
-\item[\tr{sparc-sun-sunos4}:]
-\index{sparc-sun-sunos4: fully supported}
-Fully supported, including native-code generator.
-
-%-------------------------------------------------------------------
-\item[\tr{sparc-sun-solaris2}:]
-\index{sparc-sun-solaris2: fully supported}
-Fully supported, including native-code generator. A couple of quirks,
-though: (a)~the profiling libraries are bizarrely huge; (b)~the
-default \tr{xargs} program is atrociously bad for building GHC
-libraries (see \sectionref{Pre-supposed} for details).
-
-%-------------------------------------------------------------------
-\item[HP-PA box running HP/UX 9.x:]
-\index{hppa1.1-hp-hpux: registerised port}
-Works registerised. No native-code generator.
-For GCC, you're best off with one of the Utah releases of
-GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
-We think a straight GCC 2.7.x works, too.
-
-Concurrent/Parallel Haskell probably don't work (yet).
-\index{hppa1.1-hp-hpux: concurrent---no}
-\index{hppa1.1-hp-hpux: parallel---no}
-
-%-------------------------------------------------------------------
-\item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
-\index{i386-*-linux: registerised port}
-GHC~2.01 works registerised.
-You {\em must} have GCC 2.7.x or later.
-The iX86 native-code generator is {\em nearly} there, but it
-isn't turned on by default.
-
-Profiling works, and Concurrent Haskell works.
-\index{i386-*-linux: profiling---yes}
-\index{i386-*-linux: concurrent---yes}
-Parallel Haskell probably works.
-\index{i386-*-linux: parallel---maybe}
-
-On old Linux a.out systems: should be the same.
-\index{i386-*-linuxaout: registerised port}
-
-%-------------------------------------------------------------------
-\item[\tr{mips-sgi-irix5}:]
-\index{mips-sgi-irix5: registerised port}
-GHC~2.01 works registerised (no native-code generator).
-I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
-was built with \tr{--with-gnu-as}; turns out that is important!
-
-Concurrent/Parallel Haskell probably don't work (yet).
-Profiling might work, but it is untested.
-\index{mips-sgi-irix5: concurrent---no}
-\index{mips-sgi-irix5: parallel---no}
-\index{mips-sgi-irix5: profiling---maybe}
-
-%-------------------------------------------------------------------
-\item[\tr{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~2.01 hasn't been tried on a Sun3. GHC~0.26 worked registerised.
-No native-code generator.
-
-Concurrent/Parallel Haskell probably don't work (yet).
-\index{m68k-sun-sunos4: concurrent---no}
-\index{m68k-sun-sunos4: parallel---no}
-\end{description}
-
-%************************************************************************
-%* *
-\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.
-Linux, MIPS, and HP boxes are in pretty good shape.
-\Sectionref{port-info} gives the full run-down on ports or lack
-thereof.
-
-\item
-Be sure that the ``pre-supposed'' utilities are installed.
-
-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.gla.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-2.01-<platform>.tar.gz}, where \tr{<platform>} is one of:
-alpha-dec-osf2, hppa1.1-hp-hpux9, i386-unknown-linux,
-i386-unknown-solaris2, i386-unknown-freebsd,
-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-2.01-<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-2.01-sparc-sun-sunos4.tar.gz | tar xf -
-gunzip < ghc-2.01-prof-sparc-sun-sunos4.tar.gz | tar xf -
-gunzip < ghc-2.01-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 (or link to) 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
-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
-Actually setting the \tr{GLASGOW_HASKELL_ROOT} environment variable
-is a {\em bad} idea, mostly because it precludes having several
-GHC versions around at the same time.
-
-% \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/2.01/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..
-\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}. A typical invocation might be:
-\begin{verbatim}
-% cd <the-very-top-dir>
-% ./configure --prefix=/usr/local/fp \
- --with-hc=ghc-0.29 --with-mkdependHS=mkdependHS-0.29
-\end{verbatim}
-
-\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; e.g., compile GHC~2.01 with a GHC~0.29 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.
-
-(With GHC~2.01, another drawback is that the \tr{.hc} files will give
-you a 2.01-built-with-2.01---normally a good thing---but, in this case,
-probably slower than a 2.01-built-with-0.29.)
-
-% 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
-% cd ../hslibs
-% 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-2.01/ghc/driver/ghc ~/bin/alpha/ghc
-% rehash
-\end{verbatim}
-
-Compile the program, using the \tr{-v} (verbose) flag to verify that
-libraries, etc., are being found properly:
-\begin{verbatim}
-% ghc -v -o hello Main.hs
-\end{verbatim}
-
-Now run it:
-\begin{verbatim}
-% ./hello
-Hello, world!
-\end{verbatim}
-
-Some simple-but-profitable tests are to compile and run the
-notorious \tr{nfib} program, using different numeric types. Start
-with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
-\tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
-for this is distributed in \tr{ghc/misc/examples/nfib/}.
-
-For more information on how to ``drive'' GHC,
-either do \tr{ghc -help} or consult the User's Guide (distributed in
-\tr{ghc/docs/users_guide}).
-
-%************************************************************************
-%* *
-\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
-% cd <very-top>/hslibs
-% 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
-% cd <very-top>/hslibs
-% 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/HTML 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 .hc and object files
-% rm */*.hc */*.*_hc
-% find . -name '*.o' -print | xargs /bin/rm
-
-% cd hslibs/ # ditto for syslibs
-% rm */src/*.hc */src/*.*_hc
-
-% 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-2.01-src.tar.gz}) and also some extra files in
-\tr{ghc-2.01-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-2.01-src.tar.gz | tar xf -
-% gunzip -c ghc-2.01-hc-files.tar.gz | tar xf - # basic...
-% gunzip -c ghc-2.01-prof-hc-files.tar.gz | tar xf - # profiling...
-% gunzip -c ghc-2.01-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.
-
-You will probably continue by building the system libraries:
-\tr{cd hslibs; make all}...
-
-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 that we supply do {\em not} include a native-code generator.
-(They are supposed to work on and for any machine.)
-
-From here on, I presume you've installed your booted GHC as
-\tr{ghc-2.01}.
-
-You can configure as before, but using \tr{--with-hc=ghc-2.01}
-(\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-2.01/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~2.01 doesn't build with HBC.
-
-GHC~2.01 can be built with:
-\begin{description}
-\item[GHC~0.26:]
-Provided you don't use \tr{-O} (i.e., configure with
-\tr{--disable-hsc-optimised})...
-
-\item[GHC~0.29:]
-Works fine, and builds the fastest compiler; but be sure to configure
-with \tr{--with-mkdependHS=blah}, where \tr{blah} is a name to invoke
-the \tr{mkdependHS} that comes with GHC~0.29.
-
-\item[Itself:]
-It works, but the resulting compiler is slower.
-\end{description}
-
-%$$ 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.
-
-(Perl~5 is the current version; GHC is still friendly to Perl~4 as well.)
-
-Perl should be put somewhere so that it can be invoked by the \tr{#!}
-script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
-we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
-be less than 32 characters long.
-
-\item[GNU C (\tr{gcc}):]
-\index{pre-supposed: GCC (GNU C compiler)}
-\index{GCC (GNU C compiler), pre-supposed}
-The current version is 2.7.2, 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.11; we use 3.3.7. It is readily available on
-the net; I think I got it from \tr{research.att.com}, in \tr{netlib}.
-
-A PVM installation is slightly quirky, but easy to do. Just follow
-the \tr{Readme} instructions.
-
-\item[\tr{xargs} on Solaris2:]
-\index{xargs, presupposed (Solaris only)}
-\index{Solaris: alternative xargs}
-The GHC libraries are put together with something like:
-\begin{verbatim}
-find bunch-of-dirs -name '*.o' -print | xargs ar q ...
-\end{verbatim}
-Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
-of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
-time---with near-infinite rebuilding of the symbol table in
-the \tr{.a} file.
-
-The best solution is to install a sane \tr{xargs} from the GNU
-findutils distribution. You can unpack, build, and install the GNU
-version in the time the Solaris \tr{xargs} mangles just one GHC
-library.
-
-\item[\tr{bash} (Parallel Haskell only):]
-\index{bash, presupposed (Parallel Haskell only)}
-Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
-to PostScript, is written in Bash (GNU's Bourne Again shell).
-This bug will be fixed.
-
-\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
-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-mkdependHS=}{\em mkdep}:]
-\index{--with-mkdependHS configure option}
-
-Use {\em mkdep} as your \tr{mkdependHS} program. You should use the
-\tr{mkdependHS} that came with the GHC which you are probably
-specifying via \tr{--with-hc=...}.
-
-%--------------------------------------------------------------
-\item[\tr{--with-gcc=}{\em blah}:]
-\index{--with-gcc configure option}
-Use {\em blah} as my ``GNU C compiler.'' In case you have several,
-and want to chose a particular one.
-
-%--------------------------------------------------------------
-\item[\tr{--with-make=}{\em blub}:]
-\index{--with-make configure option}
-Ditto, for ``make''.
-
-%--------------------------------------------------------------
-\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.29 --with-readline-library --with-sockets-library
- # simple build with 0.29
- # For the extra libraries, you've got to have the right
- # stuff to link to.
-
-./configure --with-hc=ghc-0.29 --disable-hsc-optimised --enable-hsc-debug
- # Don't use -O on GHC itself; turn on -DDEBUG.
- # Slows things 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-HsLibs]{Haskell-libraries-specific things in \tr{configure}}
-\index{Configuring the Haskell libraries}
-%* *
-%************************************************************************
-
-The normal thing is: \tr{--enable-hslibs --with-hc-for-hslibs=in-place}.
-
-NOT DONE YET.
-
-%************************************************************************
-%* *
-\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 --with-setup=ghc}.
-If you have NoFib and GHC in the same build
-tree but only want to build the NoFib suite, use \tr{--disable-ghc}.
-
-(If you were testing HBC on NoFib, you'd do \tr{--with-setup=hbc}, of course.)
-
-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/ & Source for the linked-in code for the ``standard prelude''. \\
-ghc/includes/ & The .h files \tr{#include}d in generated .hc files.\\
- & \\
-ghc/docs/ & documents; see the README file there. \\
- & \\
-ghc/CONTRIB/ & reserved for contributed things \\
- & \\
-hslibs/ghc/ & `ghc' system library (syslib) \\
-hslibs/hbc/ & `hbc' system library \\
-hslibs/posix/ & `posix' system library \\
-hslibs/contrib/ & `contrib' system library \\
- & \\
-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