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=0000000000000000000000000000000000000000;hb=1fb1ab5d53a09607e7f6d2450806760688396387;hp=19c5755153f7f19f4b384a9c4d16c168a54b485e;hpb=fa6fb09e2e4e6918eebc79ed187f32c88817c9db;p=ghc-hetmet.git diff --git a/ghc/docs/install_guide/installing.lit b/ghc/docs/install_guide/installing.lit deleted file mode 100644 index 19c5755..0000000 --- a/ghc/docs/install_guide/installing.lit +++ /dev/null @@ -1,2177 +0,0 @@ -% -% $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-.tar.gz}, where \tr{} 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--.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-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/} (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 /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} -%#% /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.. -\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}. A typical invocation might be: -\begin{verbatim} -% cd -% ./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 -% 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; 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--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 -% 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 /ghc -% make install -% cd /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 /ghc -% make -n install >& temp-log-file-to-look-at -% cd /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/ -%% 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 -% 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-.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=} 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 /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/ & 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}