2 % $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 $
5 \documentstyle[11pt,literate]{article}
7 \title{Installing the Glasgow Functional Programming Tools\\
9 \author{The AQUA Team (scribe: Will Partain)\\
10 Department of Computing Science\\
11 University of Glasgow\\
15 Email: glasgow-haskell-\{request,bugs\}\@dcs.glasgow.ac.uk}
23 %************************************************************************
25 \section[install-intro]{Introduction}
27 %************************************************************************
29 For most people, it should be easy to install one or more of the
30 Glasgow functional-programming tools (the `Glasgow tools'), most often
31 just the Glasgow Haskell compiler (GHC). This document will guide you
32 through the installation process, and point out the known pitfalls.
34 Note: As of version~0.26, this document describes how to build {\em
35 all} of the Glasgow tools, not just the Haskell compiler. The
36 \tr{configure} script, etc., has changed to cope with this wider
37 mandate; something to bear in mind...
39 %************************************************************************
41 \subsection[install-strategy]{What to install? Starting from what?}
43 %************************************************************************
45 Building the Glasgow tools {\em can} be complicated, mostly because
46 there are so many permutations of what/why/how, e.g., ``Build Happy
47 with HBC, everything else with GHC, leave out profiling, and test it
48 all on the `real' NoFib programs.'' Yeeps!
50 Happily, such complications don't apply to most people. A few common
51 ``strategies'' serve most purposes. Pick one and proceed
54 \item[Install from binary ``bundles'':] You have one of the supported
55 platforms (e.g., Sun4 or DEC Alpha), and you just want a Haskell
56 compiler, and you don't want to do anything fancy... This choice
57 is for you. Proceed to
58 \sectionref{installing-bin-distrib}. HIGHLY RECOMMENDED!
60 \item[Build some Glasgow tools using GHC itself:] You have a supported
61 platform, but (a)~you like the warm fuzzy feeling of compiling things
62 yourself; (b)~you want to build something ``extra''---e.g., a set of
63 libraries with strictness-analysis turned off; or (c)~you want to hack
66 In this case, you should install a binary distribution
67 (as described in \sectionref{installing-bin-distrib}),
68 then build GHC with it (as described in \sectionref{building-GHC}).
70 \item[Build GHC from intermediate C \tr{.hc} files:] You cannot get a
71 pre-built GHC, so you have no choice but to ``bootstrap'' up from the
72 intermediate C (\tr{.hc}) files that we provide.
73 Building GHC on an unsupported platform falls into this category.
74 Please see \sectionref{booting-from-C}.
76 Once you have built GHC, you can build the other Glasgow tools with
79 \item[Build GHC with another Haskell compiler (e.g., HBC):] Not
80 recommended, but see \sectionref{building-with-HBC}.
83 %************************************************************************
85 \subsection[port-info]{What machines the Glasgow tools, version~0.26, run on}
88 \index{supported platforms}
89 \index{platforms, supported}
91 %************************************************************************
93 The main question is whether or not the Haskell compiler (GHC) runs on
96 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
97 work on all machines for which basic Haskell compiling is supported.
99 Some libraries may only work on a limited number of platforms; for
100 example, a sockets library is of no use unless the operating system
101 supports the underlying BSDisms.
103 %************************************************************************
105 \subsubsection{What machines the Haskell compiler (GHC) runs on}
107 %************************************************************************
108 \index{fully-supported platforms}
109 \index{native-code generator}
110 \index{registerised ports}
111 \index{unregisterised ports}
113 The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
114 generator; (b)~next best is a ``registerised''
115 port; (c)~the bare minimum is an ``unregisterised'' port.
116 ``Unregisterised'' Haskell programs are much bigger and slower,
117 but the port is much easier to get going.
119 With GHC~0.26, we add ``registerised'' support for some HP-PA, iX86,
122 We use Sun4s running SunOS~4.1.3 and DEC~Alphas running OSF/1~V2.0,
123 so those are the ``fully-supported'' platforms, unsurprisingly. Both
124 have native-code generators, for quicker compilations.
126 Here's everything that's known about GHC ports, as of 0.26. We
127 identify platforms by their ``canonical GNU-style'' names. We
130 Note that some ports are fussy about which GCC version you use; or
134 %-------------------------------------------------------------------
135 \item[\tr{alpha-dec-osf1}:]
136 \index{alpha-dec-osf1: fully supported}
137 (We have OSF/1 V2.0.) Fully supported, including native-code generator.
138 We recommend GCC 2.6.x or later.
140 %-------------------------------------------------------------------
141 \item[\tr{sparc-sun-sunos4}:]
142 \index{sparc-sun-sunos4: fully supported}
143 Fully supported, including native-code generator.
145 %-------------------------------------------------------------------
146 \item[\tr{sparc-sun-solaris2}:]
147 \index{sparc-sun-solaris2: fully supported}
148 Fully supported, including native-code generator. A couple of quirks,
149 though: (a)~the profiling libraries are bizarrely huge; (b)~the
150 default \tr{xargs} program is atrociously bad for building GHC
151 libraries (see \sectionref{Pre-supposed} for details).
153 %-------------------------------------------------------------------
154 \item[HP-PA box running HP/UX 9.x:]
155 \index{hppa1.1-hp-hpux: registerised port}
156 GHC~0.26 works registerised. No native-code generator.
157 For GCC, you're best off with one of the Utah releases of
158 GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
159 We don't know if straight GCC 2.7.x works or not.
161 Concurrent/Parallel Haskell probably don't work (yet).
162 \index{hppa1.1-hp-hpux: concurrent---no}
163 \index{hppa1.1-hp-hpux: parallel---no}
165 %-------------------------------------------------------------------
166 \item[\tr{i386-*-linuxaout} (PCs running Linux---\tr{a.out} format):]
167 \index{i386-*-linuxaout: registerised port}
168 GHC~0.26 works registerised (no native-code generator).
169 You {\em must} have GCC 2.7.x or later.
171 Concurrent/Parallel Haskell probably don't work (yet).
172 \index{i386-*-linuxaout: concurrent---no}
173 \index{i386-*-linuxaout: parallel---no}
174 \index{i386-*-linuxaout: profiling---maybe}
175 Profiling might work, but it is untested.
177 %-------------------------------------------------------------------
178 \item[\tr{mips-sgi-irix5}:]
179 \index{mips-sgi-irix5: registerised port}
180 GHC~0.26 works registerised (no native-code generator).
181 I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
182 was built with \tr{--with-gnu-as}.
184 Concurrent/Parallel Haskell probably don't work (yet).
185 Profiling might work, but it is untested.
186 \index{mips-sgi-irix5: concurrent---no}
187 \index{mips-sgi-irix5: parallel---no}
188 \index{mips-sgi-irix5: profiling---maybe}
190 %-------------------------------------------------------------------
191 \item[\tr{m68k-apple-macos7} (Mac, using MPW):]
192 \index{m68k-apple-macos7: historically ported}
193 Once upon a time, David Wright in Tasmania has actually
194 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
195 You may be able to get Thomson's from here. (Not sure that it will
196 excite you to death, but...)
198 No particularly recent GHC is known to work on a Mac.
200 %-------------------------------------------------------------------
201 \item[\tr{m68k-next-nextstep3}:]
202 \index{m68k-next-nextstep3: historically ported}
203 Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19.
204 There's probably a little bit-rot since then, but otherwise it should
205 still be fine. Had a report that things were basically OK at 0.22.
207 Concurrent/Parallel Haskell probably won't work (yet).
208 \index{m68k-next-nextstep3: concurrent---no}
209 \index{m68k-next-nextstep3: parallel---no}
211 %-------------------------------------------------------------------
212 \item[\tr{m68k-sun-sunos4} (Sun3):]
213 \index{m68k-sun-sunos4: registerised port}
214 GHC~0.26 works registerised. No native-code generator.
216 Concurrent/Parallel Haskell probably don't work (yet).
217 \index{m68k-sun-sunos4: concurrent---no}
218 \index{m68k-sun-sunos4: parallel---no}
221 %************************************************************************
223 \subsubsection{What machines the other tools run on}
225 %************************************************************************
227 Unless you hear otherwise, the other tools work if GHC works.
229 Haggis requires Concurrent Haskell to work.
230 \index{Haggis, Concurrent Haskell}
232 %************************************************************************
234 \subsection{Things to check before you start typing}
236 %************************************************************************
240 \index{disk space needed}
241 Disk space needed: About 30MB (five hamburgers' worth) of disk space
242 for the most basic binary distribution of GHC; more for some
243 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
244 Haskell libraries) might take you to 8--10 hamburgers.
246 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
247 build the basic stuff from scratch.
249 I don't yet know the disk requirements for the non-GHC tools.
251 All of the above are {\em estimates} of disk-space needs.
254 Use an appropriate machine, compilers, and things.
256 SPARC boxes and DEC Alphas running OSF/1 are fully supported.
257 \Sectionref{port-info} gives the full run-down on ports or lack
261 Be sure that the ``pre-supposed'' utilities are installed.
263 For GHC, you must have \tr{perl} to get anywhere at all. If you're
264 going for Parallel Haskell, you'll need PVM, version 3. You will
265 probably need a reasonably up-to-date GCC (GNU C compiler),
266 too---\sectionref{port-info} lists any specific requirements in this
269 If you are going to be making documents [unlikely], you'll need
270 \tr{makeindex} as well, and maybe \tr{tgrind} [unlikely]. If you edit
271 the one or two \tr{flex} files in GHC, you'll need \tr{flex}, too
274 If you end up yacc'ing the Haskell parser [unlikely], Sun's standard
275 \tr{/bin/yacc} won't cut it. Either the unbundled \tr{/usr/lang/yacc}
276 or \tr{bison} will do fine. Berkeley yacc (\tr{byacc}) won't do.
279 If you have any problem when building or installing the Glasgow tools,
280 please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If
281 you feel there is still some shortcoming in our procedure or
282 instructions, please report it.
284 For GHC, please see the bug-reporting section of the User's guide
285 (separate document), to maximise the usefulness of your report.
287 If in doubt, please send a message to
288 \tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}.
291 %************************************************************************
293 \section[installing-bin-distrib]{Installing from binary distributions (the most common case)}
294 \index{binary installations}
295 \index{installation, of binaries}
297 %************************************************************************
299 Installing from binary distributions is easiest, and recommended!
301 %************************************************************************
303 \subsection[GHC-bin-distrib]{GHC from binary distributions}
304 \index{GHC installation, from binaries}
305 \index{installation, GHC from binaries}
307 %************************************************************************
309 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
310 so you've got to ``bootstrap'' it, somehow. We provide
311 machine-generated C-files-from-Haskell for this purpose, but it's
312 really quite a pain to use them. If you must build GHC from its
313 sources, using a binary-distributed GHC to do so is a sensible way to
316 Binary distributions come in ``bundles,''\index{bundles of binary stuff}
317 one bundle per \tr{.tar.gz} file.
319 A basic GHC ``bundle'' gives you the compiler and the standard,
320 sequential libraries. The files are called
321 \tr{ghc-0.26-<platform>.tar.gz}, where \tr{<platform>} is one of:
322 alpha-dec-osf2, hppa1.1-hp-hpux9, i386-unknown-linuxaout,
323 % i386-unknown-solaris2,
324 m68k-sun-sunos4, mips-sgi-irix5,
325 sparc-sun-sunos4, sparc-sun-solaris2.
327 There are plenty of ``non-basic'' GHC bundles. The files for them are
328 called \tr{ghc-0.26-<bundle>-<platform>.tar.gz}, where the
329 \tr{<platform>} is as above, and \tr{<bundle>} is one of these:
331 \item[\tr{prof}:] Profiling with cost-centres. You probably want this.
333 \item[\tr{conc}:] Concurrent Haskell features. You may want this.
335 \item[\tr{par}:] Parallel Haskell features (sits on top of PVM).
336 You'll want this if you're into that kind of thing.
338 \item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
339 (hmm... mainly for implementors).
341 \item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
342 information about ``what happened when I ran this program''---really
345 \item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
347 \item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell.
350 One likely scenario is that you will grab {\em three} binary
351 bundles---basic, profiling, and concurrent. Once you have them,
352 unpack them all together in the same place, thusly:
356 gunzip < ghc-0.26-sparc-sun-sunos4.tar.gz | tar xf -
357 gunzip < ghc-0.26-prof-sparc-sun-sunos4.tar.gz | tar xf -
358 gunzip < ghc-0.26-conc-sparc-sun-sunos4.tar.gz | tar xf -
361 If you unpacked the files in a way that does {\em not} preserve
362 modification times (e.g., used the \tr{m} option to \tr{tar}---why on
363 earth you might do this, I cannot imagine), then please unpack them
364 again :-) The timestamps on the files are (regrettably) important.
366 %To check that you have all the pre-supposed utilities, please see
367 %\sectionref{Pre-supposed}.
369 Here's what to do with the stuff in each directory, once unpacked.
370 % (If your binary distribution, doesn't look like this---don't despair!
371 % It may be a ``dumped-from-a-build'' distribution; please see
372 % \sectionref{dumped-from-build}.)
375 %---------------------------------------------------------------------
376 \item[\tr{bin/<platform>} (sometimes just \tr{bin/}):]
377 Copy these executables so that they will be in users' PATHs.
379 %---------------------------------------------------------------------
381 Move this directory, in toto, to wherever you want it to live.
382 It should still be called \tr{lib}.
384 %---------------------------------------------------------------------
386 This is the full \tr{docs} tree. Just follow the normal instructions,
387 in \sectionref{make-docs}.
390 Things you need to fiddle so the tools will spring to life:
393 \tr{rehash} (csh users), so your shell will see the new stuff in your
398 Edit your \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts:
399 (a)~Create a correct \tr{#!...perl} first line in each one. (Ask a
400 Unix-friendly person to help you, if you don't know what a
401 \tr{#!}-line is.) (b) Find the line that looks something like:
403 # $ENV{'GLASGOW_HASKELL_ROOT'} = '/some/absolute/path/name';
405 Remote the comment symbol (\tr{#}) on the front, and change the
406 path name to be the right thing.
408 So, if your ``lib'' files are now in \tr{/home/myself/lib/ghc/...},
409 then you should set \tr{GLASGOW_HASKELL_ROOT} to \tr{/home/myself}.
413 Set your \tr{GLASGOW_HASKELL_ROOT} environment variable, and
414 don't edit the \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts
417 It's better to edit the scripts; that way, it's once for all.
420 You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
422 % cd <wherever-the-lib-files-are-now>/ghc/0.26/sparc-sun-sunos4
423 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
425 ? # or, on some machines: ar s $i
430 Once done, test your ``installation'' as suggested in
431 \sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you
432 can see exactly what pathnames it's using.
434 If things don't work, double-check your hand-edited path
435 names. Things will go catastrophically wrong as long as they are
439 %************************************************************************
441 \subsection[non-GHC-bin-distrib]{Other tools from binary distributions}
443 %************************************************************************
447 All of the above is for GHC bundles. For other tools, the same
448 principles apply: get the binary bundles you want, then unpack them
449 all together in the same place.
451 %************************************************************************
453 %\subsection[dumped-from-build]{Installing a ``dumped-from-build'' binary distribution (some platforms)}
455 %************************************************************************
457 %#% Sometimes, a binary distribution is taken directly from a GHC
458 %#% ``build.'' An example is the Solaris distribution. You can tell from
459 %#% the layout of the files.
461 %#% The setup required is nearly the same as a ``regular'' binary
462 %#% distribution; only some names are different.
463 %#% \begin{enumerate}
465 %#% Get the user-executable scripts into your PATH, either by copying it
466 %#% or by linking to it. These are in:
468 %#% <topdir>/ghc/driver/ghc
469 %#% <topdir>/ghc/utils/mkdependHS/mkdependHS
470 %#% <topdir>/ghc/utils/hstags/hstags
474 %#% Set the \tr{GLASGOW_HASKELL_ROOT} environment variable for the three
475 %#% scripts above, in the manner outlined in the previous section.
478 %#% Possibly re-\tr{ranlib}'ing your \tr{*.a} files:
481 %#% % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
483 %#% % # or, on some machines: ar s $i
488 %#% Don't forget to test it!
491 %************************************************************************
493 \section[checklist]{Building Glasgow tools from source: a checklist}
495 %************************************************************************
499 Install any pre-supposed utility programs that you do not have at your
500 site. You have to do this ``by hand.'' It's not hard, and these are
501 things you want to have anyway. Please see \sectionref{Pre-supposed}.
504 Be sure you have a suitable Haskell compiler, or else the intermediate
505 C (\tr{.hc}) files. In some cases, you might want an alternative set
506 of interface (\tr{.hi}) files (quicker than generating a fresh set).
507 \Sectionref{install-strategy} lists the various strategies you might
510 If you don't have a Haskell compiler, the most painless option is to
511 use a binary-distributed GHC to compile Glasgow tools (including GHC
512 itself) from source. Installing a binary distribution (the first
513 step) is described in \sectionref{installing-bin-distrib}.
516 You might want to write-protect your source files at this point:
518 cd <the-very-top-dir>
519 find . -type f \! -name \*.hi \! -name \*.hc \! -name \*.jm -print \
524 Run the \tr{configure} script. It is a shell script that looks around
525 to find out things about your system. You can see the \tr{configure}
526 options by passing it a \tr{--help} flag, or by reading
527 \sectionref{Configuring}.
530 Once configured, build the basic support utilities and make your
531 Makefiles, including the automagically-created dependencies between
532 files. The near-universal incantation is:
534 % cd <the-very-top-dir>
535 % sh < STARTUP >& startup.log # and chk the log afterwards!
539 Build the Glasgow tools you are interested in, as \tr{STARTUP} suggests:
541 % cd <the-very-top-dir>/<tool>
542 % make all >& make.log # time to go to lunch!
544 Consult the list of known pitfalls (\sectionref{build-pitfalls}) if
545 something goes wrong.
548 Test what you've built, enough to know that it's working.
551 Actually install the tools, if you wish:
553 % cd <the-very-top-dir>/<tool>
558 Make and/or install the documentation.
561 Save a copy of your \tr{config.status} file, for the next
562 even-more-wonderful release!
565 If you're finished, tidy up after yourself [\tr{make clean}], if you
568 Alternatively, \tr{/bin/rm -rf <tool>} :-)
571 %************************************************************************
573 \section[building-GHC]{Building the Glasgow Haskell Compiler (GHC)}
574 \index{GHC installation, from sources}
576 %************************************************************************
578 %************************************************************************
581 \section{Building GHC from source, compiling it with itself}
582 \index{building GHC with itself}
583 \index{booting GHC with itself}
585 %************************************************************************
587 This section describes how to build GHC from source. You would do
588 this if (a)~there is no ``canned'' binary distribution for your
589 machine, (b)~the binary distribution omits features that you want,
590 (c)~you want to make changes to GHC and them build them in, or
591 (d)~you like torturing yourself.
593 This blow-by-blow description follows the general checklist in
594 \sectionref{checklist}.
596 %************************************************************************
598 \subsection[Right-compiler-and-files]{Do you have a suitable compiler and/or \tr{.hc} files and/or \tr{.hi} files?}
599 \index{booting GHC, files needed}
601 %************************************************************************
603 We now proceed through each installation step, carefully.
605 Because the compiler heart of Glorious Glasgow Haskell is written in
606 Haskell, you have to use some ``bootstrapping'' mechanism.
608 Your best choice, if available, is to use a binary distribution for
609 your platform; i.e., compile GHC~0.26 with a GHC~0.26 that we have
610 provided. Please see \sectionref{installing-bin-distrib} for how to
611 install a binary distribution.
613 Your remaining choice is to use the intermediate C (\tr{.hc}) files that we
614 supply. This is the {\em only} choice for anyone trying to port to
615 a new or weakly-supported system.
617 The main drawback of the supplied-\tr{.hc} approach is that you will
618 have a lot of very bulky intermediate files on your disk for a while.
620 One obscure note: if you're going to build GHC to have a native-code
621 generator, you're well advised to get a suitable set of interface
622 files (to save making them yourself). Please see \sectionref{Compiler_reconfig}
623 if you plan to end up with a native-code generator.
625 % If you have to boot from C (\tr{.hc}) files, you should follow the
626 % directions in \sectionref{booting-from-C}.
628 % We also supply parts of the system pre-compiled to C (in \tr{.hc}
629 % files). This is partly to save you work (you don't have to wait for
630 % them to compile yourself) and partly because this is how we will
631 % eventually supply the self-compiling compiler (when that's ready).
632 % In any case, if you slurped the \tr{.tar.gz} file, you should, {\em in
633 % the same directory as before}, do...
635 % % gunzip -c ghc-<version>-hc-files.tar.gz | tar xfv -
638 %************************************************************************
640 \subsection{Write-protecting your source files}
641 \index{write-protecting source files}
643 %************************************************************************
645 At this point, some people like to write-protect their source files against
649 find . -type f \! -name '*.hi' \! -name \*.hc \! -name '*.jm' -print \
653 %************************************************************************
655 \subsection{Running \tr{configure} and \tr{STARTUP} for GHC}
656 \index{configure, for GHC}
657 \index{STARTUP, for GHC}
659 %************************************************************************
661 The \tr{configure} script finds out things about your machine. It
662 also allows you to specify features to include/exclude from your GHC
665 Please see \sectionref{Configuring} for all about \tr{configure}, and
666 \sectionref{Configuring-GHC} for details of GHC configuring (including
669 Once \tr{configure} runs successfully, do as it says and do
672 %************************************************************************
674 \subsection{Build the compiler!}
675 \index{make all, for GHC}
677 %************************************************************************
679 Do the main GHC build, just as \tr{STARTUP} suggests:
682 % make all >& make.log
684 If this fails or something seems suspicious, check the ``known
685 pitfalls'' (\sectionref{build-pitfalls}). If you can't figure out how
686 to proceed, please get in touch with us.
688 If you have to restart the build, for whatever reason, you are just as
689 well to make the whole thing; i.e., re-do as described above. (Well,
690 the \tr{compiler} and \tr{lib} subdirectories are the last two; if the
691 build ``dies'' in one of them, it is usually safe to finish the job by
694 %************************************************************************
696 \subsection[GHC_test]{Test that GHC seems to be working}
697 \index{testing a new GHC}
699 %************************************************************************
701 The way to do this is, of course, to compile and run {\em this} program
702 (in a file \tr{Main.hs}):
704 main = putStr "Hello, world!\n"
707 First, give yourself a convenient way to execute the driver script
708 \tr{ghc/driver/ghc}, perhaps something like...
710 % ln -s /local/src/ghc-0.26/ghc/driver/ghc ~/bin/sun4/ghc
714 Compile the program, using the \tr{-v} (verbose) flag to verify that
715 libraries, etc., are being found properly:
717 % ghc -v -o hello -fhaskell-1.3 Main.hs
726 Some simple-but-profitable tests are to compile and run the
727 notorious \tr{nfib} program, using different numeric types. Start
728 with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
729 \tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
730 for this is distributed in \tr{ghc/misc/examples/nfib/}.
732 For more information on how to ``drive'' GHC,
733 either do \tr{ghc -help} or consult the User's Guide (distributed in
734 \tr{ghc/docs/users_guide}).
736 %************************************************************************
738 \subsection[GHC_install]{Actually installing GHC}
739 \index{make install, GHC}
740 \index{installing, GHC}
742 %************************************************************************
744 ``Installing GHC'' means copying the files required to run it to their
745 ``permanent home.'' You can then delete, or at least tidy up, your
748 If you have no reason to install GHC, you can execute directly out of
749 the source tree, as sketched in the section above
750 (\sectionref{GHC_test}).
752 Assuming that everything's OK so far, all you need to do is:
758 If you're a little dubious (as I usually am), you can always do a
762 % make -n install >& temp-log-file-to-look-at
765 In both cases, if something breaks, it's a {\em bug}.
768 %************************************************************************
770 \subsection[make-docs]{Installing the GHC documentation (optional)}
771 \index{documentation, making}
772 \index{make docs, GHC}
773 \index{installing documentation}
775 %************************************************************************
777 Because our documentation is in DVI/Info formats, and because there is
778 no standard practice about how such documents are ``installed,'' we
779 haven't tried to automate this (at least not enough that we promise it
782 You can find all the documentation in the distribution with:
785 % find . \( -name '*.dvi' -o -name '*.info' -o -name '*.html' \) -print
788 If you have a standard place to put such files, just copy
789 them there. (Better ideas welcome.)
791 The following ``man'' pages are hidden around in the distribution:
793 ghc/utils/hp2ps/hp2ps.1
794 literate/info-utils/info.1
795 glafp-utils/scripts/mkdirhier.man
796 glafp-utils/scripts/lndir.man
798 Please install them by hand if you need to.
800 %There are various pieces of GHC whose code can be formatted
801 %``literately.'' The usual procedure is...
804 %% make depend # VERY IMPORTANT for literate docs!
805 %% make docs # or more directly....
806 %% make whatever.dvi # or, for Info freaks,...
807 %% make whatever.info
810 %For ``chunks'' of the compiler proper, in \tr{ghc/compiler}, you will
811 %need to make a \tr{Makefile} for them first:
814 %make Makefile SUBDIRS=prelude # for example...
816 %make depend # i.e., as before
819 %Directories for which this {\em might} (I emphasize: `MIGHT') work are ...
824 %podizeCore/Jmakefile
829 %Remember: an unpatched perl 4.035 will {\em crash} on making many of
830 %our ``literate'' Info files. (The current version, 4.036, will not.)
832 %$$ Note: Because we make our Info files by going through Texinfo format,
833 %$$ you can use \tr{texi2html} to produce HTML files. A
834 %$$ minisculely-hacked version is in the distribution in
835 %$$ \tr{literate/texi2html/texi2html}.
837 %************************************************************************
839 \subsection[clean-up]{Cleaning up after yourself}
840 \index{make clean, GHC}
841 \index{cleaning up afterwards}
843 %************************************************************************
845 \tr{make clean} is the basic command to tidy things up. However: if
846 you do this, {\em you will not be able to execute directly out of the
847 source tree thereafter!} (as sketched in \sectionref{GHC_test}). Nor will
848 you be able to make documents, etc.---you would have to re-build parts
851 If you want to execute out of the source tree but would like to clear
852 off lots and lots of stuff, you can do:
854 % cd ghc/lib # scrub library C and object files
856 % find . -name '*.o' -print | xargs /bin/rm
858 % cd ghc/compiler # scrub compiler object files
860 % rm */*.hc # if you have been keeping them around
862 (You can scrub the object files in \tr{ghc/runtime} similarly---except
863 \tr{main/TopClosure*.o}.)
865 %\tr{make veryclean} is the command to clear off everything that can be
866 %safely cleared off. Not recommended (inadequately tested).
868 %************************************************************************
870 \section[booting-from-C]{Booting/porting from C (\tr{.hc}) files}
871 \index{building GHC from .hc files}
872 \index{booting GHC from .hc files}
874 %************************************************************************
876 This section is for people trying to get GHC going by using the
877 supplied intermediate C (\tr{.hc}) files. This would probably be
878 because no binaries have been provided, or because the machine
879 is not ``fully supported.''
881 To boot from C (\tr{.hc}) files, you need the regular source distribution
882 (\tr{ghc-0.26-src.tar.gz}) and also some extra files in
883 \tr{ghc-0.26-hc-files.tar.gz}. DON'T FORGET any extra \tr{.hc}
884 files for profiling, concurrent, parallel, ...
886 Whatever you want to build, just unpack all the files ``together'':
889 % gunzip -c ghc-0.26-src.tar.gz | tar xf -
890 % gunzip -c ghc-0.26-hc-files.tar.gz | tar xf - # basic...
891 % gunzip -c ghc-0.26-prof-hc-files.tar.gz | tar xf - # profiling...
892 % gunzip -c ghc-0.26-conc-hc-files.tar.gz | tar xf - # concurrent...
896 For the ``it's been tried before'' machines, the normal
897 configure/build procedure will probably work; just keep your eyes
900 WORD OF WISDOM: Be sure you have a suitable GCC (GNU C compiler); please
901 see \sectionref{port-info} for any specific requirements for your machine.
903 You'll need plenty of disk space to do this whole procedure!
905 %$$ %************************************************************************
907 %$$ \subsection[boot-file-fiddling]{Unpack; then fiddle files before booting}
909 %$$ %************************************************************************
911 %$$ Unpack the relevant files for booting as described above.
913 %$$ If you are on a never-seen-before platform, then there is a little
914 %$$ machine-specific code/stuff scattered around the GHC files, which will
915 %$$ need to be updated before you get started.
917 %$$ \begin{description}
918 %$$ %---------------------------------------------------------------------
919 %$$ \item[Change \tr{configure}, so it recognizes your machine:]
920 %$$ Add the obvious stuff if it says ``Unrecognised platform for GHC.''
922 %$$ If you are teaching GHC how to ``registerise'' on a new platform, you
923 %$$ will also need to make sure the variable @GhcWithRegisterised@ is set
926 %$$ %---------------------------------------------------------------------
927 %$$ \item[Change {\em two} copies of \tr{platform.h.in}:]
928 %$$ In the obvious way. They are in \tr{ghc/includes/} and \tr{mkworld/}.
930 %$$ %---------------------------------------------------------------------
931 %$$ \item[Floating-pointness:]
932 %$$ Grep for \tr{_TARGET} in \tr{ghc/includes/*.*h} and make suitable
935 %$$ One change you will certainly make is in \tr{StgMacros.lh}, to decide
936 %$$ the inclusion of \tr{ieee-flpt.h} and \tr{BIGENDIAN}.
938 %$$ Please use the CPP symbols defined in \tr{platform.h.in}!
940 %$$ %---------------------------------------------------------------------
941 %$$ \item[64-bitness:]
942 %$$ Again, grepping for \tr{_TARGET} in \tr{ghc/includes/*.lh} will find
943 %$$ the places that need adjusting. \tr{GhcConstants.lh} and
944 %$$ \tr{StgTypes.lh} are two places that will need tweaking, for example.
946 %$$ %---------------------------------------------------------------------
947 %$$ \item[``Registerizing'' magic:]
948 %$$ This is the platform-specific stuff in \tr{COptJumps.lh},
949 %$$ \tr{COptWraps.lh}, and \tr{MachRegs.lh} in \tr{ghc/includes}.
951 %$$ If you are doing an initial unregisterised boot for your platform, you
952 %$$ don't need to mess with these files at all.
954 %$$ \Sectionref{real-version-from-init-boot} discusses how to get a
955 %$$ ``registerised'' version of GHC going. (Much trickier, but much
956 %$$ faster. [0.26: and the documentation is OUT-OF-DATE])
958 %$$ %---------------------------------------------------------------------
959 %$$ \item[Host/target platforms in the driver:]
960 %$$ Grep for all occurrences of \tr{$HostPlatform} and \tr{$TargetPlatform}
961 %$$ in \tr{ghc/driver/*.lprl}.
963 %$$ Don't worry about the \tr{process_asm_block} stuff in
964 %$$ \tr{ghc-split.lprl}. Not used in a straight ``unregisterised''
967 %$$ %---------------------------------------------------------------------
968 %$$ \item[Target-specific GCC flags in the driver:]
970 %$$ The main thing to worry about in \tr{ghc.lprl} is the section on how
971 %$$ to ``Add on machine-specific C-compiler flags.''
972 %$$ You may want to add something {\em vaguely} like:
975 %$$ } elsif ($TargetPlatform =~ /^mips-dec-ultrix/) {
976 %$$ unshift(@CcBoth_flags, ('-G0', '-static')) if $GccAvailable;
979 %$$ Explanations: (1)~Static linking {\em tends} to give less problems, so
980 %$$ it is a reasonable choice for an initial attempt.
982 %$$ (2)~In processing
983 %$$ the intermediate C (\tr{.hc}) files, you are compiling some {\em huge}
984 %$$ wads of C. Sadly, quite a few systems don't cope well with this, and
985 %$$ more than a few silently produce object files that won't link. GCC
986 %$$ usually provides some platform-specific flag that says ``generate code
987 %$$ that will work no matter how big the files are''. The \tr{-G0} for
988 %$$ DEC MIPS boxes is an example. If your system has such restrictions,
989 %$$ insert some magic {\em here}!
990 %$$ \end{description}
992 %************************************************************************
994 \subsection{Do \tr{configure}; \tr{sh < STARTUP}; \tr{cd ghc; make all}; test it!}
995 \index{configure, GHC with .hc files}
996 \index{make all, GHC with .hc files}
998 %************************************************************************
1000 Go ahead and try \tr{configure}, as described \Sectionref{Configuring}
1001 (GHC specifics in \Sectionref{Configuring-GHC}).
1003 The key \tr{configure} option is \tr{--with-hc=c}. A typical
1004 going-via-C invocation might be:
1007 % ./configure --prefix=/local/fp --with-hc=c # basic + profiling
1010 Other common possibilities might be:
1013 % ./configure --with-hc=c --disable-profiling # basic only
1015 % ./configure --with-hc=c --enable-concurrent --enable-parallel
1016 # basic + profiling + concurrent + parallel
1019 %$$ One likely reason it won't work is it will say it never heard of your
1020 %$$ machine. Just edit the script and carry on! (As always, please send
1021 %$$ us the changes.)
1023 Next, run \tr{STARTUP} in the usual way, as described in
1024 \Sectionref{STARTUP}.
1026 It's now time to type \tr{cd ghc; make all}! This ``should'' work,
1027 especially, on a known machine. Also, it can take a VERY long time
1028 (esp. on oldish machines), so it's good to run overnight, on a quiet
1029 machine, nice'd, etc., etc.
1031 When it's all built, test your alleged GHC system, as suggested in
1032 \sectionref{GHC_test}.
1034 %$$ What you should end up with, built in this order: (1)~a runtime system
1035 %$$ [\tr{ghc/runtime/libHSrts_ap.a}]; (2)~Prelude libraries
1036 %$$ [\tr{ghc/lib/libHS_ap.a} and \tr{ghc/lib/libHShbc_ap.a}]; and (3)~a
1037 %$$ compiler [\tr{ghc/compiler/hsc}] (which needs the first two).
1039 %$$ (Umm... if you are on a supported platform, but compiling via C, then
1040 %$$ the \tr{*.a} suffixes will be \tr{_ap_o.a} (regular) and \tr{_p.a}
1043 %$$ %************************************************************************
1045 %$$ \subsubsection{A pre-emptive \tr{hello, world} test}
1047 %$$ %************************************************************************
1049 %$$ On an unsupported platform,
1050 %$$ You very well may want to {\em kill the compilation} once
1051 %$$ \tr{libHSrts_ap.a} and \tr{libHS_ap.a} are built, to do a little
1052 %$$ pre-emptive testing: time to run \tr{Hello, world!}. Using
1053 %$$ \tr{ghc/CONTRIB/hello.hc}...
1054 %$$ \begin{verbatim}
1055 %$$ % .../ghc/driver/ghc -c -g hello.hc
1056 %$$ % .../ghc/driver/ghc -v -o hello -g hello.o
1060 %$$ If you have any trouble to do with ``consistency checking,'' just
1061 %$$ avoid it, with the \tr{-no-link-chk} flag.
1063 %$$ If \tr{hello} crashes/breaks, it's time for Ye Olde Debugger, or
1064 %$$ perhaps Ye Older Cry for Help...
1066 %$$ If things are OK and if you {\em did} kill the compilation, just re-do
1067 %$$ \tr{make} to finish the job (build any other libraries, then the
1068 %$$ compiler binary \tr{ghc/hsc}).
1070 %$$ %************************************************************************
1072 %$$ \subsubsection[init-boot-hsc]{Finishing the initial boot}
1074 %$$ %************************************************************************
1076 %$$ If you manage to get a \tr{ghc/hsc} binary (usually huge), then...
1077 %$$ YOU HAVE A HASKELL COMPILER, albeit big and slow! So test it,
1078 %$$ ``from the sources,'' before installing it:
1079 %$$ \begin{verbatim}
1081 %$$ main = print ((10001 - 30002)::Integer)
1082 %$$ -- or any other program(s) you want...
1084 %$$ % .../ghc/driver/ghc -v -g -c test.hs
1085 %$$ % .../ghc/driver/ghc -v -g -o test test.o
1088 %$$ (Note how I fiendishly included a \tr{-g}, in case I had to throw a
1089 %$$ debugger at it...)
1091 %$$ Of course, you {\em may not} have a \tr{ghc/hsc} binary---something
1092 %$$ went wrong. The most likely cause is a compiler/assembler/linker
1093 %$$ failure due to the HUGE size of this program. Please revisit the
1094 %$$ discussion about this towards the end of
1095 %$$ \sectionref{boot-file-fiddling}. Sadly, if you have to tweak
1096 %$$ C-compiler/whatever flags, you may have to rebuild all the
1097 %$$ libraries/compiler again; the following is sufficient to clear
1098 %$$ off everything for a fresh start (NB: don't do \tr{make clean}):
1099 %$$ \begin{verbatim}
1100 %$$ % cd ghc/runtime # clear off RTS
1101 %$$ % make clean SUBDIRS=foo # but avoid clearing GMP lib
1104 %$$ % cd ../compiler
1108 %$$ %************************************************************************
1110 %$$ \subsubsection[installing-init-boot]{`Installing' the initial boot}
1112 %$$ %************************************************************************
1114 %$$ If you are satisfied that things are working, {\em possibly install} the
1115 %$$ initial booted version. The main point is: save the precious files
1116 %$$ you've just created.
1118 %$$ Should you choose {\em not to install}, be sure to secure these files
1119 %$$ somewhere/somehow:
1120 %$$ \begin{verbatim}
1121 %$$ ghc/compiler/hsc # compiler
1122 %$$ ghc/runtime/libHSrts_ap.a # RTS things
1123 %$$ ghc/lib/libHS_ap.a # prelude library
1126 %$$ Should you install, the comments about `normal' installing, in
1127 %$$ \Sectionref{GHC_install}, do apply. It should come down to
1128 %$$ something like...
1129 %$$ \begin{verbatim}
1131 %$$ % make -n install >& temp-log-file-to-look-at # trial run: chk it out!
1132 %$$ % make install # the real thing...
1135 %$$ (I'd probably do the install by hand, if at all; let me know if you're
1136 %$$ worried about the exact incantations.)
1138 %$$ %************************************************************************
1140 %$$ \subsubsection[testing-init-boot]{Testing the initial boot}
1142 %$$ %************************************************************************
1144 %$$ It wouldn't be a bad idea, especially on an unusual machine; I usually
1145 %$$ just skip this part, though :-)
1147 %$$ %************************************************************************
1149 %$$ \subsection[split-libs]{Getting ``splitting'' going on your Prelude libraries}
1151 %$$ %************************************************************************
1155 %$$ %************************************************************************
1157 %$$ \subsection[real-version-from-init-boot]{Getting a ``registerised'' version going}
1159 %$$ %************************************************************************
1161 %$$ Version 0.26: THIS DOCUMENTATION IS OUT-OF-DATE. (Sigh)
1163 %$$ %************************************************************************
1165 %$$ \subsubsection[registerised-magic-files]{Setting up files for `registerizing'}
1167 %$$ %************************************************************************
1169 %$$ It's time to jiggle some files related to GCC-magic-optimisation.
1170 %$$ {\em This is real work, folks.} What follows is a {\em rough} guide to
1171 %$$ what needs looking at.
1173 %$$ \begin{description}
1174 %$$ %---------------------------------------------------------------------
1175 %$$ \item[\tr{ghc/includes/MachRegs.lh}:]
1176 %$$ This maps ``STG registers'' (Hp, SpA, TagReg, etc.) to machine
1177 %$$ registers on a platform-by-platform basis.
1178 %$$ If you can't figure it out, you'd probably better ask.
1180 %$$ We are using a GCC extension to put C global variables in specific
1181 %$$ registers; see the \tr{Global Reg Vars} node in the GCC documentation.
1183 %$$ You should get the idea from the settings for our ``fully supported''
1184 %$$ platforms, but you will need to know/learn something about your
1185 %$$ hardware and your GCC (e.g., what registers it snaffles for itself).
1187 %$$ One way I went about learning these register secrets was to try the
1188 %$$ following test file (a Sun3 version here, \tr{regs3.hc}):
1189 %$$ \begin{verbatim}
1190 %$$ #define StgPtr long int *
1192 %$$ register StgPtr FooL0 __asm__("a0");
1193 %$$ register StgPtr FooL1 __asm__("a1");
1194 %$$ register StgPtr FooL2 __asm__("a2");
1195 %$$ register StgPtr FooL3 __asm__("a3");
1196 %$$ register StgPtr FooL4 __asm__("a4");
1197 %$$ register StgPtr FooL5 __asm__("a5");
1198 %$$ register StgPtr FooL6 __asm__("a6");
1199 %$$ register StgPtr FooL7 __asm__("a7");
1201 %$$ register StgPtr FooG0 __asm__("d0");
1202 %$$ register StgPtr FooG1 __asm__("d1");
1203 %$$ register StgPtr FooG2 __asm__("d2");
1204 %$$ register StgPtr FooG3 __asm__("d3");
1205 %$$ register StgPtr FooG4 __asm__("d4");
1206 %$$ register StgPtr FooG5 __asm__("d5");
1207 %$$ register StgPtr FooG6 __asm__("d6");
1208 %$$ register StgPtr FooG7 __asm__("d7");
1213 %$$ return (x + 42);
1216 %$$ Then compile it repeatedly with your new driver, e.g.,
1217 %$$ \tr{ghc-boot-me -v -S regs3.hc}, removing register declarations that
1218 %$$ offend it. Note: GCC's error messages about these register things
1219 %$$ can be less than totally enlightening.
1221 %$$ Note: don't worry about warnings that you're stealing a
1222 %$$ ``call-clobbered'' (caller-saves) register. These are stealable,
1223 %$$ though some extra work may be required.
1225 %$$ %---------------------------------------------------------------------
1226 %$$ \item[\tr{ghc/includes/COptJumps.lh}:]
1227 %$$ The name of the game, essentially, is for the @JMP_@ macro to turn
1228 %$$ into a simple jump instruction. Also, through fiendish collaboration
1229 %$$ with the assembly-language post-processor in the driver (coming up
1230 %$$ soon...), we're going to rip out all the pushing/popping to do with
1233 %$$ You {\em may} need to do something as on 680x0s, where we inject
1234 %$$ beginning-of- and end-of-real-code markers, which gives the post-processor
1235 %$$ something to look out for and tidy up around.
1237 %$$ You also need to define some mini-interpreter-related macros. These
1238 %$$ are discussed under \tr{StgMiniInt.lc} (below).
1240 %$$ %---------------------------------------------------------------------
1241 %$$ \item[\tr{ghc/includes/COptWraps.lh}:]
1243 %$$ The macro @STGCALL1(f,a)@ is defined here; it almost certainly should
1244 %$$ just be \tr{callWrapper(f,a)} (where the magical routine @callWrapper@
1245 %$$ is yet to come).
1247 %$$ %---------------------------------------------------------------------
1248 %$$ \item[\tr{ghc/driver/ghc-asm-<arch>.lprl}:]
1249 %$$ This is the notorious ``optimised assembler post-processor.'' You
1250 %$$ need to create a suitable \tr{require}-able file (if you haven't
1251 %$$ already), add a mention in the \tr{Jmakefile}, and add suitable code
1252 %$$ in the driver, \tr{ghc.lprl} to invoke it.
1254 %$$ This is really quite horrible for a SPARC; we have to shut down the
1255 %$$ register-window mechanism {\em entirely}, by ripping out all the
1256 %$$ \tr{save} and \tr{restore} instructions.
1258 %$$ We also go to lots of trouble to move info tables next to entry code,
1259 %$$ elide slow and fast entry-point routines, and probably some things
1260 %$$ I've forgotten about.
1262 %$$ Ask if you are desperately confused...
1264 %$$ Perhaps it will be less gruesome for your machine!
1266 %$$ Don't forget to test it with \tr{-g} turned on (lots of \tr{\.stab?}
1267 %$$ lines suddenly appear)...
1269 %$$ %---------------------------------------------------------------------
1270 %$$ \item[\tr{CallWrap_C.lc} or \tr{CallWrapper.ls}, in ghc/runtime/c-as-asm/:]
1272 %$$ These files have register saving/restoring code. For a SPARC, quite a
1273 %$$ bit has to be written in assembly language (\tr{CallWrapper.ls}), to
1274 %$$ avoid register windowing; but, for other machines, the C versions
1275 %$$ (\tr{CallWrap_C.lc}) should work fine.
1277 %$$ Look at the generated assembly-language very carefully!
1279 %$$ %---------------------------------------------------------------------
1280 %$$ \item[ghc/runtime/c-as-asm/StgMiniInt.lc:]
1282 %$$ You need to manage to create entry points named @miniInterpret@ and
1283 %$$ @miniInterpretEnd@, the former to jump off into threaded code; the
1284 %$$ latter to come back to.
1286 %$$ You may be able to do something quite simple---it's not bad either for
1287 %$$ mc680x0s or SPARCs---but you will want to inspect the assembler output
1288 %$$ before declaring victory.
1290 %$$ In the SPARC case, it uses a macro (@MINI_INTERPRETER_END_IS_HERE@)
1291 %$$ defined in \tr{imports/COptJumps.lh}.
1292 %$$ \end{description}
1294 %$$ %************************************************************************
1296 %$$ \subsubsection[testing-registerisation]{Initial testing of a `registerisation'}
1298 %$$ %************************************************************************
1300 %$$ {\em How to begin testing this registerised stuff:}
1302 %$$ Make sure your imports files are up-to-date:
1303 %$$ \begin{verbatim}
1304 %$$ % cd ghc/includes
1308 %$$ Park yourself in your driver subdirectory and ...
1309 %$$ \begin{verbatim}
1310 %$$ % cd ghc/driver # park
1311 %$$ % make Makefile # if you changed "only4-ghc.ljm"...
1312 %$$ % make # just to be sure
1314 %$$ % cp ../compiler/utils/Util.hc temp.hc # grab a test file;
1315 %$$ # you may want to chop it down
1316 %$$ % ghc-boot-me -v -S -ddump-raw-asm temp.hc # see what happens!
1319 %$$ (The \tr{-ddump-raw-asm} option shows you, on stderr, what comes
1320 %$$ directly out of GCC. That's what your post-processing mangler has to
1323 %$$ {\em Going further on testing this stuff:}
1325 %$$ Another good place to practice is \tr{ghc/runtime}; so, for example:
1326 %$$ \begin{verbatim}
1327 %$$ % cd ghc/runtime
1330 %$$ % make libHSrts_ap_o.a
1333 %$$ The .s output from \tr{main/StgUpdate.lhc} can be particularly
1334 %$$ enlightening, in that, if you are going to have register spills (e.g.,
1335 %$$ because your registerisation choices left GCC with too few with which
1336 %$$ to generate good code), you will see it on this file.
1338 %$$ Don't forget: you need a working \tr{CallWrapper.ls} and
1339 %$$ \tr{StgMiniInt.lc} (both in \tr{c-as-asm}) before this registerised
1340 %$$ stuff will actually run.
1342 %$$ %************************************************************************
1344 %$$ \subsubsection[building-registerized]{Building the basics of a registerised GHC}
1346 %$$ %************************************************************************
1348 %$$ \begin{description}
1349 %$$ %---------------------------------------------------------------------
1350 %$$ \item[What you need to run a registerised program:]
1352 %$$ Once you make a \tr{libHSrts_ap_o.a} in runtime, all you need is a
1353 %$$ prelude library. You need to do it by hand still.
1354 %$$ \begin{verbatim}
1356 %$$ % ghc-boot-me -c -g -O -osuf _ap_o.o */*.hc # takes a while
1358 %$$ % rm libHS_ap_o.a
1359 %$$ % ar clq libHS_ap_o.a */*_ap_o.o
1360 %$$ % ranlib libHS_ap_o.a
1363 %$$ %---------------------------------------------------------------------
1364 %$$ \item[Testing the registerised GHC:]
1366 %$$ As before, starting with the \tr{.hc} you made in the first round:
1367 %$$ \begin{verbatim}
1368 %$$ % ghc-boot-me -v -g -c test.hc
1369 %$$ % ghc-boot-me -v -g -o test test.o
1373 %$$ If things are broken, the likely outcome is a core dump, and you'll
1374 %$$ need to throw GDB (or equiv) at it. Useful breakpoints are
1375 %$$ \tr{main}, \tr{miniInterpret}, \tr{Main_main_entry}, and
1376 %$$ \tr{startStgWorld} (when you're just getting going), and
1377 %$$ \tr{stopStgWorld} and \tr{miniInterpretEnd} (which can show that you
1378 %$$ ``almost made it'').
1380 %$$ %---------------------------------------------------------------------
1381 %$$ \item[If you get a consistency-checking error:]
1383 %$$ [From the driver] (These are not as terrible as they seem...)
1385 %$$ The driver, notably \tr{driver/ghc-consist.lprl}, runs the SCCS
1386 %$$ program \tr{what} over your executable, and tries to make sense of the
1389 %$$ If you need to make changes to \tr{ghc-consist.lprl}, just do so, then
1390 %$$ re-\tr{make} in the driver directory.
1392 %$$ %---------------------------------------------------------------------
1393 %$$ \item[Compiling the compiler registerisedly:]
1395 %$$ If you can successfully compile and run {\em some} registerised
1396 %$$ programs, you are probably ready to compile the compiler in that way.
1397 %$$ \begin{verbatim}
1398 %$$ % cd ghc/compiler
1399 %$$ % ghc-boot-me -c -g -O */*.hc # takes *much more* than a while
1400 %$$ % ghc-boot-me -g -O -o hsc */*.o # LINK!
1403 %$$ (Sun3 note: on the particular system I used, I had link troubles. It
1404 %$$ was apparently a Sun bug, because I got a successful link with the GNU
1407 %$$ %---------------------------------------------------------------------
1408 %$$ \item[Testing the {\em whole} registerised GHC:]
1410 %$$ As before, but now you can try compiling from \tr{.hs} to \tr{.hc}
1411 %$$ files with the newly-registerised \tr{hsc}.
1412 %$$ \end{description}
1414 %$$ %************************************************************************
1416 %$$ \subsubsection[real-version-fine-tuning]{Fine-tuning of a ``registerised'' version of GHC}
1418 %$$ %************************************************************************
1420 %$$ NOT FINISHED YET. Let me know if you get this far :-)
1424 %************************************************************************
1426 \subsection[Compiler_reconfig]{Building GHC again after you've bootstrapped}
1427 \index{GHC reconfiguration, after booting}
1428 \index{booting, then GHC reconfigure}
1429 \index{native-code generator, after booting}
1431 %************************************************************************
1433 Two reasons why you might want to re-configure and re-build GHC after
1434 an initial boot are: (a)~to get a native-code generator, or (b)~if you
1435 are going to hack on GHC.
1437 The reason you must rebuild to get a native-code generator: The
1438 \tr{.hc} files will {\em not} turn into a native-code generator, and
1439 the distributed \tr{.hi} files ``match'' those \tr{.hc} files.
1441 From here on, I presume you've installed your booted GHC as
1444 If you are going for a native-code generator, you can save yourself
1445 some re-compiling by getting a suitable set of interface (\tr{.hi})
1446 files, for GHC for your machine. You should end up doing, for example:
1448 cd ghc-0.26/ghc/compiler # note where you are!
1450 rm */*.o # scrub the old compiler files
1452 gunzip -c ghc-0.26-hi-files-alpha.tar.gz | tar xfv -
1455 Now you can configure as before, but using \tr{--with-hc=ghc-0.26}
1456 (\tr{config.status} records what you did before).
1458 Running \tr{sh < STARTUP} isn't strictly necessary; you only need to
1459 rebuild in \tr{ghc/compiler}:
1461 cd ghc-0.26/ghc/compiler
1462 make Makefile # if you didn't STARTUP...
1464 make all EXTRA_HC_OPTS=-fvia-C # -fvia-C important!
1465 make all EXTRA_HC_OPTS=-fvia-C # again, until .hi files settle...
1468 You might want to to again test GHC ``out of the build'' before you
1469 type \tr{make install} in \tr{ghc/compiler} to finish the job.
1471 %************************************************************************
1473 \section[building-with-HBC]{Building GHC with HBC or other funny Haskell compilers}
1474 \index{GHC, building with HBC}
1475 \index{GHC, building with old GHCs}
1476 \index{GHC, building with other compilers}
1478 %************************************************************************
1480 GHC~0.26 doesn't build with HBC. (It could, but we haven't put in
1481 the effort to maintain it.)
1483 GHC~0.26 is best built with itself, GHC~0.26. We heartily recommend
1484 it. GHC~0.26 can certainly be built with GHC~0.23 or 0.24, and with
1485 some earlier versions, with some effort.
1487 GHC has never been built with compilers other than GHC and HBC.
1489 %$$ If you are going to build the compiler with HBC,
1490 %$$ please get the appropriate set of \tr{.hi} interface
1491 %$$ files. If you going to build with an old GHC,
1492 %$$ visit your psychiatrist first.
1494 %$$ If you choose this route,
1495 %$$ you are well advised to get and install a set of \tr{.hi} interface
1496 %$$ files that were created by the same compiler you intend to use. If
1497 %$$ you intend to use HBC, we may provide a suitable ``spare'' set of \tr{.hi} files,
1498 %$$ in \tr{ghc-0.26-hi-files-hbc.tar.gz}, from an FTP site near you.
1500 %$$ Unpack the \tr{.hi} files in this {\em somewhat unobvious} way:
1501 %$$ \begin{verbatim}
1502 %$$ % cd ghc-0.26/ghc/compiler # **** this is where you want to be!!! ****
1504 %$$ % gunzip -c ghc-0.26-hi-files-hbc.tar.gz | tar xfv -
1507 %************************************************************************
1509 \section[Pre-supposed]{Installing pre-supposed utilities}
1510 \index{pre-supposed utilities}
1511 \index{utilities, pre-supposed}
1513 %************************************************************************
1515 Here are the gory details about some utility programs you may need;
1516 \tr{perl} and \tr{gcc} are the only important ones. (PVM is important if you're going for Parallel Haskell.) The
1517 \tr{configure} script will tell you if you are missing something.
1521 \index{pre-supposed: Perl}
1522 \index{Perl, pre-supposed}
1523 {\em You have to have Perl to proceed!} Perl is a language quite good
1524 for doing shell-scripty tasks that involve lots of text processing.
1525 It is pretty easy to install.
1527 (We still assume Perl version 4; experience suggests that Perl~5
1530 Perl should be put somewhere so that it can be invoked by the \tr{#!}
1531 script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
1532 we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
1533 be less than 32 characters long.
1535 Perl version 4.035 has a bug to do with recursion that will bite if
1536 you run the \tr{lit2texi} script, when making Info files from
1537 ``literate'' files of various sorts. Either use a more recent version
1538 (4.036, or 5.00n) or an older version
1541 \item[GNU C (\tr{gcc}):]
1542 \index{pre-supposed: GCC (GNU C compiler)}
1543 \index{GCC (GNU C compiler), pre-supposed}
1544 The current version is 2.7.0, and has no problems that we know of.
1546 If your GCC dies with ``internal error'' on some GHC source file,
1547 please let us know, so we can report it and get things improved.
1548 (Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's
1549 \tr{-monly-N-regs} option; ask if confused...)
1551 \item[PVM version 3:]
1552 \index{pre-supposed: PVM3 (Parallel Virtual Machine)}
1553 \index{PVM3 (Parallel Virtual Machine), pre-supposed}
1554 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
1555 run. Underneath PVM, you can have (for example) a network of
1556 workstations (slow) or a multiprocessor box (faster).
1558 The current version of PVM is 3.3.7. It is readily available on
1559 the net; I think I got it from \tr{research.att.com}, in \tr{netlib}.
1561 A PVM installation is slightly quirky, but easy to do. Just follow
1562 the \tr{Readme} instructions.
1564 \item[\tr{xargs} on Solaris2:]
1565 \index{xargs, presupposed (Solaris only)}
1566 \index{Solaris: alternative xargs}
1567 The GHC libraries are put together with something like:
1569 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
1571 Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
1572 of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
1573 time---with near-infinite rebuilding of the symbol table in
1576 The best solution is to install a sane \tr{xargs} from the GNU
1577 findutils distribution. You can unpack, build, and install the GNU
1578 version in the time the Solaris \tr{xargs} mangles just one GHC
1581 \item[\tr{bash} (Parallel Haskell only):]
1582 \index{bash, presupposed (Parallel Haskell only)}
1583 Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
1584 to PostScript, is written in Bash (GNU's Bourne Again shell).
1585 This bug will be fixed.
1588 \index{pre-supposed: makeindex}
1589 \index{makeindex, pre-supposed}
1590 You won't need this unless you are re-making our documents. Makeindex
1591 normally comes with a \TeX{} distribution, but if not, we can provide
1592 the latest and greatest.
1595 \index{pre-supposed: tgrind}
1596 \index{tgrind, pre-supposed}
1597 This is required only if you remake lots of our documents {\em and}
1598 you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate
1599 programming), to do ``fancy'' typesetting of your code. {\em
1603 \index{pre-supposed: flex}
1604 \index{flex, pre-supposed}
1605 This is a quite-a-bit-better-than-Lex lexer. Used in the
1606 literate-programming stuff. You won't need it unless you're hacking
1607 on some of our more obscure stuff.
1609 \item[Something other than Sun's \tr{/usr/bin/yacc}:]
1610 \index{pre-supposed: non-worthless Yacc}
1611 \index{Yacc, pre-supposed}
1612 If you mess with the Haskell parser, you'll need a Yacc that can cope.
1613 The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK;
1614 Berkeley yacc, \tr{byacc}, is not OK.
1617 %************************************************************************
1619 \section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
1620 \index{problems, building}
1621 \index{pitfalls, in building}
1622 \index{building pitfalls}
1624 %************************************************************************
1626 WARNINGS about pitfalls and known ``problems'':
1629 %------------------------------------------------------------------------
1631 One difficulty that comes up from time to time is running out of space
1632 in \tr{/tmp}. (It is impossible for the configuration stuff to
1633 compensate for the vagaries of different sysadmin approaches re temp
1636 The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or
1637 even \tr{setenv TMPDIR .} (or the equivalent incantation with the
1638 shell of your choice).
1640 The best way around it is to use the \tr{--with-tmpdir=<dir>} option
1641 to \tr{configure}. Then GHC will use the appropriate directory
1644 %------------------------------------------------------------------------
1646 When configuring the support code (mkworld, glafp-utils, etc.), you
1647 will see mention of \tr{NO_SPECIFIC_PROJECT} and
1648 \tr{NO_SPECIFIC_VERSION}. This is cool.
1650 %------------------------------------------------------------------------
1652 In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and
1653 even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think
1656 %------------------------------------------------------------------------
1658 In 0.26, when compiling via C, you'll sometimes get ``warning:
1659 assignment from incompatible pointer type'' out of GCC. Harmless.
1661 %------------------------------------------------------------------------
1663 %If you build an ``unregisterised'' build, you will get bazillions of
1664 %warnings about `ANSI C forbids braced-groups within expressions'.
1665 %Especially in \tr{ghc/lib}. These are OK.
1667 %------------------------------------------------------------------------
1669 Similarly, \tr{ar}chiving warning messages like the following are not
1672 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1673 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1677 %------------------------------------------------------------------------
1679 Also harmless are some specialisation messages that you may see when
1680 compiling GHC; e.g.:
1682 SPECIALISATION MESSAGES (Desirable):
1684 {-# SPECIALIZE instance Eq [Class] #-}
1685 {-# SPECIALIZE instance Eq (Class, [Class]) #-}
1686 {-# SPECIALIZE instance Outputable [ClassOp] #-}
1687 {-# SPECIALIZE instance Outputable [Id] #-}
1690 %------------------------------------------------------------------------
1692 In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an
1693 ``Out of heap space'' error message. These
1694 can vary with the vagaries of different systems, it seems. The
1695 solution is simple: (1)~add a suitable \tr{-H} flag to the \tr{compile}
1696 macro for the offending module,
1697 in \tr{ghc/compiler/Jmakefile} (towards the end);
1698 (2)~re-\tr{make Makefile} in that directory; (3)~try again: \tr{make}.
1700 Alternatively, just cut to the chase scene:
1703 % make EXTRA_HC_OPTS=-H32m # or some nice big number
1706 %------------------------------------------------------------------------
1708 Not too long into the build process, you may get a huge complaint
1711 Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
1713 This indicates that your \tr{perl} was mis-installed; the binary is
1714 unable to find the files for its ``built-in'' library. Speak to your
1715 perl installer, then re-try.
1717 %------------------------------------------------------------------------
1719 If you try to compile some Haskell, and you get errors from GCC
1720 about lots of things from \tr{/usr/include/math.h}, then your GCC
1721 was mis-installed. \tr{fixincludes} wasn't run when it should've
1724 As \tr{fixincludes} is now automagically run as part of GCC
1725 installation, this bug also suggests that you have an old GCC.
1727 %------------------------------------------------------------------------
1729 %Sooner or later in your ``make-worlding'' life you will do and see
1733 % rm -f Makefile.bak; mv Makefile Makefile.bak
1734 %../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=...
1735 %../.././mkworld/jrestoredeps
1736 %==== The new Makefile is for: ====
1737 %make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen
1738 %Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard
1740 %make: Fatal error: Command failed for target `Makefile'
1743 %Don't panic! It should restore your previous \tr{Makefile}, and
1744 %leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure.
1746 %------------------------------------------------------------------------
1748 %If you do corrupt a \tr{Makefile} totally, or you need to glue a new
1749 %directory into the directory structure (in \tr{newdir}---which must
1750 %have a \tr{Jmakefile}, even if empty), here's a neat trick:
1753 %# move to the directory just above the one where you want a Makefile...
1756 %# make Makefiles, but lie about the directories below...
1757 %make Makefiles SUBDIRS=newdir
1760 %This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and
1761 %it will be properly wired into the general make-world structure.
1763 %------------------------------------------------------------------------
1765 %Don't configure/build/install using a variety of machines. A
1766 %mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to
1767 %build GHC (\tr{make all}) on a Sun3.
1769 %------------------------------------------------------------------------
1771 If you end up making documents that involve (La)TeX and/or \tr{tib}
1772 (Simon's favourite), the odds are that something about your/our setup
1773 will reach out and bite you. Yes, please complain; meanwhile,
1774 you can do \tr{make -n whatever.dvi} to see the intended commands,
1775 then try to muddle through, doing them by hand.
1777 %------------------------------------------------------------------------
1781 %************************************************************************
1783 \section[weird-configs]{Making weird GHC configurations}
1784 \index{GHC unusual configurations}
1786 %************************************************************************
1788 The usual way to build a ``weird'' GHC configuration is to turn
1789 various \tr{configure} knobs, e.g., \tr{--enable-concurrent}.
1790 Please see \sectionref{Configuring-GHC} about GHC configuring.
1792 If you want to build some Very Customised GHC libraries, it's
1793 probably best to send email to us, asking how.
1795 %$$ Usually, you will build whatever libraries your chosen ``setup''
1796 %$$ specifies. However, perhaps you are a hacker, and you want an extra
1797 %$$ ``ticky-ticky profiling'' version of the libraries. (Or, you want a
1798 %$$ version compiled with your Very Own Optimisation...)
1800 %$$ To create a ``user way'' or setup, put
1801 %$$ something like this somewhere (more on ``somewhere'', below):
1802 %$$ \begin{verbatim}
1803 %$$ #ifndef GhcBuild_UserWay_a
1804 %$$ #define GhcBuild_UserWay_a YES
1805 %$$ GHC_USER_WAY_FLAG_a = -ticky
1806 %$$ GHC_USER_WAY_OPTS_a = -fstg-reduction-counts -O
1807 %$$ #endif /* ! GhcBuild_UserWay_a */
1809 %$$ You'll be able to invoke the driver with a \tr{-ticky} option, which
1810 %$$ will be as if you typed in all that other stuff. It will also arrange
1811 %$$ that there is a version of the prelude (\tr{libHS_a.a} library,
1812 %$$ \tr{Prelude_a.hi} to match) and runtime system (\tr{libHSrts_a.a}) to
1813 %$$ match. (Neat, huh?)
1815 %$$ On the ``somewhere'' to specify what to build: If you don't plan
1816 %$$ to re-\tr{configure}, just change \tr{site-ghc.jm}. If you do plan to
1817 %$$ re-\tr{configure}, change \tr{site-ghc.jm.in} and re-\tr{configure}
1820 %$$ One note about {\em adding} ``user setups'' to an existing build:
1821 %$$ Besides remaking your \tr{Makefiles} straight away, {\em don't forget}
1822 %$$ to remake the driver (in \tr{ghc/driver}) before making any libraries!
1823 %$$ The short cut is:
1824 %$$ \begin{verbatim}
1825 %$$ cd ..../ghc/driver
1826 %$$ make Makefile; make all
1828 %$$ make Makefile; make all
1830 %$$ make Makefile; make all
1835 %************************************************************************
1837 \section[building-Haggis]{Building Haggis (Haskell GUI toolkit)}
1838 \index{Haggis, building}
1839 \index{building Haggis}
1841 %************************************************************************
1845 %************************************************************************
1847 \section[building-Happy]{Building Happy (Haskell parser generator)}
1848 \index{Happy, building}
1849 \index{building Happy}
1851 %************************************************************************
1855 %************************************************************************
1857 \section[building-NoFib]{Building NoFib (Haskell benchmark suite)}
1858 \index{NoFib suite, building}
1859 \index{building the NoFib suite}
1861 %************************************************************************
1865 %************************************************************************
1867 \section[Configuring]{Running \tr{configure}}
1868 \index{configure script}
1870 %************************************************************************
1872 The GNU-style \tr{configure} script figures out things which we need
1873 to know to build one or more Glasgow tools for your machine. Also,
1874 \tr{configure} lets you specify what you want built.
1876 Most people will configure/build one tool at a time. The
1877 ``short-cut'' instructions
1878 for GHC are in \sectionref{Configuring-GHC},
1879 for Haggis in \sectionref{Configuring-Haggis},
1880 for Happy in \sectionref{Configuring-Happy},
1881 and for NoFib in \sectionref{Configuring-NoFib}.
1883 However, \tr{configure} lets you pick and choose, so you can build
1884 several things ``in a one-er''. Just fling in all the options
1885 at once, and be amazed.
1887 %************************************************************************
1889 \subsection[Configuring-general]{\tr{configure} options for all tools}
1890 \index{Configuring (general)}
1892 %************************************************************************
1894 Many \tr{configure} options apply no matter what tools you are building.
1897 \item[\tr{--help}:] (a standard GNU option)
1898 \index{--help configure option}
1899 Prints out a long usage message. The first part is GNU boilerplate;
1900 after that is the Glasgow info.
1902 \item[\tr{--prefix=}{\em directory}:] (a standard GNU option)
1903 \index{--prefix configure option}
1904 Sets the ``root'' directory for where a system should be installed;
1905 defaults to \tr{/usr/local}.
1907 With Happy, for example, the main \tr{happy} binary will end up in
1908 \tr{/usr/local/bin/happy}.
1910 %--------------------------------------------------------------
1911 \item[\tr{--exec-prefix=}{\em directory}:] (a standard GNU option)
1912 \index{--exec-prefix configure option}
1913 Sets the ``root'' directory
1914 for where executables
1915 (e.g., the GHC driver) should be installed; defaults to whatever
1917 meaning that things will be installed in \tr{/usr/local/bin}.
1919 %$$ At Glasgow, we want such executables to go in (e.g.)
1920 %$$ \tr{/local/fp/bin.sun4}, so \tr{--exec-prefix} is no use to us.
1921 %$$ Happily, there's more than one way to do it!---just change
1922 %$$ \tr{InstBinDir_GHC} in \tr{ghc/mkworld/site-ghc.jm.in}... (We hope
1923 %$$ this doesn't bring back too many bad memories for our
1924 %$$ pre-\tr{configure} users.)
1926 %--------------------------------------------------------------
1927 \item[\tr{--with-hc=}{\em hask}:]
1928 \index{--with-hc configure option}
1929 Use {\em hask} as my ``installed Haskell compiler.''
1931 The name {\em hask} has to be one of \tr{ghc*} (for Glasgow Haskell),
1932 \tr{hbc*} (for Chalmers HBC), or \tr{nhc*} (for Rojemo's NHC).
1933 We hope to add more!
1935 As a special case, \tr{--with-hc=c} means ``I don't have a Haskell
1936 compiler, please compile from intermediate C files (produced by GHC
1939 %--------------------------------------------------------------
1940 \item[\tr{--with-tmpdir=}{\em directory}:]
1941 Set the directory where temporary files should be created. This is
1942 \tr{/tmp} by default, which is Sometimes Uncool (because, e.g.,
1943 \tr{/tmp} is too small). There's just no telling.
1945 On our Alphas, for example, we use \tr{--with-tmpdir=/usr/tmp}.
1947 %--------------------------------------------------------------
1948 \item[\tr{--with-max-heap=}{\em size}:]
1949 When whatever Haskell compiler is run while building the Glasgow
1950 tools, it will try to use some sane-but-not-too-big heap size. If you
1951 have a machine with plenty of memory, you might want to say ``Go ahead
1952 and use a great big heap.'' This option allows this. So, for
1953 example, on our Alphas we might say \tr{--with-max-heap=48m}.
1956 %************************************************************************
1958 \subsection[Configuring-GHC]{GHC-specific things in \tr{configure}}
1959 \index{Configuring for GHC}
1961 %************************************************************************
1963 The easiest way to see all the \tr{configure} options for GHC is to
1964 type \tr{./configure --help}. (I don't feel like typing the whole
1965 thing again, into this document...)
1967 Some common combinations would be:
1970 ./configure --prefix=/users/fp/partain --with-hc=c --disable-profiling
1971 # use .hc files; don't bother with profiling
1973 ./configure --with-hc=ghc-0.26 --with-readline-library --with-sockets-library
1974 # simple build with itself; for Sun4s & Alphas, you
1975 # should grab & use ghc-0.26-hi-files-<blah>.tar.gz
1976 # (because those machines have a native-code generator).
1977 # For the extra libraries, you've got to have the right
1980 ./configure --with-hc=ghc-0.26 --disable-hsc-optimised --enable-hsc-debug
1981 # Don't use -O on GHC itself; turn on -DDEBUG.
1982 # Slows things way down, but it's the right thing if
1983 # you're hacking on GHC and doing lots of recompilations.
1985 ./configure --with-hc=c --enable-concurrent --enable-parallel --with-tmpdir=/usr/tmp
1986 # Do everything from .hc files; besides the normal ones,
1987 # you'll need the "prof", "conc" and "par" .hc files.
1988 # Use /usr/tmp as TMPDIR...
1991 Remember, if you build \tr{--with-hc=c} on a Sun4 or Alpha, you
1992 do {\em not} have a native-code generator.
1994 %************************************************************************
1996 \subsection[Configuring-Haggis]{Haggis-specific things in \tr{configure}}
1997 \index{Configuring for Haggis}
1999 %************************************************************************
2001 Use \tr{--enable-haggis}. If you have Haggis and GHC in the same
2002 build tree but only want to build Haggis, use \tr{--disable-ghc}.
2006 %************************************************************************
2008 \subsection[Configuring-Happy]{Happy-specific things in \tr{configure}}
2009 \index{Configuring for Happy}
2011 %************************************************************************
2013 Use \tr{--enable-happy}. If you have Happy and GHC in the same
2014 build tree but only want to build Happy, use \tr{--disable-ghc}.
2018 %************************************************************************
2020 \subsection[Configuring-NoFib]{NoFib-specific things in \tr{configure}}
2021 \index{Configuring for NoFib}
2023 %************************************************************************
2025 Use \tr{--enable-nofib}. If you have NoFib and GHC in the same build
2026 tree but only want to build the NoFib suite, use \tr{--disable-ghc}.
2028 You may want to enable or disable various sets of tests, as
2029 suggested by \tr{./configure --help}. If you use \tr{--enable-all-tests},
2030 be aware that many of them are GHC-specific. Also, we may not have
2031 given you all of the source :-)
2033 %************************************************************************
2035 \section[STARTUP]{Running \tr{STARTUP}}
2036 \index{STARTUP script}
2038 %************************************************************************
2040 Once you've \tr{configure}d, utter the magic incantation:
2042 % sh < STARTUP >& startup.log
2044 The reason you might want to pipe the chatter into a file is so you
2045 can check it afterwards. It should be pretty obvious if it is happy.
2046 Note: it takes a little while.
2048 \tr{STARTUP} is a simple shell script that builds \tr{mkworld}
2049 (Makefile-generating system), \tr{literate} (literate-programming
2050 system), and \tr{glafp-utils} (a few utility programs); then makes the
2051 Makefiles and dependencies for everything.
2053 If you have any problems before getting through \tr{STARTUP}, you
2054 are probably best off re-running \tr{configure} and \tr{STARTUP}
2055 (after fixing what was broken).
2057 %************************************************************************
2059 \section[utils_install]{Installing the support software (optional)}
2060 \index{utilities, installing}
2062 %************************************************************************
2064 By default, the support software that comes with the Glasgow
2065 tools---\tr{mkworld}, \tr{literate}, and \tr{glafp-utils}---is not
2066 installed. However, they're generally-useful tools, so...
2068 If you did want to install the ``make world'' system, for example:
2070 % cd <very-top>/mkworld
2074 If it isn't installing things where you want it to, you can either
2075 fiddle things on the fly...
2077 % make install prefix=/home/sweet/home
2080 If you want to install just one utility, for example \tr{lndir}:
2082 % cd <very-top>/glafp-utils/scripts
2083 % make install_lndir
2086 ``Make world''---It slices, it dices... it's great!
2088 %************************************************************************
2090 \section[arrangement-of-sources]{Arrangement of the sources}
2092 %************************************************************************
2094 Once you un\tr{tar} the Glorious Haskell Compilation (GHC) system sources
2095 and \tr{cd} into the top directory, here's a bird's-eye view of what
2099 mkworld/ & ``Make world'' sub-system for configuring the system.\\
2101 glafp-utils/ & Utility programs and scripts used in building the distribution;\\
2102 & often acquired from elsewhere. \\
2103 literate/ & Glasgow literate programming sub-system. \\
2105 ghc/driver/ & The driver program for GHC; \\
2106 & currently a perl script, \tr{ghc}. \\
2108 ghc/compiler/ & The Haskell compiler proper, called \tr{hsc}; \\
2109 & source files are in \tr{compiler/*/[A-Z]*.lhs}. \\
2111 ghc/runtime/ & The runtime system, including the garbage-collector(s).\\
2113 ghc/lib/prelude/& Source for the linked-in code for the ``standard prelude''. \\
2114 ghc/lib/glaExts/ & Source for the linked-in code for our Glasgow extensions. \\
2115 ghc/lib/haskell-1.3/ & Source for the linked-in code for Haskell 1.3 I/O. \\
2116 ghc/lib/hbc/ & Source for the HBC `system library'. \\
2117 ghc/lib/ghc/ & Source for the GHC `system library'.\\
2119 ghc/includes/ & The ``public'' .hi files slurped by the parser, \\
2120 & and .h files \tr{#include}d in generated .hc files come from.\\
2122 ghc/docs/ & documents; see the README file there. \\
2124 ghc/CONTRIB/ & reserved for contributed things \\
2125 haggis/ & Haggis Haskell X11 GUI toolkit \\
2126 happy/ & Happy Haskell parser generator \\
2127 nofib/ & NoFib Haskell benchmark and test suite \\
2130 \begin{onlystandalone}
2133 \end{onlystandalone}