X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Finstall_guide%2Finstalling.lit;fp=ghc%2Fdocs%2Finstall_guide%2Finstalling.lit;h=13df5b500a19755ecf8419655be929dfb9d6df0c;hb=e7d21ee4f8ac907665a7e170c71d59e13a01da09;hp=0000000000000000000000000000000000000000;hpb=e48474bff05e6cfb506660420f025f694c870d38;p=ghc-hetmet.git diff --git a/ghc/docs/install_guide/installing.lit b/ghc/docs/install_guide/installing.lit new file mode 100644 index 0000000..13df5b5 --- /dev/null +++ b/ghc/docs/install_guide/installing.lit @@ -0,0 +1,2133 @@ +% +% $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-.tar.gz}, where \tr{} 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--.tar.gz}, where the +\tr{} is as above, and \tr{} 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/} (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 /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} +%#% /ghc/driver/ghc +%#% /ghc/utils/mkdependHS/mkdependHS +%#% /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 +%#% % 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 +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 +% 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 / +% 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 / +% 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 } :-) +\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--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 +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 /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 /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/ +%% 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 +% 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-.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=} 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-.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 /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 /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}