2 % $Header: /srv/cvs/cvs.haskell.org/fptools/ghc/docs/install_guide/Attic/installing.lit,v 1.4 1996/07/25 20:47:34 partain Exp $
5 \documentstyle[11pt,literate]{article}
7 \title{Installing the Glasgow Functional Programming Tools\\
10 Department of Computing Science\\
11 University of Glasgow\\
15 Email: glasgow-haskell-\{users,bugs\}-request\@dcs.gla.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 %************************************************************************
36 \subsection[install-strategy]{What to install? Starting from what?}
38 %************************************************************************
40 Building the Glasgow tools {\em can} be complicated, mostly because
41 there are so many permutations of what/why/how, e.g., ``Build Happy
42 with HBC, everything else with GHC, leave out profiling, and test it
43 all on the `real' NoFib programs.'' Yeeps!
45 Happily, such complications don't apply to most people. A few common
46 ``strategies'' serve most purposes. Pick one and proceed
49 \item[Install from binary ``bundles'':] You have one of the supported
50 platforms (e.g., Sun4 or DEC Alpha), and you just want a Haskell
51 compiler, and you don't want to do anything fancy... This choice
52 is for you. Proceed to
53 \sectionref{installing-bin-distrib}. HIGHLY RECOMMENDED!
55 \item[Build some Glasgow tools using GHC itself:] You have a supported
56 platform, but (a)~you like the warm fuzzy feeling of compiling things
57 yourself; (b)~you want to build something ``extra''---e.g., a set of
58 libraries with strictness-analysis turned off; or (c)~you want to hack
61 In this case, you should install a binary distribution
62 (as described in \sectionref{installing-bin-distrib}),
63 then build GHC with it (as described in \sectionref{building-GHC}).
65 \item[Build GHC from intermediate C \tr{.hc} files:] You cannot get a
66 pre-built GHC, so you have no choice but to ``bootstrap'' up from the
67 intermediate C (\tr{.hc}) files that we provide.
68 Building GHC on an unsupported platform falls into this category.
69 Please see \sectionref{booting-from-C}.
71 NB: For GHC~2.01, bootstrapping from \tr{.hc} files means you will get
72 an all-2.01 system---possibly unduly slow. Building with GHC~0.29
73 will get you a faster compiler...
75 Once you have built GHC, you can build the other Glasgow tools with
78 \item[Build GHC with another Haskell compiler (e.g., HBC):] Not
79 recommended, but see \sectionref{building-with-HBC}.
82 %************************************************************************
84 \subsection[port-info]{What machines the Glasgow tools, version~2.01, run on}
87 \index{supported platforms}
88 \index{platforms, supported}
90 %************************************************************************
92 The main question is whether or not the Haskell compiler (GHC) runs on
95 Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
96 work on all machines for which basic Haskell compiling is supported.
98 Some libraries may only work on a limited number of platforms; for
99 example, a sockets library is of no use unless the operating system
100 supports the underlying BSDisms.
102 %************************************************************************
104 \subsubsection{What machines the Haskell compiler (GHC) runs on}
106 %************************************************************************
107 \index{fully-supported platforms}
108 \index{native-code generator}
109 \index{registerised ports}
110 \index{unregisterised ports}
112 The GHC hierarchy of Porting Goodness: (a)~Best is a native-code
113 generator; (b)~next best is a ``registerised''
114 port; (c)~the bare minimum is an ``unregisterised'' port.
115 ``Unregisterised'' is so terrible that we won't say more about it.
117 We use Sun4s running SunOS~4.1.3 and Solaris 2.5, and DEC~Alphas
118 running OSF/1~V2.0, so those are the ``fully-supported'' platforms,
119 unsurprisingly. Both have native-code generators, for quicker
120 compilations. The native-code generator for iX86 platforms (e.g.,
121 Linux ELF) is {\em nearly} working; but is not turned on by default.
123 Here's everything that's known about GHC ports, as of 2.01. We
124 identify platforms by their ``canonical GNU-style'' names.
126 Note that some ports are fussy about which GCC version you use; or
130 %-------------------------------------------------------------------
131 \item[\tr{alpha-dec-osf1}:]
132 \index{alpha-dec-osf1: fully supported}
133 (We have OSF/1 V2.0.) Fully supported, including native-code generator.
134 We recommend GCC 2.6.x or later.
136 %-------------------------------------------------------------------
137 \item[\tr{sparc-sun-sunos4}:]
138 \index{sparc-sun-sunos4: fully supported}
139 Fully supported, including native-code generator.
141 %-------------------------------------------------------------------
142 \item[\tr{sparc-sun-solaris2}:]
143 \index{sparc-sun-solaris2: fully supported}
144 Fully supported, including native-code generator. A couple of quirks,
145 though: (a)~the profiling libraries are bizarrely huge; (b)~the
146 default \tr{xargs} program is atrociously bad for building GHC
147 libraries (see \sectionref{Pre-supposed} for details).
149 %-------------------------------------------------------------------
150 \item[HP-PA box running HP/UX 9.x:]
151 \index{hppa1.1-hp-hpux: registerised port}
152 Works registerised. No native-code generator.
153 For GCC, you're best off with one of the Utah releases of
154 GCC~2.6.3 (`u3' or later), from \tr{jaguar.cs.utah.edu}.
155 We think a straight GCC 2.7.x works, too.
157 Concurrent/Parallel Haskell probably don't work (yet).
158 \index{hppa1.1-hp-hpux: concurrent---no}
159 \index{hppa1.1-hp-hpux: parallel---no}
161 %-------------------------------------------------------------------
162 \item[\tr{i386-*-linux} (PCs running Linux---ELF format):]
163 \index{i386-*-linux: registerised port}
164 GHC~2.01 works registerised.
165 You {\em must} have GCC 2.7.x or later.
166 The iX86 native-code generator is {\em nearly} there, but it
167 isn't turned on by default.
169 Profiling works, and Concurrent Haskell works.
170 \index{i386-*-linux: profiling---yes}
171 \index{i386-*-linux: concurrent---yes}
172 Parallel Haskell probably works.
173 \index{i386-*-linux: parallel---maybe}
175 On old Linux a.out systems: should be the same.
176 \index{i386-*-linuxaout: registerised port}
178 %-------------------------------------------------------------------
179 \item[\tr{mips-sgi-irix5}:]
180 \index{mips-sgi-irix5: registerised port}
181 GHC~2.01 works registerised (no native-code generator).
182 I suspect any GCC~2.6.x (or later) is OK. The GCC that I used
183 was built with \tr{--with-gnu-as}; turns out that is important!
185 Concurrent/Parallel Haskell probably don't work (yet).
186 Profiling might work, but it is untested.
187 \index{mips-sgi-irix5: concurrent---no}
188 \index{mips-sgi-irix5: parallel---no}
189 \index{mips-sgi-irix5: profiling---maybe}
191 %-------------------------------------------------------------------
192 \item[\tr{m68k-apple-macos7} (Mac, using MPW):]
193 \index{m68k-apple-macos7: historically ported}
194 Once upon a time, David Wright in Tasmania has actually
195 gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
196 You may be able to get Thomson's from here. (Not sure that it will
197 excite you to death, but...)
199 No particularly recent GHC is known to work on a Mac.
201 %-------------------------------------------------------------------
202 \item[\tr{m68k-next-nextstep3}:]
203 \index{m68k-next-nextstep3: historically ported}
204 Carsten Schultz succeeded with a ``registerised'' port of GHC~0.19.
205 There's probably a little bit-rot since then, but otherwise it should
206 still be fine. Had a report that things were basically OK at 0.22.
208 Concurrent/Parallel Haskell probably won't work (yet).
209 \index{m68k-next-nextstep3: concurrent---no}
210 \index{m68k-next-nextstep3: parallel---no}
212 %-------------------------------------------------------------------
213 \item[\tr{m68k-sun-sunos4} (Sun3):]
214 \index{m68k-sun-sunos4: registerised port}
215 GHC~2.01 hasn't been tried on a Sun3. GHC~0.26 worked registerised.
216 No native-code generator.
218 Concurrent/Parallel Haskell probably don't work (yet).
219 \index{m68k-sun-sunos4: concurrent---no}
220 \index{m68k-sun-sunos4: parallel---no}
223 %************************************************************************
225 \subsubsection{What machines the other tools run on}
227 %************************************************************************
229 Unless you hear otherwise, the other tools work if GHC works.
231 Haggis requires Concurrent Haskell to work.
232 \index{Haggis, Concurrent Haskell}
234 %************************************************************************
236 \subsection{Things to check before you start typing}
238 %************************************************************************
242 \index{disk space needed}
243 Disk space needed: About 30MB (five hamburgers' worth) of disk space
244 for the most basic binary distribution of GHC; more for some
245 platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent
246 Haskell libraries) might take you to 8--10 hamburgers.
248 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
249 build the basic stuff from scratch.
251 I don't yet know the disk requirements for the non-GHC tools.
253 All of the above are {\em estimates} of disk-space needs.
256 Use an appropriate machine, compilers, and things.
258 SPARC boxes and DEC Alphas running OSF/1 are fully supported.
259 Linux, MIPS, and HP boxes are in pretty good shape.
260 \Sectionref{port-info} gives the full run-down on ports or lack
264 Be sure that the ``pre-supposed'' utilities are installed.
266 For GHC, you must have \tr{perl} to get anywhere at all. If you're
267 going for Parallel Haskell, you'll need PVM, version 3. You will
268 probably need a reasonably up-to-date GCC (GNU C compiler),
269 too---\sectionref{port-info} lists any specific requirements in this
272 % If you are going to be making documents [unlikely], you'll need
273 % \tr{makeindex} as well, and maybe \tr{tgrind} [unlikely]. If you edit
274 % the one or two \tr{flex} files in GHC, you'll need \tr{flex}, too
277 If you end up yacc'ing the Haskell parser [unlikely], Sun's standard
278 \tr{/bin/yacc} won't cut it. Either the unbundled \tr{/usr/lang/yacc}
279 or \tr{bison} will do fine. Berkeley yacc (\tr{byacc}) won't do.
282 If you have any problem when building or installing the Glasgow tools,
283 please check the ``known pitfalls'' (\sectionref{build-pitfalls}). If
284 you feel there is still some shortcoming in our procedure or
285 instructions, please report it.
287 For GHC, please see the bug-reporting section of the User's guide
288 (separate document), to maximise the usefulness of your report.
290 If in doubt, please send a message to
291 \tr{glasgow-haskell-bugs@dcs.gla.ac.uk}.
294 %************************************************************************
296 \section[installing-bin-distrib]{Installing from binary distributions (the most common case)}
297 \index{binary installations}
298 \index{installation, of binaries}
300 %************************************************************************
302 Installing from binary distributions is easiest, and recommended!
304 %************************************************************************
306 \subsection[GHC-bin-distrib]{GHC from binary distributions}
307 \index{GHC installation, from binaries}
308 \index{installation, GHC from binaries}
310 %************************************************************************
312 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
313 so you've got to ``bootstrap'' it, somehow. We provide
314 machine-generated C-files-from-Haskell for this purpose, but it's
315 really quite a pain to use them. If you must build GHC from its
316 sources, using a binary-distributed GHC to do so is a sensible way to
319 Binary distributions come in ``bundles,''\index{bundles of binary stuff}
320 one bundle per \tr{.tar.gz} file.
322 A basic GHC ``bundle'' gives you the compiler and the standard,
323 sequential libraries. The files are called
324 \tr{ghc-2.01-<platform>.tar.gz}, where \tr{<platform>} is one of:
325 alpha-dec-osf2, hppa1.1-hp-hpux9, i386-unknown-linux,
326 i386-unknown-solaris2, i386-unknown-freebsd,
327 m68k-sun-sunos4, mips-sgi-irix5,
328 sparc-sun-sunos4, sparc-sun-solaris2.
330 There are plenty of ``non-basic'' GHC bundles. The files for them are
331 called \tr{ghc-2.01-<bundle>-<platform>.tar.gz}, where the
332 \tr{<platform>} is as above, and \tr{<bundle>} is one of these:
334 \item[\tr{prof}:] Profiling with cost-centres. You probably want this.
336 \item[\tr{conc}:] Concurrent Haskell features. You may want this.
338 \item[\tr{par}:] Parallel Haskell features (sits on top of PVM).
339 You'll want this if you're into that kind of thing.
341 \item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
342 (hmm... mainly for implementors).
344 \item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
345 information about ``what happened when I ran this program''---really
348 \item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
350 \item[\tr{prof-ticky}:] Ticky-ticky profiling for Concurrent Haskell.
353 One likely scenario is that you will grab {\em three} binary
354 bundles---basic, profiling, and concurrent. Once you have them,
355 unpack them all together in the same place, thusly:
359 gunzip < ghc-2.01-sparc-sun-sunos4.tar.gz | tar xf -
360 gunzip < ghc-2.01-prof-sparc-sun-sunos4.tar.gz | tar xf -
361 gunzip < ghc-2.01-conc-sparc-sun-sunos4.tar.gz | tar xf -
364 If you unpacked the files in a way that does {\em not} preserve
365 modification times (e.g., used the \tr{m} option to \tr{tar}---why on
366 earth you might do this, I cannot imagine), then please unpack them
367 again :-) The timestamps on the files are (regrettably) important.
369 %To check that you have all the pre-supposed utilities, please see
370 %\sectionref{Pre-supposed}.
372 Here's what to do with the stuff in each directory, once unpacked.
373 % (If your binary distribution, doesn't look like this---don't despair!
374 % It may be a ``dumped-from-a-build'' distribution; please see
375 % \sectionref{dumped-from-build}.)
378 %---------------------------------------------------------------------
379 \item[\tr{bin/<platform>} (sometimes just \tr{bin/}):]
380 Copy (or link to) these executables so that they will be in users' PATHs.
382 %---------------------------------------------------------------------
384 Move this directory, in toto, to wherever you want it to live.
385 It should still be called \tr{lib}.
387 %---------------------------------------------------------------------
389 This is the full \tr{docs} tree. Just follow the normal instructions,
390 in \sectionref{make-docs}.
393 Things you need to fiddle so the tools will spring to life:
396 \tr{rehash} (csh users), so your shell will see the new stuff in your
400 Edit your \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts:
401 (a)~Create a correct \tr{#!...perl} first line in each one. (Ask a
402 Unix-friendly person to help you, if you don't know what a
403 \tr{#!}-line is.) (b) Find the line that looks something like:
405 # $ENV{'GLASGOW_HASKELL_ROOT'} = '/some/absolute/path/name';
407 Remote the comment symbol (\tr{#}) on the front, and change the
408 path name to be the right thing.
410 So, if your ``lib'' files are now in \tr{/home/myself/lib/ghc/...},
411 then you should set \tr{GLASGOW_HASKELL_ROOT} to \tr{/home/myself}.
414 Actually setting the \tr{GLASGOW_HASKELL_ROOT} environment variable
415 is a {\em bad} idea, mostly because it precludes having several
416 GHC versions around at the same time.
420 % Set your \tr{GLASGOW_HASKELL_ROOT} environment variable, and
421 % don't edit the \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts
424 % It's better to edit the scripts; that way, it's once for all.
427 You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
429 % cd <wherever-the-lib-files-are-now>/ghc/2.01/sparc-sun-sunos4
430 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
432 ? # or, on some machines: ar s $i
437 Once done, test your ``installation'' as suggested in
438 \sectionref{GHC_test}. Be sure to use a \tr{-v} option, so you
439 can see exactly what pathnames it's using.
441 If things don't work, double-check your hand-edited path
442 names. Things will go catastrophically wrong as long as they are
446 %************************************************************************
448 \subsection[non-GHC-bin-distrib]{Other tools from binary distributions}
450 %************************************************************************
454 All of the above is for GHC bundles. For other tools, the same
455 principles apply: get the binary bundles you want, then unpack them
456 all together in the same place.
458 %************************************************************************
460 %\subsection[dumped-from-build]{Installing a ``dumped-from-build'' binary distribution (some platforms)}
462 %************************************************************************
464 %#% Sometimes, a binary distribution is taken directly from a GHC
465 %#% ``build.'' An example is the Solaris distribution. You can tell from
466 %#% the layout of the files.
468 %#% The setup required is nearly the same as a ``regular'' binary
469 %#% distribution; only some names are different.
470 %#% \begin{enumerate}
472 %#% Get the user-executable scripts into your PATH, either by copying it
473 %#% or by linking to it. These are in:
475 %#% <topdir>/ghc/driver/ghc
476 %#% <topdir>/ghc/utils/mkdependHS/mkdependHS
477 %#% <topdir>/ghc/utils/hstags/hstags
481 %#% Set the \tr{GLASGOW_HASKELL_ROOT} environment variable for the three
482 %#% scripts above, in the manner outlined in the previous section.
485 %#% Possibly re-\tr{ranlib}'ing your \tr{*.a} files:
488 %#% % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
490 %#% % # or, on some machines: ar s $i
495 %#% Don't forget to test it!
498 %************************************************************************
500 \section[checklist]{Building Glasgow tools from source: a checklist}
502 %************************************************************************
506 Install any pre-supposed utility programs that you do not have at your
507 site. You have to do this ``by hand.'' It's not hard, and these are
508 things you want to have anyway. Please see \sectionref{Pre-supposed}.
511 Be sure you have a suitable Haskell compiler, or else the intermediate
513 \Sectionref{install-strategy} lists the various strategies you might
516 If you don't have a Haskell compiler, the most painless option is to
517 use a binary-distributed GHC to compile Glasgow tools (including GHC
518 itself) from source. Installing a binary distribution (the first
519 step) is described in \sectionref{installing-bin-distrib}.
522 You might want to write-protect your source files at this point:
524 cd <the-very-top-dir>
525 find . -type f \! -name \*.hi \! -name \*.hc \! -name \*.jm -print \
530 Run the \tr{configure} script. It is a shell script that looks around
531 to find out things about your system. You can see the \tr{configure}
532 options by passing it a \tr{--help} flag, or by reading
533 \sectionref{Configuring}. A typical invocation might be:
535 % cd <the-very-top-dir>
536 % ./configure --prefix=/usr/local/fp \
537 --with-hc=ghc-0.29 --with-mkdependHS=mkdependHS-0.29
541 Once configured, build the basic support utilities and make your
542 Makefiles, including the automagically-created dependencies between
543 files. The near-universal incantation is:
545 % cd <the-very-top-dir>
546 % sh < STARTUP >& startup.log # and chk the log afterwards!
550 Build the Glasgow tools you are interested in, as \tr{STARTUP} suggests:
552 % cd <the-very-top-dir>/<tool>
553 % make all >& make.log # time to go to lunch!
555 Consult the list of known pitfalls (\sectionref{build-pitfalls}) if
556 something goes wrong.
559 Test what you've built, enough to know that it's working.
562 Actually install the tools, if you wish:
564 % cd <the-very-top-dir>/<tool>
569 Make and/or install the documentation.
572 Save a copy of your \tr{config.status} file, for the next
573 even-more-wonderful release!
576 If you're finished, tidy up after yourself [\tr{make clean}], if you
579 Alternatively, \tr{/bin/rm -rf <tool>} :-)
582 %************************************************************************
584 \section[building-GHC]{Building the Glasgow Haskell Compiler (GHC)}
585 \index{GHC installation, from sources}
587 %************************************************************************
589 %************************************************************************
592 \section{Building GHC from source, compiling it with itself}
593 \index{building GHC with itself}
594 \index{booting GHC with itself}
596 %************************************************************************
598 This section describes how to build GHC from source. You would do
599 this if (a)~there is no ``canned'' binary distribution for your
600 machine, (b)~the binary distribution omits features that you want,
601 (c)~you want to make changes to GHC and them build them in, or
602 (d)~you like torturing yourself.
604 This blow-by-blow description follows the general checklist in
605 \sectionref{checklist}.
607 %************************************************************************
609 \subsection[Right-compiler-and-files]{Do you have a suitable compiler and/or \tr{.hc} files and/or \tr{.hi} files?}
610 \index{booting GHC, files needed}
612 %************************************************************************
614 We now proceed through each installation step, carefully.
616 Because the compiler heart of Glorious Glasgow Haskell is written in
617 Haskell, you have to use some ``bootstrapping'' mechanism.
619 Your best choice, if available, is to use a binary distribution for
620 your platform; e.g., compile GHC~2.01 with a GHC~0.29 that we have
621 provided. Please see \sectionref{installing-bin-distrib} for how to
622 install a binary distribution.
624 Your remaining choice is to use the intermediate C (\tr{.hc}) files
625 that we supply. This is the {\em only} choice for anyone trying to
626 port to a new or weakly-supported system.
628 The main drawback of the supplied-\tr{.hc} approach is that you will
629 have a lot of very bulky intermediate files on your disk for a while.
631 (With GHC~2.01, another drawback is that the \tr{.hc} files will give
632 you a 2.01-built-with-2.01---normally a good thing---but, in this case,
633 probably slower than a 2.01-built-with-0.29.)
635 % If you have to boot from C (\tr{.hc}) files, you should follow the
636 % directions in \sectionref{booting-from-C}.
638 % We also supply parts of the system pre-compiled to C (in \tr{.hc}
639 % files). This is partly to save you work (you don't have to wait for
640 % them to compile yourself) and partly because this is how we will
641 % eventually supply the self-compiling compiler (when that's ready).
642 % In any case, if you slurped the \tr{.tar.gz} file, you should, {\em in
643 % the same directory as before}, do...
645 % % gunzip -c ghc-<version>-hc-files.tar.gz | tar xfv -
648 %************************************************************************
650 \subsection{Write-protecting your source files}
651 \index{write-protecting source files}
653 %************************************************************************
655 At this point, some people like to write-protect their source files against
659 find . -type f \! -name '*.hi' \! -name \*.hc \! -name '*.jm' -print \
663 %************************************************************************
665 \subsection{Running \tr{configure} and \tr{STARTUP} for GHC}
666 \index{configure, for GHC}
667 \index{STARTUP, for GHC}
669 %************************************************************************
671 The \tr{configure} script finds out things about your machine. It
672 also allows you to specify features to include/exclude from your GHC
675 Please see \sectionref{Configuring} for all about \tr{configure}, and
676 \sectionref{Configuring-GHC} for details of GHC configuring (including
679 Once \tr{configure} runs successfully, do as it says and do
682 %************************************************************************
684 \subsection{Build the compiler!}
685 \index{make all, for GHC}
687 %************************************************************************
689 Do the main GHC build, just as \tr{STARTUP} suggests:
692 % make all >& make.log
694 % make all >& make.log
696 If this fails or something seems suspicious, check the ``known
697 pitfalls'' (\sectionref{build-pitfalls}). If you can't figure out how
698 to proceed, please get in touch with us.
700 If you have to restart the build, for whatever reason, you are just as
701 well to make the whole thing; i.e., re-do as described above. (Well,
702 the \tr{compiler} and \tr{lib} subdirectories are the last two; if the
703 build ``dies'' in one of them, it is usually safe to finish the job by
706 %************************************************************************
708 \subsection[GHC_test]{Test that GHC seems to be working}
709 \index{testing a new GHC}
711 %************************************************************************
713 The way to do this is, of course, to compile and run {\em this} program
714 (in a file \tr{Main.hs}):
716 main = putStr "Hello, world!\n"
719 First, give yourself a convenient way to execute the driver script
720 \tr{ghc/driver/ghc}, perhaps something like...
722 % ln -s /local/src/ghc-2.01/ghc/driver/ghc ~/bin/alpha/ghc
726 Compile the program, using the \tr{-v} (verbose) flag to verify that
727 libraries, etc., are being found properly:
729 % ghc -v -o hello Main.hs
738 Some simple-but-profitable tests are to compile and run the
739 notorious \tr{nfib} program, using different numeric types. Start
740 with \tr{nfib :: Int -> Int}, and then try \tr{Integer}, \tr{Float},
741 \tr{Double}, \tr{Rational} and maybe \tr{Complex Float}. Code
742 for this is distributed in \tr{ghc/misc/examples/nfib/}.
744 For more information on how to ``drive'' GHC,
745 either do \tr{ghc -help} or consult the User's Guide (distributed in
746 \tr{ghc/docs/users_guide}).
748 %************************************************************************
750 \subsection[GHC_install]{Actually installing GHC}
751 \index{make install, GHC}
752 \index{installing, GHC}
754 %************************************************************************
756 ``Installing GHC'' means copying the files required to run it to their
757 ``permanent home.'' You can then delete, or at least tidy up, your
760 If you have no reason to install GHC, you can execute directly out of
761 the source tree, as sketched in the section above
762 (\sectionref{GHC_test}).
764 Assuming that everything's OK so far, all you need to do is:
768 % cd <very-top>/hslibs
772 If you're a little dubious (as I usually am), you can always do a
776 % make -n install >& temp-log-file-to-look-at
777 % cd <very-top>/hslibs
778 % make -n install >& temp-log-file-to-look-at
781 In both cases, if something breaks, it's a {\em bug}.
784 %************************************************************************
786 \subsection[make-docs]{Installing the GHC documentation (optional)}
787 \index{documentation, making}
788 \index{make docs, GHC}
789 \index{installing documentation}
791 %************************************************************************
793 Because our documentation is in DVI/Info/HTML formats, and because there is
794 no standard practice about how such documents are ``installed,'' we
795 haven't tried to automate this (at least not enough that we promise it
798 You can find all the documentation in the distribution with:
801 % find . \( -name '*.dvi' -o -name '*.info' -o -name '*.html' \) -print
804 If you have a standard place to put such files, just copy
805 them there. (Better ideas welcome.)
807 The following ``man'' pages are hidden around in the distribution:
809 ghc/utils/hp2ps/hp2ps.1
810 literate/info-utils/info.1
811 glafp-utils/scripts/mkdirhier.man
812 glafp-utils/scripts/lndir.man
814 Please install them by hand if you need to.
816 %There are various pieces of GHC whose code can be formatted
817 %``literately.'' The usual procedure is...
820 %% make depend # VERY IMPORTANT for literate docs!
821 %% make docs # or more directly....
822 %% make whatever.dvi # or, for Info freaks,...
823 %% make whatever.info
826 %For ``chunks'' of the compiler proper, in \tr{ghc/compiler}, you will
827 %need to make a \tr{Makefile} for them first:
830 %make Makefile SUBDIRS=prelude # for example...
832 %make depend # i.e., as before
835 %Directories for which this {\em might} (I emphasize: `MIGHT') work are ...
840 %podizeCore/Jmakefile
845 %Remember: an unpatched perl 4.035 will {\em crash} on making many of
846 %our ``literate'' Info files. (The current version, 4.036, will not.)
848 %$$ Note: Because we make our Info files by going through Texinfo format,
849 %$$ you can use \tr{texi2html} to produce HTML files. A
850 %$$ minisculely-hacked version is in the distribution in
851 %$$ \tr{literate/texi2html/texi2html}.
853 %************************************************************************
855 \subsection[clean-up]{Cleaning up after yourself}
856 \index{make clean, GHC}
857 \index{cleaning up afterwards}
859 %************************************************************************
861 \tr{make clean} is the basic command to tidy things up. However: if
862 you do this, {\em you will not be able to execute directly out of the
863 source tree thereafter!} (as sketched in \sectionref{GHC_test}). Nor will
864 you be able to make documents, etc.---you would have to re-build parts
867 If you want to execute out of the source tree but would like to clear
868 off lots and lots of stuff, you can do:
870 % cd ghc/lib # scrub library .hc and object files
872 % find . -name '*.o' -print | xargs /bin/rm
874 % cd hslibs/ # ditto for syslibs
875 % rm */src/*.hc */src/*.*_hc
877 % cd ghc/compiler # scrub compiler object files
879 % rm */*.hc # if you have been keeping them around
881 (You can scrub the object files in \tr{ghc/runtime} similarly---except
882 \tr{main/TopClosure*.o}.)
884 %\tr{make veryclean} is the command to clear off everything that can be
885 %safely cleared off. Not recommended (inadequately tested).
887 %************************************************************************
889 \section[booting-from-C]{Booting/porting from C (\tr{.hc}) files}
890 \index{building GHC from .hc files}
891 \index{booting GHC from .hc files}
893 %************************************************************************
895 This section is for people trying to get GHC going by using the
896 supplied intermediate C (\tr{.hc}) files. This would probably be
897 because no binaries have been provided, or because the machine
898 is not ``fully supported.''
900 To boot from C (\tr{.hc}) files, you need the regular source distribution
901 (\tr{ghc-2.01-src.tar.gz}) and also some extra files in
902 \tr{ghc-2.01-hc-files.tar.gz}. DON'T FORGET any extra \tr{.hc}
903 files for profiling, concurrent, parallel, ...
905 Whatever you want to build, just unpack all the files ``together'':
908 % gunzip -c ghc-2.01-src.tar.gz | tar xf -
909 % gunzip -c ghc-2.01-hc-files.tar.gz | tar xf - # basic...
910 % gunzip -c ghc-2.01-prof-hc-files.tar.gz | tar xf - # profiling...
911 % gunzip -c ghc-2.01-conc-hc-files.tar.gz | tar xf - # concurrent...
915 For the ``it's been tried before'' machines, the normal
916 configure/build procedure will probably work; just keep your eyes
919 WORD OF WISDOM: Be sure you have a suitable GCC (GNU C compiler); please
920 see \sectionref{port-info} for any specific requirements for your machine.
922 You'll need plenty of disk space to do this whole procedure!
924 %$$ %************************************************************************
926 %$$ \subsection[boot-file-fiddling]{Unpack; then fiddle files before booting}
928 %$$ %************************************************************************
930 %$$ Unpack the relevant files for booting as described above.
932 %$$ If you are on a never-seen-before platform, then there is a little
933 %$$ machine-specific code/stuff scattered around the GHC files, which will
934 %$$ need to be updated before you get started.
936 %$$ \begin{description}
937 %$$ %---------------------------------------------------------------------
938 %$$ \item[Change \tr{configure}, so it recognizes your machine:]
939 %$$ Add the obvious stuff if it says ``Unrecognised platform for GHC.''
941 %$$ If you are teaching GHC how to ``registerise'' on a new platform, you
942 %$$ will also need to make sure the variable @GhcWithRegisterised@ is set
945 %$$ %---------------------------------------------------------------------
946 %$$ \item[Change {\em two} copies of \tr{platform.h.in}:]
947 %$$ In the obvious way. They are in \tr{ghc/includes/} and \tr{mkworld/}.
949 %$$ %---------------------------------------------------------------------
950 %$$ \item[Floating-pointness:]
951 %$$ Grep for \tr{_TARGET} in \tr{ghc/includes/*.*h} and make suitable
954 %$$ One change you will certainly make is in \tr{StgMacros.lh}, to decide
955 %$$ the inclusion of \tr{ieee-flpt.h} and \tr{BIGENDIAN}.
957 %$$ Please use the CPP symbols defined in \tr{platform.h.in}!
959 %$$ %---------------------------------------------------------------------
960 %$$ \item[64-bitness:]
961 %$$ Again, grepping for \tr{_TARGET} in \tr{ghc/includes/*.lh} will find
962 %$$ the places that need adjusting. \tr{GhcConstants.lh} and
963 %$$ \tr{StgTypes.lh} are two places that will need tweaking, for example.
965 %$$ %---------------------------------------------------------------------
966 %$$ \item[``Registerizing'' magic:]
967 %$$ This is the platform-specific stuff in \tr{COptJumps.lh},
968 %$$ \tr{COptWraps.lh}, and \tr{MachRegs.lh} in \tr{ghc/includes}.
970 %$$ If you are doing an initial unregisterised boot for your platform, you
971 %$$ don't need to mess with these files at all.
973 %$$ \Sectionref{real-version-from-init-boot} discusses how to get a
974 %$$ ``registerised'' version of GHC going. (Much trickier, but much
975 %$$ faster. [0.26: and the documentation is OUT-OF-DATE])
977 %$$ %---------------------------------------------------------------------
978 %$$ \item[Host/target platforms in the driver:]
979 %$$ Grep for all occurrences of \tr{$HostPlatform} and \tr{$TargetPlatform}
980 %$$ in \tr{ghc/driver/*.lprl}.
982 %$$ Don't worry about the \tr{process_asm_block} stuff in
983 %$$ \tr{ghc-split.lprl}. Not used in a straight ``unregisterised''
986 %$$ %---------------------------------------------------------------------
987 %$$ \item[Target-specific GCC flags in the driver:]
989 %$$ The main thing to worry about in \tr{ghc.lprl} is the section on how
990 %$$ to ``Add on machine-specific C-compiler flags.''
991 %$$ You may want to add something {\em vaguely} like:
994 %$$ } elsif ($TargetPlatform =~ /^mips-dec-ultrix/) {
995 %$$ unshift(@CcBoth_flags, ('-G0', '-static')) if $GccAvailable;
998 %$$ Explanations: (1)~Static linking {\em tends} to give less problems, so
999 %$$ it is a reasonable choice for an initial attempt.
1001 %$$ (2)~In processing
1002 %$$ the intermediate C (\tr{.hc}) files, you are compiling some {\em huge}
1003 %$$ wads of C. Sadly, quite a few systems don't cope well with this, and
1004 %$$ more than a few silently produce object files that won't link. GCC
1005 %$$ usually provides some platform-specific flag that says ``generate code
1006 %$$ that will work no matter how big the files are''. The \tr{-G0} for
1007 %$$ DEC MIPS boxes is an example. If your system has such restrictions,
1008 %$$ insert some magic {\em here}!
1009 %$$ \end{description}
1011 %************************************************************************
1013 \subsection{Do \tr{configure}; \tr{sh < STARTUP}; \tr{cd ghc; make all}; test it!}
1014 \index{configure, GHC with .hc files}
1015 \index{make all, GHC with .hc files}
1017 %************************************************************************
1019 Go ahead and try \tr{configure}, as described \Sectionref{Configuring}
1020 (GHC specifics in \Sectionref{Configuring-GHC}).
1022 The key \tr{configure} option is \tr{--with-hc=c}. A typical
1023 going-via-C invocation might be:
1026 % ./configure --prefix=/local/fp --with-hc=c # basic + profiling
1029 Other common possibilities might be:
1032 % ./configure --with-hc=c --disable-profiling # basic only
1034 % ./configure --with-hc=c --enable-concurrent --enable-parallel
1035 # basic + profiling + concurrent + parallel
1038 %$$ One likely reason it won't work is it will say it never heard of your
1039 %$$ machine. Just edit the script and carry on! (As always, please send
1040 %$$ us the changes.)
1042 Next, run \tr{STARTUP} in the usual way, as described in
1043 \Sectionref{STARTUP}.
1045 It's now time to type \tr{cd ghc; make all}! This ``should'' work,
1046 especially, on a known machine. Also, it can take a VERY long time
1047 (esp. on oldish machines), so it's good to run overnight, on a quiet
1048 machine, nice'd, etc., etc.
1050 You will probably continue by building the system libraries:
1051 \tr{cd hslibs; make all}...
1053 When it's all built, test your alleged GHC system, as suggested in
1054 \sectionref{GHC_test}.
1056 %$$ What you should end up with, built in this order: (1)~a runtime system
1057 %$$ [\tr{ghc/runtime/libHSrts_ap.a}]; (2)~Prelude libraries
1058 %$$ [\tr{ghc/lib/libHS_ap.a} and \tr{ghc/lib/libHShbc_ap.a}]; and (3)~a
1059 %$$ compiler [\tr{ghc/compiler/hsc}] (which needs the first two).
1061 %$$ (Umm... if you are on a supported platform, but compiling via C, then
1062 %$$ the \tr{*.a} suffixes will be \tr{_ap_o.a} (regular) and \tr{_p.a}
1065 %$$ %************************************************************************
1067 %$$ \subsubsection{A pre-emptive \tr{hello, world} test}
1069 %$$ %************************************************************************
1071 %$$ On an unsupported platform,
1072 %$$ You very well may want to {\em kill the compilation} once
1073 %$$ \tr{libHSrts_ap.a} and \tr{libHS_ap.a} are built, to do a little
1074 %$$ pre-emptive testing: time to run \tr{Hello, world!}. Using
1075 %$$ \tr{ghc/CONTRIB/hello.hc}...
1076 %$$ \begin{verbatim}
1077 %$$ % .../ghc/driver/ghc -c -g hello.hc
1078 %$$ % .../ghc/driver/ghc -v -o hello -g hello.o
1082 %$$ If you have any trouble to do with ``consistency checking,'' just
1083 %$$ avoid it, with the \tr{-no-link-chk} flag.
1085 %$$ If \tr{hello} crashes/breaks, it's time for Ye Olde Debugger, or
1086 %$$ perhaps Ye Older Cry for Help...
1088 %$$ If things are OK and if you {\em did} kill the compilation, just re-do
1089 %$$ \tr{make} to finish the job (build any other libraries, then the
1090 %$$ compiler binary \tr{ghc/hsc}).
1092 %$$ %************************************************************************
1094 %$$ \subsubsection[init-boot-hsc]{Finishing the initial boot}
1096 %$$ %************************************************************************
1098 %$$ If you manage to get a \tr{ghc/hsc} binary (usually huge), then...
1099 %$$ YOU HAVE A HASKELL COMPILER, albeit big and slow! So test it,
1100 %$$ ``from the sources,'' before installing it:
1101 %$$ \begin{verbatim}
1103 %$$ main = print ((10001 - 30002)::Integer)
1104 %$$ -- or any other program(s) you want...
1106 %$$ % .../ghc/driver/ghc -v -g -c test.hs
1107 %$$ % .../ghc/driver/ghc -v -g -o test test.o
1110 %$$ (Note how I fiendishly included a \tr{-g}, in case I had to throw a
1111 %$$ debugger at it...)
1113 %$$ Of course, you {\em may not} have a \tr{ghc/hsc} binary---something
1114 %$$ went wrong. The most likely cause is a compiler/assembler/linker
1115 %$$ failure due to the HUGE size of this program. Please revisit the
1116 %$$ discussion about this towards the end of
1117 %$$ \sectionref{boot-file-fiddling}. Sadly, if you have to tweak
1118 %$$ C-compiler/whatever flags, you may have to rebuild all the
1119 %$$ libraries/compiler again; the following is sufficient to clear
1120 %$$ off everything for a fresh start (NB: don't do \tr{make clean}):
1121 %$$ \begin{verbatim}
1122 %$$ % cd ghc/runtime # clear off RTS
1123 %$$ % make clean SUBDIRS=foo # but avoid clearing GMP lib
1126 %$$ % cd ../compiler
1130 %$$ %************************************************************************
1132 %$$ \subsubsection[installing-init-boot]{`Installing' the initial boot}
1134 %$$ %************************************************************************
1136 %$$ If you are satisfied that things are working, {\em possibly install} the
1137 %$$ initial booted version. The main point is: save the precious files
1138 %$$ you've just created.
1140 %$$ Should you choose {\em not to install}, be sure to secure these files
1141 %$$ somewhere/somehow:
1142 %$$ \begin{verbatim}
1143 %$$ ghc/compiler/hsc # compiler
1144 %$$ ghc/runtime/libHSrts_ap.a # RTS things
1145 %$$ ghc/lib/libHS_ap.a # prelude library
1148 %$$ Should you install, the comments about `normal' installing, in
1149 %$$ \Sectionref{GHC_install}, do apply. It should come down to
1150 %$$ something like...
1151 %$$ \begin{verbatim}
1153 %$$ % make -n install >& temp-log-file-to-look-at # trial run: chk it out!
1154 %$$ % make install # the real thing...
1157 %$$ (I'd probably do the install by hand, if at all; let me know if you're
1158 %$$ worried about the exact incantations.)
1160 %$$ %************************************************************************
1162 %$$ \subsubsection[testing-init-boot]{Testing the initial boot}
1164 %$$ %************************************************************************
1166 %$$ It wouldn't be a bad idea, especially on an unusual machine; I usually
1167 %$$ just skip this part, though :-)
1169 %$$ %************************************************************************
1171 %$$ \subsection[split-libs]{Getting ``splitting'' going on your Prelude libraries}
1173 %$$ %************************************************************************
1177 %$$ %************************************************************************
1179 %$$ \subsection[real-version-from-init-boot]{Getting a ``registerised'' version going}
1181 %$$ %************************************************************************
1183 %$$ Version 0.26: THIS DOCUMENTATION IS OUT-OF-DATE. (Sigh)
1185 %$$ %************************************************************************
1187 %$$ \subsubsection[registerised-magic-files]{Setting up files for `registerizing'}
1189 %$$ %************************************************************************
1191 %$$ It's time to jiggle some files related to GCC-magic-optimisation.
1192 %$$ {\em This is real work, folks.} What follows is a {\em rough} guide to
1193 %$$ what needs looking at.
1195 %$$ \begin{description}
1196 %$$ %---------------------------------------------------------------------
1197 %$$ \item[\tr{ghc/includes/MachRegs.lh}:]
1198 %$$ This maps ``STG registers'' (Hp, SpA, TagReg, etc.) to machine
1199 %$$ registers on a platform-by-platform basis.
1200 %$$ If you can't figure it out, you'd probably better ask.
1202 %$$ We are using a GCC extension to put C global variables in specific
1203 %$$ registers; see the \tr{Global Reg Vars} node in the GCC documentation.
1205 %$$ You should get the idea from the settings for our ``fully supported''
1206 %$$ platforms, but you will need to know/learn something about your
1207 %$$ hardware and your GCC (e.g., what registers it snaffles for itself).
1209 %$$ One way I went about learning these register secrets was to try the
1210 %$$ following test file (a Sun3 version here, \tr{regs3.hc}):
1211 %$$ \begin{verbatim}
1212 %$$ #define StgPtr long int *
1214 %$$ register StgPtr FooL0 __asm__("a0");
1215 %$$ register StgPtr FooL1 __asm__("a1");
1216 %$$ register StgPtr FooL2 __asm__("a2");
1217 %$$ register StgPtr FooL3 __asm__("a3");
1218 %$$ register StgPtr FooL4 __asm__("a4");
1219 %$$ register StgPtr FooL5 __asm__("a5");
1220 %$$ register StgPtr FooL6 __asm__("a6");
1221 %$$ register StgPtr FooL7 __asm__("a7");
1223 %$$ register StgPtr FooG0 __asm__("d0");
1224 %$$ register StgPtr FooG1 __asm__("d1");
1225 %$$ register StgPtr FooG2 __asm__("d2");
1226 %$$ register StgPtr FooG3 __asm__("d3");
1227 %$$ register StgPtr FooG4 __asm__("d4");
1228 %$$ register StgPtr FooG5 __asm__("d5");
1229 %$$ register StgPtr FooG6 __asm__("d6");
1230 %$$ register StgPtr FooG7 __asm__("d7");
1235 %$$ return (x + 42);
1238 %$$ Then compile it repeatedly with your new driver, e.g.,
1239 %$$ \tr{ghc-boot-me -v -S regs3.hc}, removing register declarations that
1240 %$$ offend it. Note: GCC's error messages about these register things
1241 %$$ can be less than totally enlightening.
1243 %$$ Note: don't worry about warnings that you're stealing a
1244 %$$ ``call-clobbered'' (caller-saves) register. These are stealable,
1245 %$$ though some extra work may be required.
1247 %$$ %---------------------------------------------------------------------
1248 %$$ \item[\tr{ghc/includes/COptJumps.lh}:]
1249 %$$ The name of the game, essentially, is for the @JMP_@ macro to turn
1250 %$$ into a simple jump instruction. Also, through fiendish collaboration
1251 %$$ with the assembly-language post-processor in the driver (coming up
1252 %$$ soon...), we're going to rip out all the pushing/popping to do with
1255 %$$ You {\em may} need to do something as on 680x0s, where we inject
1256 %$$ beginning-of- and end-of-real-code markers, which gives the post-processor
1257 %$$ something to look out for and tidy up around.
1259 %$$ You also need to define some mini-interpreter-related macros. These
1260 %$$ are discussed under \tr{StgMiniInt.lc} (below).
1262 %$$ %---------------------------------------------------------------------
1263 %$$ \item[\tr{ghc/includes/COptWraps.lh}:]
1265 %$$ The macro @STGCALL1(f,a)@ is defined here; it almost certainly should
1266 %$$ just be \tr{callWrapper(f,a)} (where the magical routine @callWrapper@
1267 %$$ is yet to come).
1269 %$$ %---------------------------------------------------------------------
1270 %$$ \item[\tr{ghc/driver/ghc-asm-<arch>.lprl}:]
1271 %$$ This is the notorious ``optimised assembler post-processor.'' You
1272 %$$ need to create a suitable \tr{require}-able file (if you haven't
1273 %$$ already), add a mention in the \tr{Jmakefile}, and add suitable code
1274 %$$ in the driver, \tr{ghc.lprl} to invoke it.
1276 %$$ This is really quite horrible for a SPARC; we have to shut down the
1277 %$$ register-window mechanism {\em entirely}, by ripping out all the
1278 %$$ \tr{save} and \tr{restore} instructions.
1280 %$$ We also go to lots of trouble to move info tables next to entry code,
1281 %$$ elide slow and fast entry-point routines, and probably some things
1282 %$$ I've forgotten about.
1284 %$$ Ask if you are desperately confused...
1286 %$$ Perhaps it will be less gruesome for your machine!
1288 %$$ Don't forget to test it with \tr{-g} turned on (lots of \tr{\.stab?}
1289 %$$ lines suddenly appear)...
1291 %$$ %---------------------------------------------------------------------
1292 %$$ \item[\tr{CallWrap_C.lc} or \tr{CallWrapper.ls}, in ghc/runtime/c-as-asm/:]
1294 %$$ These files have register saving/restoring code. For a SPARC, quite a
1295 %$$ bit has to be written in assembly language (\tr{CallWrapper.ls}), to
1296 %$$ avoid register windowing; but, for other machines, the C versions
1297 %$$ (\tr{CallWrap_C.lc}) should work fine.
1299 %$$ Look at the generated assembly-language very carefully!
1301 %$$ %---------------------------------------------------------------------
1302 %$$ \item[ghc/runtime/c-as-asm/StgMiniInt.lc:]
1304 %$$ You need to manage to create entry points named @miniInterpret@ and
1305 %$$ @miniInterpretEnd@, the former to jump off into threaded code; the
1306 %$$ latter to come back to.
1308 %$$ You may be able to do something quite simple---it's not bad either for
1309 %$$ mc680x0s or SPARCs---but you will want to inspect the assembler output
1310 %$$ before declaring victory.
1312 %$$ In the SPARC case, it uses a macro (@MINI_INTERPRETER_END_IS_HERE@)
1313 %$$ defined in \tr{imports/COptJumps.lh}.
1314 %$$ \end{description}
1316 %$$ %************************************************************************
1318 %$$ \subsubsection[testing-registerisation]{Initial testing of a `registerisation'}
1320 %$$ %************************************************************************
1322 %$$ {\em How to begin testing this registerised stuff:}
1324 %$$ Make sure your imports files are up-to-date:
1325 %$$ \begin{verbatim}
1326 %$$ % cd ghc/includes
1330 %$$ Park yourself in your driver subdirectory and ...
1331 %$$ \begin{verbatim}
1332 %$$ % cd ghc/driver # park
1333 %$$ % make Makefile # if you changed "only4-ghc.ljm"...
1334 %$$ % make # just to be sure
1336 %$$ % cp ../compiler/utils/Util.hc temp.hc # grab a test file;
1337 %$$ # you may want to chop it down
1338 %$$ % ghc-boot-me -v -S -ddump-raw-asm temp.hc # see what happens!
1341 %$$ (The \tr{-ddump-raw-asm} option shows you, on stderr, what comes
1342 %$$ directly out of GCC. That's what your post-processing mangler has to
1345 %$$ {\em Going further on testing this stuff:}
1347 %$$ Another good place to practice is \tr{ghc/runtime}; so, for example:
1348 %$$ \begin{verbatim}
1349 %$$ % cd ghc/runtime
1352 %$$ % make libHSrts_ap_o.a
1355 %$$ The .s output from \tr{main/StgUpdate.lhc} can be particularly
1356 %$$ enlightening, in that, if you are going to have register spills (e.g.,
1357 %$$ because your registerisation choices left GCC with too few with which
1358 %$$ to generate good code), you will see it on this file.
1360 %$$ Don't forget: you need a working \tr{CallWrapper.ls} and
1361 %$$ \tr{StgMiniInt.lc} (both in \tr{c-as-asm}) before this registerised
1362 %$$ stuff will actually run.
1364 %$$ %************************************************************************
1366 %$$ \subsubsection[building-registerized]{Building the basics of a registerised GHC}
1368 %$$ %************************************************************************
1370 %$$ \begin{description}
1371 %$$ %---------------------------------------------------------------------
1372 %$$ \item[What you need to run a registerised program:]
1374 %$$ Once you make a \tr{libHSrts_ap_o.a} in runtime, all you need is a
1375 %$$ prelude library. You need to do it by hand still.
1376 %$$ \begin{verbatim}
1378 %$$ % ghc-boot-me -c -g -O -osuf _ap_o.o */*.hc # takes a while
1380 %$$ % rm libHS_ap_o.a
1381 %$$ % ar clq libHS_ap_o.a */*_ap_o.o
1382 %$$ % ranlib libHS_ap_o.a
1385 %$$ %---------------------------------------------------------------------
1386 %$$ \item[Testing the registerised GHC:]
1388 %$$ As before, starting with the \tr{.hc} you made in the first round:
1389 %$$ \begin{verbatim}
1390 %$$ % ghc-boot-me -v -g -c test.hc
1391 %$$ % ghc-boot-me -v -g -o test test.o
1395 %$$ If things are broken, the likely outcome is a core dump, and you'll
1396 %$$ need to throw GDB (or equiv) at it. Useful breakpoints are
1397 %$$ \tr{main}, \tr{miniInterpret}, \tr{Main_main_entry}, and
1398 %$$ \tr{startStgWorld} (when you're just getting going), and
1399 %$$ \tr{stopStgWorld} and \tr{miniInterpretEnd} (which can show that you
1400 %$$ ``almost made it'').
1402 %$$ %---------------------------------------------------------------------
1403 %$$ \item[If you get a consistency-checking error:]
1405 %$$ [From the driver] (These are not as terrible as they seem...)
1407 %$$ The driver, notably \tr{driver/ghc-consist.lprl}, runs the SCCS
1408 %$$ program \tr{what} over your executable, and tries to make sense of the
1411 %$$ If you need to make changes to \tr{ghc-consist.lprl}, just do so, then
1412 %$$ re-\tr{make} in the driver directory.
1414 %$$ %---------------------------------------------------------------------
1415 %$$ \item[Compiling the compiler registerisedly:]
1417 %$$ If you can successfully compile and run {\em some} registerised
1418 %$$ programs, you are probably ready to compile the compiler in that way.
1419 %$$ \begin{verbatim}
1420 %$$ % cd ghc/compiler
1421 %$$ % ghc-boot-me -c -g -O */*.hc # takes *much more* than a while
1422 %$$ % ghc-boot-me -g -O -o hsc */*.o # LINK!
1425 %$$ (Sun3 note: on the particular system I used, I had link troubles. It
1426 %$$ was apparently a Sun bug, because I got a successful link with the GNU
1429 %$$ %---------------------------------------------------------------------
1430 %$$ \item[Testing the {\em whole} registerised GHC:]
1432 %$$ As before, but now you can try compiling from \tr{.hs} to \tr{.hc}
1433 %$$ files with the newly-registerised \tr{hsc}.
1434 %$$ \end{description}
1436 %$$ %************************************************************************
1438 %$$ \subsubsection[real-version-fine-tuning]{Fine-tuning of a ``registerised'' version of GHC}
1440 %$$ %************************************************************************
1442 %$$ NOT FINISHED YET. Let me know if you get this far :-)
1446 %************************************************************************
1448 \subsection[Compiler_reconfig]{Building GHC again after you've bootstrapped}
1449 \index{GHC reconfiguration, after booting}
1450 \index{booting, then GHC reconfigure}
1451 \index{native-code generator, after booting}
1453 %************************************************************************
1455 Two reasons why you might want to re-configure and re-build GHC after
1456 an initial boot are: (a)~to get a native-code generator, or (b)~if you
1457 are going to hack on GHC.
1459 The reason you must rebuild to get a native-code generator: The
1460 \tr{.hc} files that we supply do {\em not} include a native-code generator.
1461 (They are supposed to work on and for any machine.)
1463 From here on, I presume you've installed your booted GHC as
1466 You can configure as before, but using \tr{--with-hc=ghc-2.01}
1467 (\tr{config.status} records what you did before).
1469 Running \tr{sh < STARTUP} isn't strictly necessary; you only need to
1470 rebuild in \tr{ghc/compiler}:
1472 cd ghc-2.01/ghc/compiler
1473 make Makefile # if you didn't STARTUP...
1475 make all EXTRA_HC_OPTS=-fvia-C # -fvia-C important!
1476 make all EXTRA_HC_OPTS=-fvia-C # again, until .hi files settle...
1479 You might want to to again test GHC ``out of the build'' before you
1480 type \tr{make install} in \tr{ghc/compiler} to finish the job.
1482 %************************************************************************
1484 \section[building-with-HBC]{Building GHC with HBC or other funny Haskell compilers}
1485 \index{GHC, building with HBC}
1486 \index{GHC, building with old GHCs}
1487 \index{GHC, building with other compilers}
1489 %************************************************************************
1491 GHC~2.01 doesn't build with HBC.
1493 GHC~2.01 can be built with:
1496 Provided you don't use \tr{-O} (i.e., configure with
1497 \tr{--disable-hsc-optimised})...
1500 Works fine, and builds the fastest compiler; but be sure to configure
1501 with \tr{--with-mkdependHS=blah}, where \tr{blah} is a name to invoke
1502 the \tr{mkdependHS} that comes with GHC~0.29.
1505 It works, but the resulting compiler is slower.
1508 %$$ If you are going to build the compiler with HBC,
1509 %$$ please get the appropriate set of \tr{.hi} interface
1510 %$$ files. If you going to build with an old GHC,
1511 %$$ visit your psychiatrist first.
1513 %$$ If you choose this route,
1514 %$$ you are well advised to get and install a set of \tr{.hi} interface
1515 %$$ files that were created by the same compiler you intend to use. If
1516 %$$ you intend to use HBC, we may provide a suitable ``spare'' set of \tr{.hi} files,
1517 %$$ in \tr{ghc-0.26-hi-files-hbc.tar.gz}, from an FTP site near you.
1519 %$$ Unpack the \tr{.hi} files in this {\em somewhat unobvious} way:
1520 %$$ \begin{verbatim}
1521 %$$ % cd ghc-0.26/ghc/compiler # **** this is where you want to be!!! ****
1523 %$$ % gunzip -c ghc-0.26-hi-files-hbc.tar.gz | tar xfv -
1526 %************************************************************************
1528 \section[Pre-supposed]{Installing pre-supposed utilities}
1529 \index{pre-supposed utilities}
1530 \index{utilities, pre-supposed}
1532 %************************************************************************
1534 Here are the gory details about some utility programs you may need;
1535 \tr{perl} and \tr{gcc} are the only important ones. (PVM is important
1536 if you're going for Parallel Haskell.) The \tr{configure} script will
1537 tell you if you are missing something.
1541 \index{pre-supposed: Perl}
1542 \index{Perl, pre-supposed}
1543 {\em You have to have Perl to proceed!} Perl is a language quite good
1544 for doing shell-scripty tasks that involve lots of text processing.
1545 It is pretty easy to install.
1547 (Perl~5 is the current version; GHC is still friendly to Perl~4 as well.)
1549 Perl should be put somewhere so that it can be invoked by the \tr{#!}
1550 script-invoking mechanism. (I believe \tr{/usr/bin/perl} is preferred;
1551 we use \tr{/usr/local/bin/perl} at Glasgow.) The full pathname should
1552 be less than 32 characters long.
1554 \item[GNU C (\tr{gcc}):]
1555 \index{pre-supposed: GCC (GNU C compiler)}
1556 \index{GCC (GNU C compiler), pre-supposed}
1557 The current version is 2.7.2, and has no problems that we know of.
1559 If your GCC dies with ``internal error'' on some GHC source file,
1560 please let us know, so we can report it and get things improved.
1561 (Exception: on \tr{iX86} boxes---you may need to fiddle with GHC's
1562 \tr{-monly-N-regs} option; ask if confused...)
1564 \item[PVM version 3:]
1565 \index{pre-supposed: PVM3 (Parallel Virtual Machine)}
1566 \index{PVM3 (Parallel Virtual Machine), pre-supposed}
1567 PVM is the Parallel Virtual Machine on which Parallel Haskell programs
1568 run. Underneath PVM, you can have (for example) a network of
1569 workstations (slow) or a multiprocessor box (faster).
1571 The current version of PVM is 3.3.11; we use 3.3.7. It is readily available on
1572 the net; I think I got it from \tr{research.att.com}, in \tr{netlib}.
1574 A PVM installation is slightly quirky, but easy to do. Just follow
1575 the \tr{Readme} instructions.
1577 \item[\tr{xargs} on Solaris2:]
1578 \index{xargs, presupposed (Solaris only)}
1579 \index{Solaris: alternative xargs}
1580 The GHC libraries are put together with something like:
1582 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
1584 Unfortunately the Solaris \tr{xargs} (the shell-script equivalent
1585 of \tr{map}) only ``bites off'' the \tr{.o} files a few at a
1586 time---with near-infinite rebuilding of the symbol table in
1589 The best solution is to install a sane \tr{xargs} from the GNU
1590 findutils distribution. You can unpack, build, and install the GNU
1591 version in the time the Solaris \tr{xargs} mangles just one GHC
1594 \item[\tr{bash} (Parallel Haskell only):]
1595 \index{bash, presupposed (Parallel Haskell only)}
1596 Sadly, the \tr{gr2ps} script, used to convert ``parallelism profiles''
1597 to PostScript, is written in Bash (GNU's Bourne Again shell).
1598 This bug will be fixed.
1601 \index{pre-supposed: makeindex}
1602 \index{makeindex, pre-supposed}
1603 You won't need this unless you are re-making our documents. Makeindex
1604 normally comes with a \TeX{} distribution, but if not, we can provide
1605 the latest and greatest.
1608 \index{pre-supposed: tgrind}
1609 \index{tgrind, pre-supposed}
1610 This is required only if you remake lots of our documents {\em and}
1611 you use the \tr{-t tgrind} option with \tr{lit2latex} (also literate
1612 programming), to do ``fancy'' typesetting of your code. {\em
1616 \index{pre-supposed: flex}
1617 \index{flex, pre-supposed}
1618 This is a quite-a-bit-better-than-Lex lexer. Used in the
1619 literate-programming stuff. You won't need it unless you're hacking
1620 on some of our more obscure stuff.
1622 \item[Something other than Sun's \tr{/usr/bin/yacc}:]
1623 \index{pre-supposed: non-worthless Yacc}
1624 \index{Yacc, pre-supposed}
1625 If you mess with the Haskell parser, you'll need a Yacc that can cope.
1626 The unbundled \tr{/usr/lang/yacc} is OK; the GNU \tr{bison} is OK;
1627 Berkeley yacc, \tr{byacc}, is not OK.
1630 %************************************************************************
1632 \section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
1633 \index{problems, building}
1634 \index{pitfalls, in building}
1635 \index{building pitfalls}
1637 %************************************************************************
1639 WARNINGS about pitfalls and known ``problems'':
1642 %------------------------------------------------------------------------
1644 One difficulty that comes up from time to time is running out of space
1645 in \tr{/tmp}. (It is impossible for the configuration stuff to
1646 compensate for the vagaries of different sysadmin approaches re temp
1649 The quickest way around it is \tr{setenv TMPDIR /usr/tmp} or
1650 even \tr{setenv TMPDIR .} (or the equivalent incantation with the
1651 shell of your choice).
1653 The best way around it is to use the \tr{--with-tmpdir=<dir>} option
1654 to \tr{configure}. Then GHC will use the appropriate directory
1657 %------------------------------------------------------------------------
1659 When configuring the support code (mkworld, glafp-utils, etc.), you
1660 will see mention of \tr{NO_SPECIFIC_PROJECT} and
1661 \tr{NO_SPECIFIC_VERSION}. This is cool.
1663 %------------------------------------------------------------------------
1665 In compiling some support-code bits, e.g., in \tr{ghc/runtime/gmp} and
1666 even in \tr{ghc/lib}, you may get a few C-compiler warnings. We think
1669 %------------------------------------------------------------------------
1671 When compiling via C, you'll sometimes get ``warning:
1672 assignment from incompatible pointer type'' out of GCC. Harmless.
1674 %------------------------------------------------------------------------
1676 %If you build an ``unregisterised'' build, you will get bazillions of
1677 %warnings about `ANSI C forbids braced-groups within expressions'.
1678 %Especially in \tr{ghc/lib}. These are OK.
1680 %------------------------------------------------------------------------
1682 Similarly, \tr{ar}chiving warning messages like the following are not
1685 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1686 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1690 %------------------------------------------------------------------------
1692 Also harmless are some specialisation messages that you may see when
1693 compiling GHC; e.g.:
1695 SPECIALISATION MESSAGES (Desirable):
1697 {-# SPECIALIZE instance Eq [Class] #-}
1698 {-# SPECIALIZE instance Eq (Class, [Class]) #-}
1699 {-# SPECIALIZE instance Outputable [ClassOp] #-}
1700 {-# SPECIALIZE instance Outputable [Id] #-}
1703 %------------------------------------------------------------------------
1705 In compiling the compiler proper (in \tr{compiler/}), you {\em may} get an
1706 ``Out of heap space'' error message. These
1707 can vary with the vagaries of different systems, it seems. The
1708 solution is simple: (1)~add a suitable \tr{-H} flag to the \tr{compile}
1709 macro for the offending module,
1710 in \tr{ghc/compiler/Jmakefile} (towards the end);
1711 (2)~re-\tr{make Makefile} in that directory; (3)~try again: \tr{make}.
1713 Alternatively, just cut to the chase scene:
1716 % make EXTRA_HC_OPTS=-H32m # or some nice big number
1719 %------------------------------------------------------------------------
1721 Not too long into the build process, you may get a huge complaint
1724 Giant error 'do'ing getopts.pl: at ./lit2pgm.BOOT line 27.
1726 This indicates that your \tr{perl} was mis-installed; the binary is
1727 unable to find the files for its ``built-in'' library. Speak to your
1728 perl installer, then re-try.
1730 %------------------------------------------------------------------------
1732 If you try to compile some Haskell, and you get errors from GCC
1733 about lots of things from \tr{/usr/include/math.h}, then your GCC
1734 was mis-installed. \tr{fixincludes} wasn't run when it should've
1737 As \tr{fixincludes} is now automagically run as part of GCC
1738 installation, this bug also suggests that you have an old GCC.
1740 %------------------------------------------------------------------------
1742 %Sooner or later in your ``make-worlding'' life you will do and see
1746 % rm -f Makefile.bak; mv Makefile Makefile.bak
1747 %../.././mkworld/jmake -P ghc -S std -I../.././mkworld -DTopDir=../../. -DTopDir=...
1748 %../.././mkworld/jrestoredeps
1749 %==== The new Makefile is for: ====
1750 %make: Fatal error in reader: Makefile, line 850: Unexpected end of line seen
1751 %Current working directory /export/users/fp/grasp/ghc-0.26/ghc/runtimes/standard
1753 %make: Fatal error: Command failed for target `Makefile'
1756 %Don't panic! It should restore your previous \tr{Makefile}, and
1757 %leave the junk one in \tr{Makefile.bad}. Snoop around at your leisure.
1759 %------------------------------------------------------------------------
1761 %If you do corrupt a \tr{Makefile} totally, or you need to glue a new
1762 %directory into the directory structure (in \tr{newdir}---which must
1763 %have a \tr{Jmakefile}, even if empty), here's a neat trick:
1766 %# move to the directory just above the one where you want a Makefile...
1769 %# make Makefiles, but lie about the directories below...
1770 %make Makefiles SUBDIRS=newdir
1773 %This will create a \tr{Makefile} {\em ex nihilo} in \tr{newdir}, and
1774 %it will be properly wired into the general make-world structure.
1776 %------------------------------------------------------------------------
1778 %Don't configure/build/install using a variety of machines. A
1779 %mistake we've made is to do \tr{make Makefiles} on a Sun4, then try to
1780 %build GHC (\tr{make all}) on a Sun3.
1782 %------------------------------------------------------------------------
1784 If you end up making documents that involve (La)TeX and/or \tr{tib}
1785 (Simon's favourite), the odds are that something about your/our setup
1786 will reach out and bite you. Yes, please complain; meanwhile,
1787 you can do \tr{make -n whatever.dvi} to see the intended commands,
1788 then try to muddle through, doing them by hand.
1790 %------------------------------------------------------------------------
1794 %************************************************************************
1796 \section[weird-configs]{Making weird GHC configurations}
1797 \index{GHC unusual configurations}
1799 %************************************************************************
1801 The usual way to build a ``weird'' GHC configuration is to turn
1802 various \tr{configure} knobs, e.g., \tr{--enable-concurrent}.
1803 Please see \sectionref{Configuring-GHC} about GHC configuring.
1805 If you want to build some Very Customised GHC libraries, it's
1806 probably best to send email to us, asking how.
1808 %$$ Usually, you will build whatever libraries your chosen ``setup''
1809 %$$ specifies. However, perhaps you are a hacker, and you want an extra
1810 %$$ ``ticky-ticky profiling'' version of the libraries. (Or, you want a
1811 %$$ version compiled with your Very Own Optimisation...)
1813 %$$ To create a ``user way'' or setup, put
1814 %$$ something like this somewhere (more on ``somewhere'', below):
1815 %$$ \begin{verbatim}
1816 %$$ #ifndef Build_UserWay_a
1817 %$$ #define Build_UserWay_a YES
1818 %$$ GHC_USER_WAY_FLAG_a = -ticky
1819 %$$ GHC_USER_WAY_OPTS_a = -fstg-reduction-counts -O
1820 %$$ #endif /* ! Build_UserWay_a */
1822 %$$ You'll be able to invoke the driver with a \tr{-ticky} option, which
1823 %$$ will be as if you typed in all that other stuff. It will also arrange
1824 %$$ that there is a version of the prelude (\tr{libHS_a.a} library,
1825 %$$ \tr{Prelude_a.hi} to match) and runtime system (\tr{libHSrts_a.a}) to
1826 %$$ match. (Neat, huh?)
1828 %$$ On the ``somewhere'' to specify what to build: If you don't plan
1829 %$$ to re-\tr{configure}, just change \tr{site-ghc.jm}. If you do plan to
1830 %$$ re-\tr{configure}, change \tr{site-ghc.jm.in} and re-\tr{configure}
1833 %$$ One note about {\em adding} ``user setups'' to an existing build:
1834 %$$ Besides remaking your \tr{Makefiles} straight away, {\em don't forget}
1835 %$$ to remake the driver (in \tr{ghc/driver}) before making any libraries!
1836 %$$ The short cut is:
1837 %$$ \begin{verbatim}
1838 %$$ cd ..../ghc/driver
1839 %$$ make Makefile; make all
1841 %$$ make Makefile; make all
1843 %$$ make Makefile; make all
1848 %************************************************************************
1850 \section[building-Haggis]{Building Haggis (Haskell GUI toolkit)}
1851 \index{Haggis, building}
1852 \index{building Haggis}
1854 %************************************************************************
1858 %************************************************************************
1860 \section[building-Happy]{Building Happy (Haskell parser generator)}
1861 \index{Happy, building}
1862 \index{building Happy}
1864 %************************************************************************
1868 %************************************************************************
1870 \section[building-NoFib]{Building NoFib (Haskell benchmark suite)}
1871 \index{NoFib suite, building}
1872 \index{building the NoFib suite}
1874 %************************************************************************
1878 %************************************************************************
1880 \section[Configuring]{Running \tr{configure}}
1881 \index{configure script}
1883 %************************************************************************
1885 The GNU-style \tr{configure} script figures out things which we need
1886 to know to build one or more Glasgow tools for your machine. Also,
1887 \tr{configure} lets you specify what you want built.
1889 Most people will configure/build one tool at a time. The
1890 ``short-cut'' instructions
1891 for GHC are in \sectionref{Configuring-GHC},
1892 for Haggis in \sectionref{Configuring-Haggis},
1893 for Happy in \sectionref{Configuring-Happy},
1894 and for NoFib in \sectionref{Configuring-NoFib}.
1896 However, \tr{configure} lets you pick and choose, so you can build
1897 several things ``in a one-er''. Just fling in all the options
1898 at once, and be amazed.
1900 %************************************************************************
1902 \subsection[Configuring-general]{\tr{configure} options for all tools}
1903 \index{Configuring (general)}
1905 %************************************************************************
1907 Many \tr{configure} options apply no matter what tools you are building.
1910 \item[\tr{--help}:] (a standard GNU option)
1911 \index{--help configure option}
1912 Prints out a long usage message. The first part is GNU boilerplate;
1913 after that is the Glasgow info.
1915 \item[\tr{--prefix=}{\em directory}:] (a standard GNU option)
1916 \index{--prefix configure option}
1917 Sets the ``root'' directory for where a system should be installed;
1918 defaults to \tr{/usr/local}.
1920 With Happy, for example, the main \tr{happy} binary will end up in
1921 \tr{/usr/local/bin/happy}.
1923 %--------------------------------------------------------------
1924 \item[\tr{--exec-prefix=}{\em directory}:] (a standard GNU option)
1925 \index{--exec-prefix configure option}
1926 Sets the ``root'' directory
1927 for where executables
1928 (e.g., the GHC driver) should be installed; defaults to whatever
1930 meaning that things will be installed in \tr{/usr/local/bin}.
1932 %$$ At Glasgow, we want such executables to go in (e.g.)
1933 %$$ \tr{/local/fp/bin.sun4}, so \tr{--exec-prefix} is no use to us.
1934 %$$ Happily, there's more than one way to do it!---just change
1935 %$$ \tr{InstBinDir_GHC} in \tr{ghc/mkworld/site-ghc.jm.in}... (We hope
1936 %$$ this doesn't bring back too many bad memories for our
1937 %$$ pre-\tr{configure} users.)
1939 %--------------------------------------------------------------
1940 \item[\tr{--with-hc=}{\em hask}:]
1941 \index{--with-hc configure option}
1942 Use {\em hask} as my ``installed Haskell compiler.''
1944 The name {\em hask} has to be one of \tr{ghc*} (for Glasgow Haskell),
1945 \tr{hbc*} (for Chalmers HBC), or \tr{nhc*} (for Rojemo's NHC).
1946 We hope to add more!
1948 As a special case, \tr{--with-hc=c} means ``I don't have a Haskell
1949 compiler, please compile from intermediate C files (produced by GHC
1952 %--------------------------------------------------------------
1953 \item[\tr{--with-mkdependHS=}{\em mkdep}:]
1954 \index{--with-mkdependHS configure option}
1956 Use {\em mkdep} as your \tr{mkdependHS} program. You should use the
1957 \tr{mkdependHS} that came with the GHC which you are probably
1958 specifying via \tr{--with-hc=...}.
1960 %--------------------------------------------------------------
1961 \item[\tr{--with-gcc=}{\em blah}:]
1962 \index{--with-gcc configure option}
1963 Use {\em blah} as my ``GNU C compiler.'' In case you have several,
1964 and want to chose a particular one.
1966 %--------------------------------------------------------------
1967 \item[\tr{--with-make=}{\em blub}:]
1968 \index{--with-make configure option}
1969 Ditto, for ``make''.
1971 %--------------------------------------------------------------
1972 \item[\tr{--with-tmpdir=}{\em directory}:]
1973 Set the directory where temporary files should be created. This is
1974 \tr{/tmp} by default, which is Sometimes Uncool (because, e.g.,
1975 \tr{/tmp} is too small). There's just no telling.
1977 On our Alphas, for example, we use \tr{--with-tmpdir=/usr/tmp}.
1979 %--------------------------------------------------------------
1980 \item[\tr{--with-max-heap=}{\em size}:]
1981 When whatever Haskell compiler is run while building the Glasgow
1982 tools, it will try to use some sane-but-not-too-big heap size. If you
1983 have a machine with plenty of memory, you might want to say ``Go ahead
1984 and use a great big heap.'' This option allows this. So, for
1985 example, on our Alphas we might say \tr{--with-max-heap=48m}.
1988 %************************************************************************
1990 \subsection[Configuring-GHC]{GHC-specific things in \tr{configure}}
1991 \index{Configuring for GHC}
1993 %************************************************************************
1995 The easiest way to see all the \tr{configure} options for GHC is to
1996 type \tr{./configure --help}. (I don't feel like typing the whole
1997 thing again, into this document...)
1999 Some common combinations would be:
2002 ./configure --prefix=/users/fp/partain --with-hc=c --disable-profiling
2003 # use .hc files; don't bother with profiling
2005 ./configure --with-hc=ghc-0.29 --with-readline-library --with-sockets-library
2006 # simple build with 0.29
2007 # For the extra libraries, you've got to have the right
2010 ./configure --with-hc=ghc-0.29 --disable-hsc-optimised --enable-hsc-debug
2011 # Don't use -O on GHC itself; turn on -DDEBUG.
2012 # Slows things down, but it's The Right Thing if
2013 # you're hacking on GHC and doing lots of recompilations.
2015 ./configure --with-hc=c --enable-concurrent --enable-parallel --with-tmpdir=/usr/tmp
2016 # Do everything from .hc files; besides the normal ones,
2017 # you'll need the "prof", "conc" and "par" .hc files.
2018 # Use /usr/tmp as TMPDIR...
2021 Remember, if you build \tr{--with-hc=c} on a Sun4 or Alpha, you
2022 do {\em not} have a native-code generator.
2024 %************************************************************************
2026 \subsection[Configuring-HsLibs]{Haskell-libraries-specific things in \tr{configure}}
2027 \index{Configuring the Haskell libraries}
2029 %************************************************************************
2031 The normal thing is: \tr{--enable-hslibs --with-hc-for-hslibs=in-place}.
2035 %************************************************************************
2037 \subsection[Configuring-Haggis]{Haggis-specific things in \tr{configure}}
2038 \index{Configuring for Haggis}
2040 %************************************************************************
2042 Use \tr{--enable-haggis}. If you have Haggis and GHC in the same
2043 build tree but only want to build Haggis, use \tr{--disable-ghc}.
2047 %************************************************************************
2049 \subsection[Configuring-Happy]{Happy-specific things in \tr{configure}}
2050 \index{Configuring for Happy}
2052 %************************************************************************
2054 Use \tr{--enable-happy}. If you have Happy and GHC in the same
2055 build tree but only want to build Happy, use \tr{--disable-ghc}.
2059 %************************************************************************
2061 \subsection[Configuring-NoFib]{NoFib-specific things in \tr{configure}}
2062 \index{Configuring for NoFib}
2064 %************************************************************************
2066 Use \tr{--enable-nofib --with-setup=ghc}.
2067 If you have NoFib and GHC in the same build
2068 tree but only want to build the NoFib suite, use \tr{--disable-ghc}.
2070 (If you were testing HBC on NoFib, you'd do \tr{--with-setup=hbc}, of course.)
2072 You may want to enable or disable various sets of tests, as
2073 suggested by \tr{./configure --help}. If you use \tr{--enable-all-tests},
2074 be aware that many of them are GHC-specific. Also, we may not have
2075 given you all of the source :-)
2077 %************************************************************************
2079 \section[STARTUP]{Running \tr{STARTUP}}
2080 \index{STARTUP script}
2082 %************************************************************************
2084 Once you've \tr{configure}d, utter the magic incantation:
2086 % sh < STARTUP >& startup.log
2088 The reason you might want to pipe the chatter into a file is so you
2089 can check it afterwards. It should be pretty obvious if it is happy.
2090 Note: it takes a little while.
2092 \tr{STARTUP} is a simple shell script that builds \tr{mkworld}
2093 (Makefile-generating system), \tr{literate} (literate-programming
2094 system), and \tr{glafp-utils} (a few utility programs); then makes the
2095 Makefiles and dependencies for everything.
2097 If you have any problems before getting through \tr{STARTUP}, you
2098 are probably best off re-running \tr{configure} and \tr{STARTUP}
2099 (after fixing what was broken).
2101 %************************************************************************
2103 \section[utils_install]{Installing the support software (optional)}
2104 \index{utilities, installing}
2106 %************************************************************************
2108 By default, the support software that comes with the Glasgow
2109 tools---\tr{mkworld}, \tr{literate}, and \tr{glafp-utils}---is not
2110 installed. However, they're generally-useful tools, so...
2112 If you did want to install the ``make world'' system, for example:
2114 % cd <very-top>/mkworld
2118 If it isn't installing things where you want it to, you can either
2119 fiddle things on the fly...
2121 % make install prefix=/home/sweet/home
2124 If you want to install just one utility, for example \tr{lndir}:
2126 % cd <very-top>/glafp-utils/scripts
2127 % make install_lndir
2130 ``Make world''---It slices, it dices... it's great!
2132 %************************************************************************
2134 \section[arrangement-of-sources]{Arrangement of the sources}
2136 %************************************************************************
2138 Once you un\tr{tar} the Glorious Haskell Compilation (GHC) system sources
2139 and \tr{cd} into the top directory, here's a bird's-eye view of what
2143 mkworld/ & ``Make world'' sub-system for configuring the system.\\
2145 glafp-utils/ & Utility programs and scripts used in building the distribution;\\
2146 & often acquired from elsewhere. \\
2147 literate/ & Glasgow literate programming sub-system. \\
2149 ghc/driver/ & The driver program for GHC; \\
2150 & currently a perl script, \tr{ghc}. \\
2152 ghc/compiler/ & The Haskell compiler proper, called \tr{hsc}; \\
2153 & source files are in \tr{compiler/*/[A-Z]*.lhs}. \\
2155 ghc/runtime/ & The runtime system, including the garbage-collector(s).\\
2157 ghc/lib/ & Source for the linked-in code for the ``standard prelude''. \\
2158 ghc/includes/ & The .h files \tr{#include}d in generated .hc files.\\
2160 ghc/docs/ & documents; see the README file there. \\
2162 ghc/CONTRIB/ & reserved for contributed things \\
2164 hslibs/ghc/ & `ghc' system library (syslib) \\
2165 hslibs/hbc/ & `hbc' system library \\
2166 hslibs/posix/ & `posix' system library \\
2167 hslibs/contrib/ & `contrib' system library \\
2169 haggis/ & Haggis Haskell X11 GUI toolkit \\
2170 happy/ & Happy Haskell parser generator \\
2171 nofib/ & NoFib Haskell benchmark and test suite \\
2174 \begin{onlystandalone}
2177 \end{onlystandalone}