13df5b500a19755ecf8419655be929dfb9d6df0c
[ghc.git] / ghc / docs / install_guide / installing.lit
1 %
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 $
3 %
4 \begin{onlystandalone}
5 \documentstyle[11pt,literate]{article}
6 \begin{document}
7 \title{Installing the Glasgow Functional Programming Tools\\
8 Version~0.26}
9 \author{The AQUA Team (scribe: Will Partain)\\
10 Department of Computing Science\\
11 University of Glasgow\\
12 Glasgow, Scotland\\
13 G12 8QQ\\
14 \\
15 Email: glasgow-haskell-\{request,bugs\}\@dcs.glasgow.ac.uk}
16 \maketitle
17 \begin{rawlatex}
18 \tableofcontents
19 \end{rawlatex}
20 \clearpage
21 \end{onlystandalone}
22
23 %************************************************************************
24 %*                                                                      *
25 \section[install-intro]{Introduction}
26 %*                                                                      *
27 %************************************************************************
28
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.
33
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...
38
39 %************************************************************************
40 %*                                                                      *
41 \subsection[install-strategy]{What to install?  Starting from what?}
42 %*                                                                      *
43 %************************************************************************
44
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!
49
50 Happily, such complications don't apply to most people.  A few common
51 ``strategies'' serve most purposes.  Pick one and proceed
52 as suggested:
53 \begin{description}
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!
59
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
64 on GHC yourself.
65
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}).
69
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}.
75
76 Once you have built GHC, you can build the other Glasgow tools with
77 it.
78
79 \item[Build GHC with another Haskell compiler (e.g., HBC):] Not
80 recommended, but see \sectionref{building-with-HBC}.
81 \end{description}
82
83 %************************************************************************
84 %*                                                                      *
85 \subsection[port-info]{What machines the Glasgow tools, version~0.26, run on}
86 \index{ports, GHC}
87 \index{GHC ports}
88 \index{supported platforms}
89 \index{platforms, supported}
90 %*                                                                      *
91 %************************************************************************
92
93 The main question is whether or not the Haskell compiler (GHC) runs on
94 your machine.
95
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.
98
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.
102
103 %************************************************************************
104 %*                                                                      *
105 \subsubsection{What machines the Haskell compiler (GHC) runs on}
106 %*                                                                      *
107 %************************************************************************
108 \index{fully-supported platforms}
109 \index{native-code generator}
110 \index{registerised ports}
111 \index{unregisterised ports}
112
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.
118
119 With GHC~0.26, we add ``registerised'' support for some HP-PA, iX86,
120 and MIPS platforms.
121
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.
125
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
128 identify
129
130 Note that some ports are fussy about which GCC version you use; or
131 require GAS; or ...
132
133 \begin{description}
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.
139
140 %-------------------------------------------------------------------
141 \item[\tr{sparc-sun-sunos4}:]
142 \index{sparc-sun-sunos4: fully supported}
143 Fully supported, including native-code generator.
144
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).
152
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.
160
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}
164
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.
170
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.
176
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}.
183
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}
189
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...)
197
198 No particularly recent GHC is known to work on a Mac.
199
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.
206
207 Concurrent/Parallel Haskell probably won't work (yet).
208 \index{m68k-next-nextstep3: concurrent---no}
209 \index{m68k-next-nextstep3: parallel---no}
210
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.
215
216 Concurrent/Parallel Haskell probably don't work (yet).
217 \index{m68k-sun-sunos4: concurrent---no}
218 \index{m68k-sun-sunos4: parallel---no}
219 \end{description}
220
221 %************************************************************************
222 %*                                                                      *
223 \subsubsection{What machines the other tools run on}
224 %*                                                                      *
225 %************************************************************************
226
227 Unless you hear otherwise, the other tools work if GHC works.
228
229 Haggis requires Concurrent Haskell to work.
230 \index{Haggis, Concurrent Haskell}
231
232 %************************************************************************
233 %*                                                                      *
234 \subsection{Things to check before you start typing}
235 %*                                                                      *
236 %************************************************************************
237
238 \begin{enumerate}
239 \item
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.
245
246 You'll need over 100MB (say, 20 hamburgers' worth) if you need to
247 build the basic stuff from scratch.
248
249 I don't yet know the disk requirements for the non-GHC tools.
250
251 All of the above are {\em estimates} of disk-space needs.
252
253 \item
254 Use an appropriate machine, compilers, and things.
255
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
258 thereof.
259
260 \item
261 Be sure that the ``pre-supposed'' utilities are installed.
262
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
267 regard.
268
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
272 [unlikely].
273
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.
277
278 \item
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.
283
284 For GHC, please see the bug-reporting section of the User's guide
285 (separate document), to maximise the usefulness of your report.
286
287 If in doubt, please send a message to
288 \tr{glasgow-haskell-bugs@dcs.glasgow.ac.uk}.
289 \end{enumerate}
290
291 %************************************************************************
292 %*                                                                      *
293 \section[installing-bin-distrib]{Installing from binary distributions (the most common case)}
294 \index{binary installations}
295 \index{installation, of binaries}
296 %*                                                                      *
297 %************************************************************************
298
299 Installing from binary distributions is easiest, and recommended!
300
301 %************************************************************************
302 %*                                                                      *
303 \subsection[GHC-bin-distrib]{GHC from binary distributions}
304 \index{GHC installation, from binaries}
305 \index{installation, GHC from binaries}
306 %*                                                                      *
307 %************************************************************************
308
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
314 proceed.)
315
316 Binary distributions come in ``bundles,''\index{bundles of binary stuff}
317 one bundle per \tr{.tar.gz} file.
318
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.
326
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:
330 \begin{description}
331 \item[\tr{prof}:]  Profiling with cost-centres.  You probably want this.
332
333 \item[\tr{conc}:] Concurrent Haskell features.  You may want this.
334
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.
337
338 \item[\tr{gran}:] The ``GranSim'' parallel-Haskell simulator
339 (hmm... mainly for implementors).
340
341 \item[\tr{ticky}:] ``Ticky-ticky'' profiling; very detailed
342 information about ``what happened when I ran this program''---really
343 for implementors.
344
345 \item[\tr{prof-conc}:] Cost-centre profiling for Concurrent Haskell.
346
347 \item[\tr{prof-ticky}:]  Ticky-ticky profiling for Concurrent Haskell.
348 \end{description}
349
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:
353
354 \begin{verbatim}
355 cd /put/them/in/here
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 -
359 \end{verbatim}
360
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.
365
366 %To check that you have all the pre-supposed utilities, please see
367 %\sectionref{Pre-supposed}.
368
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}.)
373
374 \begin{description}
375 %---------------------------------------------------------------------
376 \item[\tr{bin/<platform>} (sometimes just \tr{bin/}):]
377 Copy these executables so that they will be in users' PATHs.
378
379 %---------------------------------------------------------------------
380 \item[\tr{lib}:]
381 Move this directory, in toto, to wherever you want it to live.
382 It should still be called \tr{lib}.
383
384 %---------------------------------------------------------------------
385 \item[\tr{docs}:]
386 This is the full \tr{docs} tree.  Just follow the normal instructions,
387 in \sectionref{make-docs}.
388 \end{description}
389
390 Things you need to fiddle so the tools will spring to life:
391 \begin{enumerate}
392 \item
393 \tr{rehash} (csh users), so your shell will see the new stuff in your
394 bin directory.
395
396 \item
397 CHOICE \#1 (BETTER):
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:
402 \begin{verbatim}
403 # $ENV{'GLASGOW_HASKELL_ROOT'} = '/some/absolute/path/name';
404 \end{verbatim}
405 Remote the comment symbol (\tr{#}) on the front, and change the
406 path name to be the right thing.
407
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}.
410
411 \item
412 CHOICE \#2:
413 Set your \tr{GLASGOW_HASKELL_ROOT} environment variable, and
414 don't edit the \tr{ghc}, \tr{mkdependHS}, and \tr{hstags} scripts
415 at all.
416
417 It's better to edit the scripts; that way, it's once for all.
418
419 \item
420 You {\em may} need to re-\tr{ranlib} your libraries (on Sun4s).
421 \begin{verbatim}
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...
424 ?    ranlib $i
425 ?    # or, on some machines: ar s $i
426 ? end
427 \end{verbatim}
428
429 \item
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.
433
434 If things don't work, double-check your hand-edited path
435 names.  Things will go catastrophically wrong as long as they are
436 incorrect.
437 \end{enumerate}
438
439 %************************************************************************
440 %*                                                                      *
441 \subsection[non-GHC-bin-distrib]{Other tools from binary distributions}
442 %*                                                                      *
443 %************************************************************************
444
445 NOT DONE YET.
446
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.
450
451 %************************************************************************
452 %*                                                                      *
453 %\subsection[dumped-from-build]{Installing a ``dumped-from-build'' binary distribution (some platforms)}
454 %*                                                                      *
455 %************************************************************************
456 %#% 
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.
460 %#% 
461 %#% The setup required is nearly the same as a ``regular'' binary
462 %#% distribution; only some names are different.
463 %#% \begin{enumerate}
464 %#% \item
465 %#% Get the user-executable scripts into your PATH, either by copying it
466 %#% or by linking to it.  These are in:
467 %#% \begin{verbatim}
468 %#% <topdir>/ghc/driver/ghc
469 %#% <topdir>/ghc/utils/mkdependHS/mkdependHS
470 %#% <topdir>/ghc/utils/hstags/hstags
471 %#% \end{verbatim}
472 %#% 
473 %#% \item
474 %#% Set the \tr{GLASGOW_HASKELL_ROOT} environment variable for the three
475 %#% scripts above, in the manner outlined in the previous section.
476 %#% 
477 %#% \item
478 %#% Possibly re-\tr{ranlib}'ing  your \tr{*.a} files:
479 %#% \begin{verbatim}
480 %#% % cd <topdir>
481 %#% % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
482 %#% %    ranlib $i
483 %#% %    # or, on some machines: ar s $i
484 %#% % end
485 %#% \end{verbatim}
486 %#% 
487 %#% \item
488 %#% Don't forget to test it!
489 %#% \end{enumerate}
490
491 %************************************************************************
492 %*                                                                      *
493 \section[checklist]{Building Glasgow tools from source: a checklist}
494 %*                                                                      *
495 %************************************************************************
496
497 \begin{enumerate}
498 \item
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}.
502
503 \item
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
508 adopt.
509
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}.
514
515 \item
516 You might want to write-protect your source files at this point:
517 \begin{verbatim}
518 cd <the-very-top-dir>
519 find . -type f \! -name \*.hi \! -name \*.hc \! -name \*.jm -print \
520         | xargs chmod a-w
521 \end{verbatim}
522
523 \item
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}.
528
529 \item
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:
533 \begin{verbatim}
534 % cd <the-very-top-dir>
535 % sh < STARTUP >& startup.log   # and chk the log afterwards!
536 \end{verbatim}
537
538 \item
539 Build the Glasgow tools you are interested in, as \tr{STARTUP} suggests:
540 \begin{verbatim}
541 % cd <the-very-top-dir>/<tool>
542 % make all >& make.log          # time to go to lunch!
543 \end{verbatim}
544 Consult the list of known pitfalls (\sectionref{build-pitfalls}) if
545 something goes wrong.
546
547 \item
548 Test what you've built, enough to know that it's working.
549
550 \item
551 Actually install the tools, if you wish:
552 \begin{verbatim}
553 % cd <the-very-top-dir>/<tool>
554 % make install
555 \end{verbatim}
556
557 \item
558 Make and/or install the documentation.
559
560 \item
561 Save a copy of your \tr{config.status} file, for the next
562 even-more-wonderful release!
563
564 \item
565 If you're finished, tidy up after yourself [\tr{make clean}], if you
566 want to.
567
568 Alternatively, \tr{/bin/rm -rf <tool>} :-)
569 \end{enumerate}
570
571 %************************************************************************
572 %*                                                                      *
573 \section[building-GHC]{Building the Glasgow Haskell Compiler (GHC)}
574 \index{GHC installation, from sources}
575 %*                                                                      *
576 %************************************************************************
577
578 %************************************************************************
579 %*                                                                      *
580 \downsection
581 \section{Building GHC from source, compiling it with itself}
582 \index{building GHC with itself}
583 \index{booting GHC with itself}
584 %*                                                                      *
585 %************************************************************************
586
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.
592
593 This blow-by-blow description follows the general checklist in
594 \sectionref{checklist}.
595
596 %************************************************************************
597 %*                                                                      *
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}
600 %*                                                                      *
601 %************************************************************************
602
603 We now proceed through each installation step, carefully.
604
605 Because the compiler heart of Glorious Glasgow Haskell is written in
606 Haskell, you have to use some ``bootstrapping'' mechanism.
607
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.
612
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.
616
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.
619
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.
624
625 % If you have to boot from C (\tr{.hc}) files, you should follow the
626 % directions in \sectionref{booting-from-C}.
627
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...
634 % \begin{verbatim}
635 % % gunzip -c ghc-<version>-hc-files.tar.gz | tar xfv -
636 % \end{verbatim}
637
638 %************************************************************************
639 %*                                                                      *
640 \subsection{Write-protecting your source files}
641 \index{write-protecting source files}
642 %*                                                                      *
643 %************************************************************************
644
645 At this point, some people like to write-protect their source files against
646 inadvertent change:
647 \begin{verbatim}
648 cd <very-top-dir>
649 find . -type f \! -name '*.hi' \! -name \*.hc \! -name '*.jm' -print \
650         | xargs chmod a-w
651 \end{verbatim}
652
653 %************************************************************************
654 %*                                                                      *
655 \subsection{Running \tr{configure} and \tr{STARTUP} for GHC}
656 \index{configure, for GHC}
657 \index{STARTUP, for GHC}
658 %*                                                                      *
659 %************************************************************************
660
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
663 installation.
664
665 Please see \sectionref{Configuring} for all about \tr{configure}, and
666 \sectionref{Configuring-GHC} for details of GHC configuring (including
667 examples).
668
669 Once \tr{configure} runs successfully, do as it says and do
670 \tr{sh < STARTUP}.
671
672 %************************************************************************
673 %*                                                                      *
674 \subsection{Build the compiler!}
675 \index{make all, for GHC}
676 %*                                                                      *
677 %************************************************************************
678
679 Do the main GHC build, just as \tr{STARTUP} suggests:
680 \begin{verbatim}
681 % cd ghc
682 % make all >& make.log
683 \end{verbatim}
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.
687
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
692 hand.)
693
694 %************************************************************************
695 %*                                                                      *
696 \subsection[GHC_test]{Test that GHC seems to be working}
697 \index{testing a new GHC}
698 %*                                                                      *
699 %************************************************************************
700
701 The way to do this is, of course, to compile and run {\em this} program
702 (in a file \tr{Main.hs}):
703 \begin{verbatim}
704 main = putStr "Hello, world!\n"
705 \end{verbatim}
706
707 First, give yourself a convenient way to execute the driver script
708 \tr{ghc/driver/ghc}, perhaps something like...
709 \begin{verbatim}
710 % ln -s /local/src/ghc-0.26/ghc/driver/ghc ~/bin/sun4/ghc
711 % rehash
712 \end{verbatim}
713
714 Compile the program, using the \tr{-v} (verbose) flag to verify that
715 libraries, etc., are being found properly:
716 \begin{verbatim}
717 % ghc -v -o hello -fhaskell-1.3 Main.hs
718 \end{verbatim}
719
720 Now run it:
721 \begin{verbatim}
722 % ./hello
723 Hello, world!
724 \end{verbatim}
725
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/}.
731
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}).
735
736 %************************************************************************
737 %*                                                                      *
738 \subsection[GHC_install]{Actually installing GHC}
739 \index{make install, GHC}
740 \index{installing, GHC}
741 %*                                                                      *
742 %************************************************************************
743
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
746 source directory.
747
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}).
751
752 Assuming that everything's OK so far, all you need to do is:
753 \begin{verbatim}
754 % cd <very-top>/ghc
755 % make install
756 \end{verbatim}
757
758 If you're a little dubious (as I usually am), you can always do a
759 ``trial run'' first:
760 \begin{verbatim}
761 % cd <very-top>/ghc
762 % make -n install >& temp-log-file-to-look-at
763 \end{verbatim}
764
765 In both cases, if something breaks, it's a {\em bug}.
766
767
768 %************************************************************************
769 %*                                                                      *
770 \subsection[make-docs]{Installing the GHC documentation (optional)}
771 \index{documentation, making}
772 \index{make docs, GHC}
773 \index{installing documentation}
774 %*                                                                      *
775 %************************************************************************
776
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
780 works).
781
782 You can find all the documentation in the distribution with:
783 \begin{verbatim}
784 % cd ghc/docs
785 % find . \( -name '*.dvi' -o -name '*.info' -o -name '*.html' \) -print
786 \end{verbatim}
787
788 If you have a standard place to put such files, just copy
789 them there.  (Better ideas welcome.)
790
791 The following ``man'' pages are hidden around in the distribution:
792 \begin{verbatim}
793 ghc/utils/hp2ps/hp2ps.1
794 literate/info-utils/info.1
795 glafp-utils/scripts/mkdirhier.man
796 glafp-utils/scripts/lndir.man
797 \end{verbatim}
798 Please install them by hand if you need to.
799
800 %There are various pieces of GHC whose code can be formatted
801 %``literately.''  The usual procedure is...
802 %\begin{verbatim}
803 %% cd ghc/<wherever>
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
808 %\end{verbatim}
809
810 %For ``chunks'' of the compiler proper, in \tr{ghc/compiler}, you will
811 %need to make a \tr{Makefile} for them first:
812 %\begin{verbatim}
813 %cd ghc/compiler
814 %make Makefile SUBDIRS=prelude  # for example...
815 %cd prelude
816 %make depend        # i.e., as before
817 %make prelude.dvi
818 %\end{verbatim}
819 %Directories for which this {\em might} (I emphasize: `MIGHT') work are ...
820 %\begin{verbatim}
821 %codeGen/Jmakefile
822 %coreSyn/Jmakefile
823 %deSugar/Jmakefile
824 %podizeCore/Jmakefile
825 %prelude/Jmakefile
826 %typecheck/Jmakefile
827 %\end{verbatim}
828 %
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.)
831
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}.
836
837 %************************************************************************
838 %*                                                                      *
839 \subsection[clean-up]{Cleaning up after yourself}
840 \index{make clean, GHC}
841 \index{cleaning up afterwards}
842 %*                                                                      *
843 %************************************************************************
844
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
849 of GHC first.
850
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:
853 \begin{verbatim}
854 % cd ghc/lib    # scrub library C and object files
855 % rm */*.hc
856 % find . -name '*.o' -print | xargs /bin/rm
857
858 % cd ghc/compiler   # scrub compiler object files
859 % rm */*.o
860 % rm */*.hc         # if you have been keeping them around
861 \end{verbatim}
862 (You can scrub the object files in \tr{ghc/runtime} similarly---except
863 \tr{main/TopClosure*.o}.)
864
865 %\tr{make veryclean} is the command to clear off everything that can be
866 %safely cleared off.  Not recommended (inadequately tested).
867
868 %************************************************************************
869 %*                                                                      *
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}
873 %*                                                                      *
874 %************************************************************************
875
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.''
880
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, ...
885
886 Whatever you want to build, just unpack all the files ``together'':
887 \begin{verbatim}
888 % cd <wherever>
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...
893 ... etc ...
894 \end{verbatim}
895
896 For the ``it's been tried before'' machines, the normal
897 configure/build procedure will probably work; just keep your eyes
898 peeled for mischief.
899
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.
902
903 You'll need plenty of disk space to do this whole procedure!
904
905 %$$ %************************************************************************
906 %$$ %*                                                                  *
907 %$$ \subsection[boot-file-fiddling]{Unpack; then fiddle files before booting}
908 %$$ %*                                                                  *
909 %$$ %************************************************************************
910 %$$ 
911 %$$ Unpack the relevant files for booting as described above.
912 %$$ 
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.
916 %$$ 
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.''
921 %$$ 
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
924 %$$ correctly.
925 %$$ 
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/}.
929 %$$ 
930 %$$ %---------------------------------------------------------------------
931 %$$ \item[Floating-pointness:]
932 %$$ Grep for \tr{_TARGET} in \tr{ghc/includes/*.*h} and make suitable
933 %$$ adjustments.
934 %$$ 
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}.
937 %$$ 
938 %$$ Please use the CPP symbols defined in \tr{platform.h.in}!
939 %$$ 
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.
945 %$$ 
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}.
950 %$$ 
951 %$$ If you are doing an initial unregisterised boot for your platform, you
952 %$$ don't need to mess with these files at all.
953 %$$ 
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])
957 %$$ 
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}.
962 %$$ 
963 %$$ Don't worry about the \tr{process_asm_block} stuff in
964 %$$ \tr{ghc-split.lprl}.  Not used in a straight ``unregisterised''
965 %$$ version.
966 %$$ 
967 %$$ %---------------------------------------------------------------------
968 %$$ \item[Target-specific GCC flags in the driver:]
969 %$$ 
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:
973 %$$ \begin{verbatim}
974 %$$ ...
975 %$$ } elsif ($TargetPlatform =~ /^mips-dec-ultrix/) {
976 %$$     unshift(@CcBoth_flags,  ('-G0', '-static')) if $GccAvailable;
977 %$$ \end{verbatim}
978 %$$ 
979 %$$ Explanations: (1)~Static linking {\em tends} to give less problems, so
980 %$$ it is a reasonable choice for an initial attempt.
981 %$$ 
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}
991
992 %************************************************************************
993 %*                                                                      *
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}
997 %*                                                                      *
998 %************************************************************************
999
1000 Go ahead and try \tr{configure}, as described \Sectionref{Configuring}
1001 (GHC specifics in \Sectionref{Configuring-GHC}).
1002
1003 The key \tr{configure} option is \tr{--with-hc=c}.  A typical
1004 going-via-C invocation might be:
1005
1006 \begin{verbatim}
1007 % ./configure  --prefix=/local/fp --with-hc=c   # basic + profiling
1008 \end{verbatim}
1009
1010 Other common possibilities might be:
1011
1012 \begin{verbatim}
1013 % ./configure --with-hc=c --disable-profiling   # basic only
1014
1015 % ./configure --with-hc=c --enable-concurrent --enable-parallel
1016         # basic + profiling + concurrent + parallel
1017 \end{verbatim}
1018
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.)
1022
1023 Next, run \tr{STARTUP} in the usual way, as described in
1024 \Sectionref{STARTUP}.
1025
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.
1030
1031 When it's all built, test your alleged GHC system, as suggested in
1032 \sectionref{GHC_test}.
1033
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).
1038 %$$ 
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}
1041 %$$ (profiling).)
1042
1043 %$$ %************************************************************************
1044 %$$ %*                                                                  *
1045 %$$ \subsubsection{A pre-emptive \tr{hello, world} test}
1046 %$$ %*                                                                  *
1047 %$$ %************************************************************************
1048 %$$ 
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
1057 %$$ % ./hello
1058 %$$ \end{verbatim}
1059 %$$ 
1060 %$$ If you have any trouble to do with ``consistency checking,'' just
1061 %$$ avoid it, with the \tr{-no-link-chk} flag.
1062 %$$ 
1063 %$$ If \tr{hello} crashes/breaks, it's time for Ye Olde Debugger, or
1064 %$$ perhaps Ye Older Cry for Help...
1065 %$$ 
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}).
1069 %$$ 
1070 %$$ %************************************************************************
1071 %$$ %*                                                                  *
1072 %$$ \subsubsection[init-boot-hsc]{Finishing the initial boot}
1073 %$$ %*                                                                  *
1074 %$$ %************************************************************************
1075 %$$ 
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}
1080 %$$ % cat > test.hs
1081 %$$ main = print ((10001 - 30002)::Integer)
1082 %$$ -- or any other program(s) you want...
1083 %$$ ^D
1084 %$$ % .../ghc/driver/ghc -v -g -c test.hs
1085 %$$ % .../ghc/driver/ghc -v -g -o test test.o
1086 %$$ % ./test
1087 %$$ \end{verbatim}
1088 %$$ (Note how I fiendishly included a \tr{-g}, in case I had to throw a
1089 %$$ debugger at it...)
1090 %$$ 
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
1102 %$$ % cd ../lib
1103 %$$ % rm */*.o
1104 %$$ % cd ../compiler
1105 %$$ % rm */*.o
1106 %$$ \end{verbatim}
1107 %$$ 
1108 %$$ %************************************************************************
1109 %$$ %*                                                                  *
1110 %$$ \subsubsection[installing-init-boot]{`Installing' the initial boot}
1111 %$$ %*                                                                  *
1112 %$$ %************************************************************************
1113 %$$ 
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.
1117 %$$ 
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
1124 %$$ \end{verbatim}
1125 %$$ 
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}
1130 %$$ % cd ghc
1131 %$$ % make -n install >& temp-log-file-to-look-at # trial run: chk it out!
1132 %$$ % make install                                    # the real thing...
1133 %$$ \end{verbatim}
1134 %$$ 
1135 %$$ (I'd probably do the install by hand, if at all; let me know if you're
1136 %$$ worried about the exact incantations.)
1137 %$$ 
1138 %$$ %************************************************************************
1139 %$$ %*                                                                  *
1140 %$$ \subsubsection[testing-init-boot]{Testing the initial boot}
1141 %$$ %*                                                                  *
1142 %$$ %************************************************************************
1143 %$$ 
1144 %$$ It wouldn't be a bad idea, especially on an unusual machine; I usually
1145 %$$ just skip this part, though :-)
1146 %$$ 
1147 %$$ %************************************************************************
1148 %$$ %*                                                                  *
1149 %$$ \subsection[split-libs]{Getting ``splitting'' going on your Prelude libraries}
1150 %$$ %*                                                                  *
1151 %$$ %************************************************************************
1152 %$$ 
1153 %$$ ghc-split.lprl
1154 %$$ 
1155 %$$ %************************************************************************
1156 %$$ %*                                                                  *
1157 %$$ \subsection[real-version-from-init-boot]{Getting a ``registerised'' version going}
1158 %$$ %*                                                                  *
1159 %$$ %************************************************************************
1160 %$$ 
1161 %$$ Version 0.26: THIS DOCUMENTATION IS OUT-OF-DATE.  (Sigh)
1162 %$$ 
1163 %$$ %************************************************************************
1164 %$$ %*                                                                  *
1165 %$$ \subsubsection[registerised-magic-files]{Setting up files for `registerizing'}
1166 %$$ %*                                                                  *
1167 %$$ %************************************************************************
1168 %$$ 
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.
1172 %$$ 
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.
1179 %$$ 
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.
1182 %$$ 
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).
1186 %$$ 
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 *
1191 %$$ 
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");
1200 %$$ 
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");
1209 %$$ 
1210 %$$ wurble(x)
1211 %$$ int x;
1212 %$$ {
1213 %$$   return (x + 42);
1214 %$$ }
1215 %$$ \end{verbatim}
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.
1220 %$$ 
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.
1224 %$$ 
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
1231 %$$ the C stack.
1232 %$$ 
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.
1236 %$$ 
1237 %$$ You also need to define some mini-interpreter-related macros.  These
1238 %$$ are discussed under \tr{StgMiniInt.lc} (below).
1239 %$$ 
1240 %$$ %---------------------------------------------------------------------
1241 %$$ \item[\tr{ghc/includes/COptWraps.lh}:]
1242 %$$ 
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).
1246 %$$ 
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.
1253 %$$ 
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.
1257 %$$ 
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.
1261 %$$ 
1262 %$$ Ask if you are desperately confused...
1263 %$$ 
1264 %$$ Perhaps it will be less gruesome for your machine!
1265 %$$ 
1266 %$$ Don't forget to test it with \tr{-g} turned on (lots of \tr{\.stab?}
1267 %$$ lines suddenly appear)...
1268 %$$ 
1269 %$$ %---------------------------------------------------------------------
1270 %$$ \item[\tr{CallWrap_C.lc} or \tr{CallWrapper.ls}, in ghc/runtime/c-as-asm/:]
1271 %$$ 
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.
1276 %$$ 
1277 %$$ Look at the generated assembly-language very carefully!
1278 %$$ 
1279 %$$ %---------------------------------------------------------------------
1280 %$$ \item[ghc/runtime/c-as-asm/StgMiniInt.lc:]
1281 %$$ 
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.
1285 %$$ 
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.
1289 %$$ 
1290 %$$ In the SPARC case, it uses a macro (@MINI_INTERPRETER_END_IS_HERE@)
1291 %$$ defined in \tr{imports/COptJumps.lh}.
1292 %$$ \end{description}
1293 %$$ 
1294 %$$ %************************************************************************
1295 %$$ %*                                                                  *
1296 %$$ \subsubsection[testing-registerisation]{Initial testing of a `registerisation'}
1297 %$$ %*                                                                  *
1298 %$$ %************************************************************************
1299 %$$ 
1300 %$$ {\em How to begin testing this registerised stuff:}
1301 %$$ 
1302 %$$ Make sure your imports files are up-to-date:
1303 %$$ \begin{verbatim}
1304 %$$ % cd ghc/includes
1305 %$$ % make
1306 %$$ \end{verbatim}
1307 %$$ 
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
1313 %$$ 
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!
1317 %$$ \end{verbatim}
1318 %$$ 
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
1321 %$$ chomp on.)
1322 %$$ 
1323 %$$ {\em Going further on testing this stuff:}
1324 %$$ 
1325 %$$ Another good place to practice is \tr{ghc/runtime}; so, for example:
1326 %$$ \begin{verbatim}
1327 %$$ % cd ghc/runtime
1328 %$$ % make Makefile
1329 %$$ % make clean
1330 %$$ % make libHSrts_ap_o.a
1331 %$$ \end{verbatim}
1332 %$$ 
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.
1337 %$$ 
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.
1341 %$$ 
1342 %$$ %************************************************************************
1343 %$$ %*                                                                  *
1344 %$$ \subsubsection[building-registerized]{Building the basics of a registerised GHC}
1345 %$$ %*                                                                  *
1346 %$$ %************************************************************************
1347 %$$ 
1348 %$$ \begin{description}
1349 %$$ %---------------------------------------------------------------------
1350 %$$ \item[What you need to run a registerised program:]
1351 %$$ 
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}
1355 %$$ % cd ghc/lib
1356 %$$ % ghc-boot-me -c -g -O -osuf _ap_o.o */*.hc # takes a while
1357 %$$ %
1358 %$$ % rm libHS_ap_o.a
1359 %$$ % ar clq libHS_ap_o.a */*_ap_o.o
1360 %$$ % ranlib libHS_ap_o.a
1361 %$$ \end{verbatim}
1362 %$$ 
1363 %$$ %---------------------------------------------------------------------
1364 %$$ \item[Testing the registerised GHC:]
1365 %$$ 
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
1370 %$$ % ./test
1371 %$$ \end{verbatim}
1372 %$$ 
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'').
1379 %$$ 
1380 %$$ %---------------------------------------------------------------------
1381 %$$ \item[If you get a consistency-checking error:]
1382 %$$ 
1383 %$$ [From the driver] (These are not as terrible as they seem...)
1384 %$$ 
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
1387 %$$ output.
1388 %$$ 
1389 %$$ If you need to make changes to \tr{ghc-consist.lprl}, just do so, then
1390 %$$ re-\tr{make} in the driver directory.
1391 %$$ 
1392 %$$ %---------------------------------------------------------------------
1393 %$$ \item[Compiling the compiler registerisedly:]
1394 %$$ 
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!
1401 %$$ \end{verbatim}
1402 %$$ 
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
1405 %$$ linker.)
1406 %$$ 
1407 %$$ %---------------------------------------------------------------------
1408 %$$ \item[Testing the {\em whole} registerised GHC:]
1409 %$$ 
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}
1413 %$$ 
1414 %$$ %************************************************************************
1415 %$$ %*                                                                  *
1416 %$$ \subsubsection[real-version-fine-tuning]{Fine-tuning of a ``registerised'' version of GHC}
1417 %$$ %*                                                                  *
1418 %$$ %************************************************************************
1419 %$$ 
1420 %$$ NOT FINISHED YET.  Let me know if you get this far :-)
1421 %$$ 
1422 %$$ installing
1423 %$$ 
1424 %************************************************************************
1425 %*                                                                      *
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}
1430 %*                                                                      *
1431 %************************************************************************
1432
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.
1436
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.
1440
1441 From here on, I presume you've installed your booted GHC as
1442 \tr{ghc-0.26}.
1443
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:
1447 \begin{verbatim}
1448 cd ghc-0.26/ghc/compiler # note where you are!
1449
1450 rm */*.o    # scrub the old compiler files
1451
1452 gunzip -c ghc-0.26-hi-files-alpha.tar.gz | tar xfv -
1453 \end{verbatim}
1454
1455 Now you can configure as before, but using \tr{--with-hc=ghc-0.26}
1456 (\tr{config.status} records what you did before).
1457
1458 Running \tr{sh < STARTUP} isn't strictly necessary; you only need to
1459 rebuild in \tr{ghc/compiler}:
1460 \begin{verbatim}
1461 cd ghc-0.26/ghc/compiler
1462 make Makefile   # if you didn't STARTUP...
1463
1464 make all EXTRA_HC_OPTS=-fvia-C  # -fvia-C important!
1465 make all EXTRA_HC_OPTS=-fvia-C  # again, until .hi files settle...
1466 \end{verbatim}
1467
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.
1470
1471 %************************************************************************
1472 %*                                                                      *
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}
1477 %*                                                                      *
1478 %************************************************************************
1479
1480 GHC~0.26 doesn't build with HBC.  (It could, but we haven't put in
1481 the effort to maintain it.)
1482
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.
1486
1487 GHC has never been built with compilers other than GHC and HBC.
1488
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.
1493 %$$ 
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.
1499 %$$ 
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!!! ****
1503 %$$ 
1504 %$$ % gunzip -c ghc-0.26-hi-files-hbc.tar.gz | tar xfv -
1505 %$$ \end{verbatim}
1506
1507 %************************************************************************
1508 %*                                                                      *
1509 \section[Pre-supposed]{Installing pre-supposed utilities}
1510 \index{pre-supposed utilities}
1511 \index{utilities, pre-supposed}
1512 %*                                                                      *
1513 %************************************************************************
1514
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.
1518
1519 \begin{description}
1520 \item[Perl:]
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.
1526
1527 (We still assume Perl version 4; experience suggests that Perl~5
1528 is fine, too.)
1529
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.
1534
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
1539 (e.g., perl 4.019).
1540
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.
1545
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...)
1550
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).
1557
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}.
1560
1561 A PVM installation is slightly quirky, but easy to do.  Just follow
1562 the \tr{Readme} instructions.
1563
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:
1568 \begin{verbatim}
1569 find bunch-of-dirs -name '*.o' -print | xargs ar q ...
1570 \end{verbatim}
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
1574 the \tr{.a} file.
1575
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
1579 library.
1580
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.
1586
1587 \item[Makeindex:]
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.
1593
1594 \item[Tgrind:]
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
1600 Unlikely.}
1601
1602 \item[Flex:]
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.
1608
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.
1615 \end{description}
1616
1617 %************************************************************************
1618 %*                                                                      *
1619 \section[build-pitfalls]{Known pitfalls in building Glasgow Haskell}
1620 \index{problems, building}
1621 \index{pitfalls, in building}
1622 \index{building pitfalls}
1623 %*                                                                      *
1624 %************************************************************************
1625
1626 WARNINGS about pitfalls and known ``problems'':
1627
1628 \begin{enumerate}
1629 %------------------------------------------------------------------------
1630 \item
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
1634 space.)
1635
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).
1639
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
1642 in all cases.
1643
1644 %------------------------------------------------------------------------
1645 \item
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.
1649
1650 %------------------------------------------------------------------------
1651 \item
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
1654 these are OK.
1655
1656 %------------------------------------------------------------------------
1657 \item
1658 In 0.26, when compiling via C, you'll sometimes get ``warning:
1659 assignment from incompatible pointer type'' out of GCC.  Harmless.
1660
1661 %------------------------------------------------------------------------
1662 %\item
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.
1666
1667 %------------------------------------------------------------------------
1668 \item
1669 Similarly, \tr{ar}chiving warning messages like the following are not
1670 a problem:
1671 \begin{verbatim}
1672 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
1673 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
1674 ...
1675 \end{verbatim}
1676
1677 %------------------------------------------------------------------------
1678 \item
1679 Also harmless are some specialisation messages that you may see when
1680 compiling GHC; e.g.:
1681 \begin{verbatim}
1682 SPECIALISATION MESSAGES (Desirable):
1683 *** INSTANCES
1684 {-# SPECIALIZE instance Eq [Class] #-}
1685 {-# SPECIALIZE instance Eq (Class, [Class]) #-}
1686 {-# SPECIALIZE instance Outputable [ClassOp] #-}
1687 {-# SPECIALIZE instance Outputable [Id] #-}
1688 \end{verbatim}
1689
1690 %------------------------------------------------------------------------
1691 \item
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}.
1699
1700 Alternatively, just cut to the chase scene:
1701 \begin{verbatim}
1702 % cd ghc/compiler
1703 % make EXTRA_HC_OPTS=-H32m  # or some nice big number
1704 \end{verbatim}
1705
1706 %------------------------------------------------------------------------
1707 \item
1708 Not too long into the build process, you may get a huge complaint
1709 of the form:
1710 \begin{verbatim}
1711 Giant error 'do'ing getopts.pl:  at ./lit2pgm.BOOT line 27.
1712 \end{verbatim}
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.
1716
1717 %------------------------------------------------------------------------
1718 \item
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
1722 been.
1723
1724 As \tr{fixincludes} is now automagically run as part of GCC
1725 installation, this bug also suggests that you have an old GCC.
1726
1727 %------------------------------------------------------------------------
1728 %\item
1729 %Sooner or later in your ``make-worlding'' life you will do and see
1730 %something like:
1731 %\begin{verbatim}
1732 %% make Makefile
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
1739 %*** Error code 1
1740 %make: Fatal error: Command failed for target `Makefile'
1741 %\end{verbatim}
1742 %
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.
1745
1746 %------------------------------------------------------------------------
1747 %\item
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:
1751 %\begin{verbatim}
1752 %#
1753 %# move to the directory just above the one where you want a Makefile...
1754 %cd ..
1755 %#
1756 %# make Makefiles, but lie about the directories below...
1757 %make Makefiles SUBDIRS=newdir
1758 %\end{verbatim}
1759 %
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.
1762
1763 %------------------------------------------------------------------------
1764 %\item
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.
1768
1769 %------------------------------------------------------------------------
1770 \item
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.
1776
1777 %------------------------------------------------------------------------
1778 %\item
1779 \end{enumerate}
1780
1781 %************************************************************************
1782 %*                                                                      *
1783 \section[weird-configs]{Making weird GHC configurations}
1784 \index{GHC unusual configurations}
1785 %*                                                                      *
1786 %************************************************************************
1787
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.
1791
1792 If you want to build some Very Customised GHC libraries, it's
1793 probably best to send email to us, asking how.
1794
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...)
1799 %$$ 
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 */
1808 %$$ \end{verbatim}
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?)
1814 %$$ 
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}
1818 %$$ immediately.
1819 %$$ 
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
1827 %$$ cd ../runtime
1828 %$$ make Makefile; make all
1829 %$$ cd ../lib
1830 %$$ make Makefile; make all
1831 %$$ \end{verbatim}
1832
1833 \upsection
1834
1835 %************************************************************************
1836 %*                                                                      *
1837 \section[building-Haggis]{Building Haggis (Haskell GUI toolkit)}
1838 \index{Haggis, building}
1839 \index{building Haggis}
1840 %*                                                                      *
1841 %************************************************************************
1842
1843 NOT DONE YET.
1844
1845 %************************************************************************
1846 %*                                                                      *
1847 \section[building-Happy]{Building Happy (Haskell parser generator)}
1848 \index{Happy, building}
1849 \index{building Happy}
1850 %*                                                                      *
1851 %************************************************************************
1852
1853 NOT DONE YET.
1854
1855 %************************************************************************
1856 %*                                                                      *
1857 \section[building-NoFib]{Building NoFib (Haskell benchmark suite)}
1858 \index{NoFib suite, building}
1859 \index{building the NoFib suite}
1860 %*                                                                      *
1861 %************************************************************************
1862
1863 NOT DONE YET.
1864
1865 %************************************************************************
1866 %*                                                                      *
1867 \section[Configuring]{Running \tr{configure}}
1868 \index{configure script}
1869 %*                                                                      *
1870 %************************************************************************
1871
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.
1875
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}.
1882
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.
1886
1887 %************************************************************************
1888 %*                                                                      *
1889 \subsection[Configuring-general]{\tr{configure} options for all tools}
1890 \index{Configuring (general)}
1891 %*                                                                      *
1892 %************************************************************************
1893
1894 Many \tr{configure} options apply no matter what tools you are building.
1895
1896 \begin{description}
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.
1901
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}.
1906
1907 With Happy, for example, the main \tr{happy} binary will end up in
1908 \tr{/usr/local/bin/happy}.
1909
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
1916 \tr{--prefix} is,
1917 meaning that things will be installed in \tr{/usr/local/bin}.
1918
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.)
1925
1926 %--------------------------------------------------------------
1927 \item[\tr{--with-hc=}{\em hask}:]
1928 \index{--with-hc configure option}
1929 Use {\em hask} as my ``installed Haskell compiler.''
1930
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!
1934
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
1937 somewhere else).''
1938
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.
1944
1945 On our Alphas, for example, we use \tr{--with-tmpdir=/usr/tmp}.
1946
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}.
1954 \end{description}
1955
1956 %************************************************************************
1957 %*                                                                      *
1958 \subsection[Configuring-GHC]{GHC-specific things in \tr{configure}}
1959 \index{Configuring for GHC}
1960 %*                                                                      *
1961 %************************************************************************
1962
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...)
1966
1967 Some common combinations would be:
1968
1969 \begin{verbatim}
1970 ./configure --prefix=/users/fp/partain --with-hc=c --disable-profiling
1971     # use .hc files; don't bother with profiling
1972
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
1978     # stuff to link to.
1979
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.
1984
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...
1989 \end{verbatim}
1990
1991 Remember, if you build \tr{--with-hc=c} on a Sun4 or Alpha, you
1992 do {\em not} have a native-code generator.
1993
1994 %************************************************************************
1995 %*                                                                      *
1996 \subsection[Configuring-Haggis]{Haggis-specific things in \tr{configure}}
1997 \index{Configuring for Haggis}
1998 %*                                                                      *
1999 %************************************************************************
2000
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}.
2003
2004 MORE TO COME.
2005
2006 %************************************************************************
2007 %*                                                                      *
2008 \subsection[Configuring-Happy]{Happy-specific things in \tr{configure}}
2009 \index{Configuring for Happy}
2010 %*                                                                      *
2011 %************************************************************************
2012
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}.
2015
2016 MORE TO COME.
2017
2018 %************************************************************************
2019 %*                                                                      *
2020 \subsection[Configuring-NoFib]{NoFib-specific things in \tr{configure}}
2021 \index{Configuring for NoFib}
2022 %*                                                                      *
2023 %************************************************************************
2024
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}.
2027
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 :-)
2032
2033 %************************************************************************
2034 %*                                                                      *
2035 \section[STARTUP]{Running \tr{STARTUP}}
2036 \index{STARTUP script}
2037 %*                                                                      *
2038 %************************************************************************
2039
2040 Once you've \tr{configure}d, utter the magic incantation:
2041 \begin{verbatim}
2042 % sh < STARTUP >& startup.log
2043 \end{verbatim}
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.
2047
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.
2052
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).
2056
2057 %************************************************************************
2058 %*                                                                      *
2059 \section[utils_install]{Installing the support software (optional)}
2060 \index{utilities, installing}
2061 %*                                                                      *
2062 %************************************************************************
2063
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...
2067
2068 If you did want to install the ``make world'' system, for example:
2069 \begin{verbatim}
2070 % cd <very-top>/mkworld
2071 % make install
2072 \end{verbatim}
2073
2074 If it isn't installing things where you want it to, you can either
2075 fiddle things on the fly...
2076 \begin{verbatim}
2077 % make install prefix=/home/sweet/home
2078 \end{verbatim}
2079
2080 If you want to install just one utility, for example \tr{lndir}:
2081 \begin{verbatim}
2082 % cd <very-top>/glafp-utils/scripts
2083 % make install_lndir
2084 \end{verbatim}
2085
2086 ``Make world''---It slices, it dices... it's great!
2087
2088 %************************************************************************
2089 %*                                                                      *
2090 \section[arrangement-of-sources]{Arrangement of the sources}
2091 %*                                                                      *
2092 %************************************************************************
2093
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
2096 you should see:
2097
2098 \begin{tabular}{ll}
2099 mkworld/        & ``Make world'' sub-system for configuring the system.\\
2100                 & \\
2101 glafp-utils/    & Utility programs and scripts used in building the distribution;\\
2102                 & often acquired from elsewhere. \\
2103 literate/       & Glasgow literate programming sub-system. \\
2104                 & \\
2105 ghc/driver/     & The driver program for GHC; \\
2106                 & currently a perl script, \tr{ghc}. \\
2107                 & \\
2108 ghc/compiler/   & The Haskell compiler proper, called \tr{hsc}; \\
2109                 & source files are in \tr{compiler/*/[A-Z]*.lhs}. \\
2110                 & \\
2111 ghc/runtime/    & The runtime system, including the garbage-collector(s).\\
2112                 & \\
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'.\\
2118                 & \\
2119 ghc/includes/   & The ``public'' .hi files slurped by the parser, \\
2120                 & and .h files \tr{#include}d in generated .hc files come from.\\
2121                 & \\
2122 ghc/docs/       & documents; see the README file there. \\
2123                 & \\
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 \\
2128 \end{tabular}
2129
2130 \begin{onlystandalone}
2131 \printindex
2132 \end{document}
2133 \end{onlystandalone}