[project @ 2005-05-18 15:34:27 by simonpj]
[ghc.git] / docs / building / building.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <article id="building-guide">
6
7 <articleinfo>
8
9 <title>Building the Glasgow Functional Programming Tools Suite</title>
10 <author><othername>The GHC Team</othername></author>
11 <address><email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</email></address>
12
13 <abstract>
14 <para>The Glasgow fptools suite is a collection of Functional
15 Programming related tools, including the Glasgow Haskell
16 Compiler (GHC). The source code for the whole suite is kept in
17 a single CVS repository and shares a common build and
18 installation system.</para>
19
20 <para>This guide is intended for people who want to build or
21 modify programs from the Glasgow <literal>fptools</literal>
22 suite (as distinct from those who merely want to
23 <emphasis>run</emphasis> them). Installation instructions are
24 now provided in the user guide.</para>
25
26 <para>The bulk of this guide applies to building on Unix
27 systems; see <xref linkend="winbuild"/> for Windows notes.</para>
28 </abstract>
29
30 </articleinfo>
31
32
33 <sect1 id="sec-getting">
34 <title>Getting the sources</title>
35
36 <para>You can get your hands on the <literal>fptools</literal>
37 in two ways:</para>
38
39 <variablelist>
40
41 <varlistentry>
42 <term><indexterm><primary>Source
43 distributions</primary></indexterm>Source distributions</term>
44 <listitem>
45 <para>You have a supported platform, but (a)&nbsp;you like
46 the warm fuzzy feeling of compiling things yourself;
47 (b)&nbsp;you want to build something ``extra&rdquo;&mdash;e.g., a
48 set of libraries with strictness-analysis turned off; or
49 (c)&nbsp;you want to hack on GHC yourself.</para>
50
51 <para>A source distribution contains complete sources for
52 one or more projects in the <literal>fptools</literal>
53 suite. Not only that, but the more awkward
54 machine-independent steps are done for you. For example, if
55 you don't have
56 <command>happy</command><indexterm><primary>happy</primary></indexterm>
57 you'll find it convenient that the source distribution
58 contains the result of running <command>happy</command> on
59 the parser specifications. If you don't want to alter the
60 parser then this saves you having to find and install
61 <command>happy</command>. You will still need a working
62 version of GHC (version 5.x or later) on your machine in
63 order to compile (most of) the sources, however.</para>
64 </listitem>
65 </varlistentry>
66
67 <varlistentry>
68 <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
69 <listitem>
70 <para>We make releases infrequently. If you want more
71 up-to-the minute (but less tested) source code then you need
72 to get access to our CVS repository.</para>
73
74 <para>All the <literal>fptools</literal> source code is held
75 in a CVS repository. CVS is a pretty good source-code
76 control system, and best of all it works over the
77 network.</para>
78
79 <para>The repository holds source code only. It holds no
80 mechanically generated files at all. So if you check out a
81 source tree from CVS you will need to install every utility
82 so that you can build all the derived files from
83 scratch.</para>
84
85 <para>More information about our CVS repository can be found
86 in <xref linkend="sec-cvs"/>.</para>
87 </listitem>
88 </varlistentry>
89 </variablelist>
90
91 <para>If you are going to do any building from sources (either
92 from a source distribution or the CVS repository) then you need to
93 read all of this manual in detail.</para>
94 </sect1>
95
96 <sect1 id="sec-cvs">
97 <title>Using the CVS repository</title>
98
99 <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
100 sources for various software projects. CVS lets several people
101 work on the same software at the same time, allowing changes to be
102 checked in incrementally. </para>
103
104 <para>This section is a set of guidelines for how to use our CVS
105 repository, and will probably evolve in time. The main thing to
106 remember is that most mistakes can be undone, but if there's
107 anything you're not sure about feel free to bug the local CVS
108 meister (namely Jeff Lewis
109 <email>jlewis@galois.com</email>). </para>
110
111 <sect2 id="cvs-access">
112 <title>Getting access to the CVS Repository</title>
113
114 <para>You can access the repository in one of two ways:
115 read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
116 linkend="cvs-read-write"/>).</para>
117
118 <sect3 id="cvs-read-only">
119 <title>Remote Read-only CVS Access</title>
120
121 <para>Read-only access is available to anyone - there's no
122 need to ask us first. With read-only CVS access you can do
123 anything except commit changes to the repository. You can
124 make changes to your local tree, and still use CVS's merge
125 facility to keep your tree up to date, and you can generate
126 patches using 'cvs diff' in order to send to us for
127 inclusion. </para>
128
129 <para>To get read-only access to the repository:</para>
130
131 <orderedlist>
132 <listitem>
133 <para>Make sure that <application>cvs</application> is
134 installed on your machine.</para>
135 </listitem>
136 <listitem>
137 <para>Set your <literal>$CVSROOT</literal> environment variable to
138 <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
139 <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
140 have any trailing spaces on that line, otherwise CVS will respond with
141 a perplexing message like
142 <screen>/cvs : no such repository</screen></para>
143 </listitem>
144 <listitem>
145 <para>Run the command</para>
146 <screen>$ cvs login</screen>
147 <para>The password is simply <literal>cvs</literal>. This
148 sets up a file in your home directory called
149 <literal>.cvspass</literal>, which squirrels away the
150 dummy password, so you only need to do this step once.</para>
151 </listitem>
152
153 <listitem>
154 <para>Now go to <xref linkend="cvs-first"/>.</para>
155 </listitem>
156 </orderedlist>
157 </sect3>
158
159 <sect3 id="cvs-read-write">
160 <title>Remote Read-Write CVS Access</title>
161
162 <para>We generally supply read-write access to folk doing
163 serious development on some part of the source tree, when
164 going through us would be a pain. If you're developing some
165 feature, or think you have the time and inclination to fix
166 bugs in our sources, feel free to ask for read-write
167 access. There is a certain amount of responsibility that goes
168 with commit privileges; we are more likely to grant you access
169 if you've demonstrated your competence by sending us patches
170 via mail in the past.</para>
171
172 <para>To get remote read-write CVS access, you need to do the
173 following steps.</para>
174
175 <orderedlist>
176 <listitem>
177 <para>Make sure that <literal>cvs</literal> and
178 <literal>ssh</literal> are both installed on your
179 machine.</para>
180 </listitem>
181
182 <listitem>
183 <para>Generate a DSA private-key/public-key pair, thus:</para>
184 <screen>$ ssh-keygen -d</screen>
185 <para>(<literal>ssh-keygen</literal> comes with
186 <literal>ssh</literal>.) Running <literal>ssh-keygen
187 -d</literal> creates the private and public keys in
188 <literal>$HOME/.ssh/id_dsa</literal> and
189 <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
190 (assuming you accept the standard defaults).</para>
191
192 <para><literal>ssh-keygen -d</literal> will only work if
193 you have Version 2 <literal>ssh</literal> installed; it
194 will fail harmlessly otherwise. If you only have Version
195 1 you can instead generate an RSA key pair using plain</para>
196 <screen>$ ssh-keygen</screen>
197
198 <para>Doing so creates the private and public RSA keys in
199 <literal>$HOME/.ssh/identity</literal> and
200 <literal>$HOME/.ssh/identity.pub</literal>
201 respectively.</para>
202
203 <para>[Deprecated.] Incidentally, you can force a Version
204 2 <literal>ssh</literal> to use the Version 1 protocol by
205 creating <literal>$HOME/config</literal> with the
206 following in it:</para>
207 <programlisting>BatchMode Yes
208
209 Host cvs.haskell.org
210 Protocol 1</programlisting>
211
212 <para>In both cases, <literal>ssh-keygen</literal> will
213 ask for a <firstterm>passphrase</firstterm>. The
214 passphrase is a password that protects your private key.
215 In response to the 'Enter passphrase' question, you can
216 either:</para>
217 <itemizedlist>
218 <listitem>
219 <para>[Recommended.] Enter a passphrase, which you
220 will quote each time you use CVS.
221 <literal>ssh-agent</literal> makes this entirely
222 un-tiresome.</para>
223 </listitem>
224 <listitem>
225 <para>[Deprecated.] Just hit return (i.e. use an empty
226 passphrase); then you won't need to quote the
227 passphrase when using CVS. The downside is that
228 anyone who can see into your <literal>.ssh</literal>
229 directory, and thereby get your private key, can mess
230 up the repository. So you must keep the
231 <literal>.ssh</literal> directory with draconian
232 no-access permissions.</para>
233 </listitem>
234 </itemizedlist>
235
236
237 <para>
238 <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
239 </para>
240
241
242 </listitem>
243
244 <listitem>
245 <para>Send a message to to the CVS repository
246 administrator (currently Jeff Lewis
247 <email>jeff@galois.com</email>), containing:</para>
248 <itemizedlist>
249 <listitem>
250 <para>Your desired user-name.</para>
251 </listitem>
252 <listitem>
253 <para>Your <literal>.ssh/id_dsa.pub</literal> (or
254 <literal>.ssh/identity.pub</literal>).</para>
255 </listitem>
256 </itemizedlist>
257 <para>He will set up your account.</para>
258 </listitem>
259
260 <listitem>
261 <para>Set the following environment variables:</para>
262 <itemizedlist>
263 <listitem>
264 <para>
265 <constant>$HOME</constant>: points to your home directory. This is where CVS
266 will look for its <filename>.cvsrc</filename> file.
267 </para>
268 </listitem>
269
270 <listitem>
271 <para>
272 <constant>$CVS_RSH</constant> to <filename>ssh</filename>
273 </para>
274 <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
275 <literal>ssh</literal> assumes that your CVS client
276 understands how to execute shell script
277 (&quot;#!&quot;s,really), which is what
278 <literal>ssh</literal> is. This may not be the case on
279 Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
280 <literal>ssh1</literal>.</para>
281 </listitem>
282
283 <listitem>
284 <para><literal>$CVSROOT</literal> to
285 <literal>:ext:</literal><replaceable>your-username</replaceable>
286 <literal>@cvs.haskell.org:/home/cvs/root</literal>
287 where <replaceable>your-username</replaceable> is your user name on
288 <literal>cvs.haskell.org</literal>.
289 </para>
290 <para>The <literal>CVSROOT</literal> environment variable will
291 be recorded in the checked-out tree, so you don't need to set
292 this every time. </para>
293
294 </listitem>
295
296 <listitem>
297 <para>
298 <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
299 if you want to use an Emacs buffer for typing in those long commit messages.
300 </para>
301 </listitem>
302
303 <listitem>
304 <para>
305 <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
306 set this to point to <filename>bash.exe</filename>.
307 </para>
308 </listitem>
309
310 </itemizedlist>
311
312
313 </listitem>
314
315 <listitem>
316 <para>
317 Put the following in <filename>$HOME/.cvsrc</filename>:
318 </para>
319
320 <programlisting>checkout -P
321 release -d
322 update -P
323 diff -u</programlisting>
324
325 <para>
326 These are the default options for the specified CVS commands,
327 and represent better defaults than the usual ones. (Feel
328 free to change them.)
329 </para>
330
331 <para>
332 [Windows users.] Filenames starting with <filename>.</filename> were illegal in
333 the 8.3 DOS filesystem, but that restriction should have
334 been lifted by now (i.e., you're using VFAT or later filesystems.) If
335 you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
336 optional.
337 </para>
338 </listitem>
339
340 </orderedlist>
341
342
343 <para>[Experts.] Once your account is set up, you can get
344 access from other machines without bothering Jeff, thus:</para>
345 <orderedlist>
346 <listitem>
347 <para>Generate a public/private key pair on the new
348 machine.</para>
349 </listitem>
350 <listitem>
351 <para>Use ssh to log in to
352 <literal>cvs.haskell.org</literal>, from your old
353 machine.</para>
354 </listitem>
355 <listitem>
356 <para>Add the public key for the new machine to the file
357 <literal>$HOME/ssh/authorized_keys</literal> on
358 <literal>cvs.haskell.org</literal>.
359 (<literal>authorized_keys2</literal>, I think, for Version
360 2 protocol.)</para>
361 </listitem>
362 <listitem>
363 <para>Make sure that the new version of
364 <literal>authorized_keys</literal> still has 600 file
365 permissions.</para>
366 </listitem>
367 </orderedlist>
368 </sect3>
369 </sect2>
370
371
372
373 <sect2 id="cvs-first">
374 <title>Checking Out a Source Tree</title>
375
376 <itemizedlist>
377 <listitem>
378 <para>Make sure you set your <literal>CVSROOT</literal>
379 environment variable according to either of the remote
380 methods above. The Approved Way to check out a source tree
381 is as follows:</para>
382
383 <screen>$ cvs checkout fpconfig</screen>
384
385 <para>At this point you have a new directory called
386 <literal>fptools</literal> which contains the basic stuff
387 for the fptools suite, including the configuration files and
388 some other junk. </para>
389
390 <para>[Windows users.] The following messages appear to be harmless:
391 <screen>setsockopt IPTOS_LOWDELAY: Invalid argument
392 setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
393 </para>
394
395
396 <para>You can call the fptools directory whatever you like,
397 CVS won't mind: </para>
398
399 <screen>$ mv fptools <replaceable>directory</replaceable></screen>
400
401 <para> NB: after you've read the CVS manual you might be
402 tempted to try</para>
403 <screen>$ cvs checkout -d <replaceable>directory</replaceable> fpconfig</screen>
404
405 <para>instead of checking out <literal>fpconfig</literal>
406 and then renaming it. But this doesn't work, and will
407 result in checking out the entire repository instead of just
408 the <literal>fpconfig</literal> bit.</para>
409 <screen>$ cd <replaceable>directory</replaceable>
410 $ cvs checkout ghc libraries</screen>
411
412 <para>The second command here checks out the relevant
413 modules you want to work on. For a GHC build, for instance,
414 you need at least the <literal>ghc</literal>,
415 and <literal>libraries</literal>
416 modules (for a full list of the projects available, see
417 <xref linkend="projects"/>).</para>
418
419 <para>Remember that if you do not have
420 <literal>happy</literal> and/or <literal>Alex</literal>
421 installed, you need to check them out as well.</para>
422 </listitem>
423 </itemizedlist>
424 </sect2>
425
426 <sect2 id="cvs-committing">
427 <title>Committing Changes</title>
428
429 <para>This is only if you have read-write access to the
430 repository. For anoncvs users, CVS will issue a &quot;read-only
431 repository&quot; error if you try to commit changes.</para>
432
433 <itemizedlist>
434 <listitem>
435 <para>Build the software, if necessary. Unless you're just
436 working on documentation, you'll probably want to build the
437 software in order to test any changes you make.</para>
438 </listitem>
439
440 <listitem>
441 <para>Make changes. Preferably small ones first.</para>
442 </listitem>
443
444 <listitem>
445 <para>Test them. You can see exactly what changes you've
446 made by using the <literal>cvs diff</literal> command:</para>
447 <screen>$ cvs diff</screen>
448 <para>lists all the changes (using the
449 <literal>diff</literal> command) in and below the current
450 directory. In emacs, <literal>C-c C-v =</literal> runs
451 <literal>cvs diff</literal> on the current buffer and shows
452 you the results.</para>
453 </listitem>
454
455 <listitem>
456 <para>If you changed something in the
457 <literal>fptools/libraries</literal> subdirectories, also run
458 <literal>make html</literal> to check if the documentation can
459 be generated successfully, too.</para>
460 </listitem>
461
462 <listitem>
463 <para>Before checking in a change, you need to update your
464 source tree:</para>
465
466 <screen>$ cd fptools
467 $ cvs update</screen>
468 <para>This pulls in any changes that other people have made,
469 and merges them with yours. If there are any conflicts, CVS
470 will tell you, and you'll have to resolve them before you
471 can check your changes in. The documentation describes what
472 to do in the event of a conflict.</para>
473
474 <para>It's not always necessary to do a full cvs update
475 before checking in a change, since CVS will always tell you
476 if you try to check in a file that someone else has changed.
477 However, you should still update at regular intervals to
478 avoid making changes that don't work in conjuction with
479 changes that someone else made. Keeping an eye on what goes
480 by on the mailing list can help here.</para>
481 </listitem>
482
483 <listitem>
484 <para>When you're happy that your change isn't going to
485 break anything, check it in. For a one-file change:</para>
486
487 <screen>$ cvs commit <replaceable>filename</replaceable></screen>
488
489 <para>CVS will then pop up an editor for you to enter a
490 &quot;commit message&quot;, this is just a short description
491 of what your change does, and will be kept in the history of
492 the file.</para>
493
494 <para>If you're using emacs, simply load up the file into a
495 buffer and type <literal>C-x C-q</literal>, and emacs will
496 prompt for a commit message and then check in the file for
497 you.</para>
498
499 <para>For a multiple-file change, things are a bit
500 trickier. There are several ways to do this, but this is the
501 way I find easiest. First type the commit message into a
502 temporary file. Then either</para>
503
504 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable></screen>
505
506 <para>or, if nothing else has changed in this part of the
507 source tree, </para>
508
509 <screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable></screen>
510
511 <para>where <replaceable>directory</replaceable> is a common
512 parent directory for all your changes, and
513 <replaceable>commit-message</replaceable> is the name of the
514 file containing the commit message.</para>
515
516 <para>Shortly afterwards, you'll get some mail from the
517 relevant mailing list saying which files changed, and giving
518 the commit message. For a multiple-file change, you should
519 still get only <emphasis>one</emphasis> message.</para>
520 </listitem>
521 </itemizedlist>
522 </sect2>
523
524 <sect2 id="cvs-update">
525 <title>Updating Your Source Tree</title>
526
527 <para>It can be tempting to cvs update just part of a source
528 tree to bring in some changes that someone else has made, or
529 before committing your own changes. This is NOT RECOMMENDED!
530 Quite often changes in one part of the tree are dependent on
531 changes in another part of the tree (the
532 <literal>mk/*.mk</literal> files are a good example where
533 problems crop up quite often). Having an inconsistent tree is a
534 major cause of headaches. </para>
535
536 <para>So, to avoid a lot of hassle, follow this recipe for
537 updating your tree:</para>
538
539 <screen>$ cd fptools
540 $ cvs update -P 2&gt;&amp;1 | tee log</screen>
541
542 <para>Look at the log file, and fix any conflicts (denoted by a
543 <quote>C</quote> in the first column). New directories may have
544 appeared in the repository; CVS doesn't check these out by
545 default, so to get new directories you have to explicitly do
546 <screen>$ cvs update -d</screen>
547 in each project subdirectory. Don't do this at the top level,
548 because then <emphasis>all</emphasis> the projects will be
549 checked out.</para>
550
551 <para>If you're using multiple build trees, then for every build
552 tree you have pointing at this source tree, you need to update
553 the links in case any new files have appeared: </para>
554
555 <screen>$ cd <replaceable>build-tree</replaceable>
556 $ lndir <replaceable>source-tree</replaceable></screen>
557
558 <para>Some files might have been removed, so you need to remove
559 the links pointing to these non-existent files:</para>
560
561 <screen>$ find . -xtype l -exec rm '{}' \;</screen>
562
563 <para>To be <emphasis>really</emphasis> safe, you should do
564 </para>
565
566 <screen>$ gmake all</screen>
567
568 <para>from the top-level, to update the dependencies and build
569 any changed files. </para>
570 </sect2>
571
572 <sect2 id="cvs-tags">
573 <title>GHC Tag Policy</title>
574
575 <para>If you want to check out a particular version of GHC,
576 you'll need to know how we tag versions in the repository. The
577 policy (as of 4.04) is:</para>
578
579 <itemizedlist>
580 <listitem>
581 <para>The tree is branched before every major release. The
582 branch tag is <literal>ghc-x-xx-branch</literal>, where
583 <literal>x-xx</literal> is the version number of the release
584 with the <literal>'.'</literal> replaced by a
585 <literal>'-'</literal>. For example, the 4.04 release lives
586 on <literal>ghc-4-04-branch</literal>.</para>
587 </listitem>
588
589 <listitem>
590 <para>The release itself is tagged with
591 <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
592 called <literal>ghc-4-06</literal>.</para>
593 </listitem>
594
595 <listitem>
596 <para>We didn't always follow these guidelines, so to see
597 what tags there are for previous versions, do <literal>cvs
598 log</literal> on a file that's been around for a while (like
599 <literal>fptools/ghc/README</literal>).</para>
600 </listitem>
601 </itemizedlist>
602
603 <para>So, to check out a fresh GHC 4.06 tree you would
604 do:</para>
605
606 <screen>$ cvs co -r ghc-4-06 fpconfig
607 $ cd fptools
608 $ cvs co -r ghc-4-06 ghc libraries</screen>
609 </sect2>
610
611 <sect2 id="cvs-hints">
612 <title>General Hints</title>
613
614 <itemizedlist>
615 <listitem>
616 <para>As a general rule: commit changes in small units,
617 preferably addressing one issue or implementing a single
618 feature. Provide a descriptive log message so that the
619 repository records exactly which changes were required to
620 implement a given feature/fix a bug. I've found this
621 <emphasis>very</emphasis> useful in the past for finding out
622 when a particular bug was introduced: you can just wind back
623 the CVS tree until the bug disappears.</para>
624 </listitem>
625
626 <listitem>
627 <para>Keep the sources at least *buildable* at any given
628 time. No doubt bugs will creep in, but it's quite easy to
629 ensure that any change made at least leaves the tree in a
630 buildable state. We do nightly builds of GHC to keep an eye
631 on what things work/don't work each day and how we're doing
632 in relation to previous verions. This idea is truely wrecked
633 if the compiler won't build in the first place!</para>
634 </listitem>
635
636 <listitem>
637 <para>To check out extra bits into an already-checked-out
638 tree, use the following procedure. Suppose you have a
639 checked-out fptools tree containing just ghc, and you want
640 to add nofib to it:</para>
641
642 <screen>$ cd fptools
643 $ cvs checkout nofib</screen>
644
645 <para>or: </para>
646
647 <screen>$ cd fptools
648 $ cvs update -d nofib</screen>
649
650 <para>(the -d flag tells update to create a new
651 directory). If you just want part of the nofib suite, you
652 can do </para>
653
654 <screen>$ cd fptools
655 $ cvs checkout nofib/spectral</screen>
656
657 <para>This works because <literal>nofib</literal> is a
658 module in its own right, and spectral is a subdirectory of
659 the nofib module. The path argument to checkout must always
660 start with a module name. There's no equivalent form of this
661 command using <literal>update</literal>.</para>
662 </listitem>
663 </itemizedlist>
664 </sect2>
665 </sect1>
666
667 <sect1 id="projects">
668 <title>What projects are there?</title>
669
670 <para>The <literal>fptools</literal> suite consists of several
671 <firstterm>projects</firstterm>, most of which can be downloaded,
672 built and installed individually. Each project corresponds to a
673 subdirectory in the source tree, and if checking out from CVS then
674 each project can be checked out individually by sitting in the top
675 level of your source tree and typing <command>cvs checkout
676 <replaceable>project</replaceable></command>.</para>
677
678 <para>Here is a list of the projects currently available:</para>
679
680 <variablelist>
681 <varlistentry>
682 <term>
683 <literal>alex</literal>
684 <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
685 </term>
686 <listitem>
687 <para>The <ulink
688 url="http://www.haskell.org/alex/">Alex</ulink> lexical
689 analyser generator for Haskell.</para>
690 </listitem>
691 </varlistentry>
692
693 <varlistentry>
694 <term>
695 <literal>ghc</literal>
696 <indexterm><primary><literal>ghc</literal></primary>
697 <secondary>project</secondary></indexterm>
698 </term>
699 <listitem>
700 <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
701 Haskell Compiler</ulink> (minus libraries). Absolutely
702 required for building GHC.</para>
703 </listitem>
704 </varlistentry>
705
706 <varlistentry>
707 <term>
708 <literal>glafp-utils</literal>
709 <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
710 </term>
711 <listitem>
712 <para>Utility programs, some of which are used by the
713 build/installation system. Required for pretty much
714 everything.</para>
715 </listitem>
716 </varlistentry>
717
718 <varlistentry>
719 <term>
720 <literal>greencard</literal>
721 <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
722 </term>
723 <listitem>
724 <para>The <ulink
725 url="http://www.haskell.org/greencard/">GreenCard</ulink>
726 system for generating Haskell foreign function
727 interfaces.</para>
728 </listitem>
729 </varlistentry>
730
731 <varlistentry>
732 <term>
733 <literal>haggis</literal>
734 <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
735 </term>
736 <listitem>
737 <para>The <ulink
738 url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
739 Haskell GUI framework.</para>
740 </listitem>
741 </varlistentry>
742
743 <varlistentry>
744 <term>
745 <literal>haddock</literal>
746 <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
747 </term>
748 <listitem>
749 <para>The <ulink
750 url="http://www.haskell.org/haddock/">Haddock</ulink>
751 documentation tool.</para>
752 </listitem>
753 </varlistentry>
754
755 <varlistentry>
756 <term>
757 <literal>happy</literal>
758 <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
759 </term>
760 <listitem>
761 <para>The <ulink
762 url="http://www.haskell.org/happy/">Happy</ulink> Parser
763 generator.</para>
764 </listitem>
765 </varlistentry>
766
767 <varlistentry>
768 <term>
769 <literal>hdirect</literal>
770 <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
771 </term>
772 <listitem>
773 <para>The <ulink
774 url="http://www.haskell.org/hdirect/">H/Direct</ulink>
775 Haskell interoperability tool.</para>
776 </listitem>
777 </varlistentry>
778
779 <varlistentry>
780 <term>
781 <literal>hood</literal>
782 <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
783 </term>
784 <listitem>
785 <para>The <ulink url="http://www.haskell.org/hood/">Haskell
786 Object Observation Debugger</ulink>.</para>
787 </listitem>
788 </varlistentry>
789
790 <varlistentry>
791 <term>
792 <literal>hslibs</literal>
793 <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
794 </term>
795 <listitem>
796 <para>Old, now deprecated, libraries. Everything in here is in <literal>libraries</literal>.</para>
797 </listitem>
798 </varlistentry>
799
800 <varlistentry>
801 <term>
802 <literal>libraries</literal>
803 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
804 </term>
805 <listitem>
806 <para>Hierarchical Haskell library suite
807 (<emphasis>required</emphasis> for building GHC).</para>
808 </listitem>
809 </varlistentry>
810
811 <varlistentry>
812 <term>
813 <literal>mhms</literal>
814 <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
815 </term>
816 <listitem>
817 <para>The Modular Haskell Metric System.</para>
818 </listitem>
819 </varlistentry>
820
821 <varlistentry>
822 <term>
823 <literal>nofib</literal>
824 <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
825 </term>
826 <listitem>
827 <para>The NoFib suite: A collection of Haskell programs used
828 primarily for benchmarking.</para>
829 </listitem>
830 </varlistentry>
831
832 <varlistentry>
833 <term>
834 <literal>testsuite</literal>
835 <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
836 </term>
837 <listitem>
838 <para>A testing framework, including GHC's regression test
839 suite.</para>
840 </listitem>
841 </varlistentry>
842 </variablelist>
843
844 <para>So, to build GHC you need at least the
845 <literal>ghc</literal> and <literal>libraries</literal>
846 projects (a GHC source distribution will
847 already include the bits you need).</para>
848 </sect1>
849
850 <sect1 id="sec-build-checks">
851 <title>Things to check before you start</title>
852
853 <para>Here's a list of things to check before you get
854 started.</para>
855
856 <orderedlist>
857
858 <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
859 space needed: from about 100Mb for a basic GHC
860 build, up to probably 500Mb for a GHC build with everything
861 included (libraries built several different ways,
862 etc.).</para>
863 </listitem>
864
865 <listitem>
866 <para>Use an appropriate machine / operating system. <xref
867 linkend="sec-port-info"/> lists the supported platforms; if
868 yours isn't amongst these then you can try porting GHC (see
869 <xref linkend="sec-porting-ghc"/>).</para>
870 </listitem>
871
872 <listitem>
873 <para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
874 installed. <xref linkend="sec-pre-supposed"/>
875 elaborates.</para>
876 </listitem>
877
878 <listitem>
879 <para>If you have any problem when building or installing the
880 Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<xref
881 linkend="sec-build-pitfalls"/>). Also check the FAQ for the
882 version you're building, which is part of the User's Guide and
883 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
884 site</ulink>.</para>
885
886 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
887
888 <para>If you feel there is still some shortcoming in our
889 procedure or instructions, please report it.</para>
890
891 <para>For GHC, please see the <ulink
892 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
893 section of the GHC Users' Guide</ulink>, to maximise the
894 usefulness of your report.</para>
895
896 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
897 <para>If in doubt, please send a message to
898 <email>glasgow-haskell-bugs@haskell.org</email>.
899 <indexterm><primary>bugs</primary><secondary>mailing
900 list</secondary></indexterm></para>
901 </listitem>
902 </orderedlist>
903 </sect1>
904
905 <sect1 id="sec-port-info">
906 <title>What machines the Glasgow tools run on</title>
907
908 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
909 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
910 <indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
911
912 <para>The main question is whether or not the Haskell compiler
913 (GHC) runs on your platform.</para>
914
915 <para>A &ldquo;platform&rdquo; is a
916 architecture/manufacturer/operating-system combination, such as
917 <literal>sparc-sun-solaris2</literal>. Other common ones are
918 <literal>alpha-dec-osf2</literal>,
919 <literal>hppa1.1-hp-hpux9</literal>,
920 <literal>i386-unknown-linux</literal>,
921 <literal>i386-unknown-solaris2</literal>,
922 <literal>i386-unknown-freebsd</literal>,
923 <literal>i386-unknown-cygwin32</literal>,
924 <literal>m68k-sun-sunos4</literal>,
925 <literal>mips-sgi-irix5</literal>,
926 <literal>sparc-sun-sunos4</literal>,
927 <literal>sparc-sun-solaris2</literal>,
928 <literal>powerpc-ibm-aix</literal>.</para>
929
930 <para>Some libraries may only work on a limited number of
931 platforms; for example, a sockets library is of no use unless the
932 operating system supports the underlying BSDisms.</para>
933
934 <sect2>
935 <title>What platforms the Haskell compiler (GHC) runs on</title>
936
937 <indexterm><primary>fully-supported platforms</primary></indexterm>
938 <indexterm><primary>native-code generator</primary></indexterm>
939 <indexterm><primary>registerised ports</primary></indexterm>
940 <indexterm><primary>unregisterised ports</primary></indexterm>
941
942 <para>The GHC hierarchy of Porting Goodness: (a)&nbsp;Best is a
943 native-code generator; (b)&nbsp;next best is a
944 &ldquo;registerised&rdquo; port; (c)&nbsp;the bare minimum is an
945 &ldquo;unregisterised&rdquo; port.
946 (&ldquo;Unregisterised&rdquo; is so terrible that we won't say
947 more about it).</para>
948
949 <para>We use Sparcs running Solaris 2.7 and x86 boxes running
950 FreeBSD and Linux, so those are the best supported platforms,
951 unsurprisingly.</para>
952
953 <para>Here's everything that's known about GHC ports. We
954 identify platforms by their &ldquo;canonical&rdquo;
955 CPU/Manufacturer/OS triple.</para>
956
957 <variablelist>
958 <varlistentry>
959 <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
960 <indexterm><primary>alpha-dec-osf</primary></indexterm>
961 <indexterm><primary>alpha-dec-linux</primary></indexterm>
962 <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
963 <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
964 <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
965 </term>
966 <listitem>
967 <para>The OSF port is currently working (as of GHC version
968 5.02.1) and well supported. The native code generator is
969 currently non-working. Other operating systems will
970 require some minor porting.</para>
971 </listitem>
972 </varlistentry>
973
974 <varlistentry>
975 <term>sparc-sun-sunos4
976 <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
977 </term>
978 <listitem>
979 <para>Probably works with minor tweaks, hasn't been tested
980 for a while.</para>
981 </listitem>
982 </varlistentry>
983
984 <varlistentry>
985 <term>sparc-sun-solaris2
986 <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
987 </term>
988 <listitem>
989 <para>Fully supported (at least for Solaris 2.7 and 2.6),
990 including native-code generator.</para>
991 </listitem>
992 </varlistentry>
993
994 <varlistentry>
995 <term>sparc-unknown-openbsd
996 <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
997 </term>
998 <listitem>
999 <para>Supported, including native-code generator. The
1000 same should also be true of NetBSD</para>
1001 </listitem>
1002 </varlistentry>
1003
1004 <varlistentry>
1005 <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
1006 <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
1007 </term>
1008 <listitem>
1009 <para>A registerised port is available for version 4.08,
1010 but GHC hasn't been built on that platform since (as far
1011 as we know). No native-code generator.</para>
1012 </listitem>
1013 </varlistentry>
1014
1015 <varlistentry>
1016 <term>i386-unknown-linux (PCs running Linux, ELF binary format)
1017 <indexterm><primary>i386-*-linux</primary></indexterm>
1018 </term>
1019 <listitem>
1020 <para>GHC works registerised and has a native code
1021 generator. You <emphasis>must</emphasis> have GCC 2.7.x
1022 or later. NOTE about <literal>glibc</literal> versions:
1023 GHC binaries built on a system running <literal>glibc
1024 2.0</literal> won't work on a system running
1025 <literal>glibc 2.1</literal>, and vice versa. In general,
1026 don't expect compatibility between
1027 <literal>glibc</literal> versions, even if the shared
1028 library version hasn't changed.</para>
1029 </listitem>
1030 </varlistentry>
1031
1032 <varlistentry>
1033 <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
1034 <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
1035 </term>
1036 <listitem>
1037 <para>GHC works registerised. Pre-built packages are
1038 available in the native package format, so if you just
1039 need binaries you're better off just installing the
1040 package (it might even be on your installation
1041 CD!).</para>
1042 </listitem>
1043 </varlistentry>
1044
1045 <varlistentry>
1046 <term>i386-unknown-openbsd (PCs running OpenBSD)
1047 <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
1048 </term>
1049 <listitem>
1050 <para>Supported, with native code generator. Packages are
1051 available through the ports system in the native package
1052 format.</para>
1053 </listitem>
1054 </varlistentry>
1055
1056 <varlistentry>
1057 <term>i386-unknown-netbsd (PCs running NetBSD)
1058 <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1059 </term>
1060 <listitem>
1061 <para>Will require some minor porting effort, but should
1062 work registerised.</para>
1063 </listitem>
1064 </varlistentry>
1065
1066 <varlistentry>
1067 <term>i386-unknown-mingw32 (PCs running Windows)
1068 <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
1069 </term>
1070 <listitem>
1071 <para>Fully supported under Win9x, WinNT, Win2k, and
1072 WinXP. Includes a native code generator. Building from
1073 source requires a recent <ulink
1074 url="http://www.cygwin.com/">Cygwin</ulink> distribution
1075 to be installed.</para>
1076 </listitem>
1077 </varlistentry>
1078
1079 <varlistentry>
1080 <term>ia64-unknown-linux
1081 <indexterm><primary>ia64-unknown-linux</primary></indexterm>
1082 </term>
1083 <listitem>
1084 <para>Supported, except there is no native code
1085 generator.</para>
1086 </listitem>
1087 </varlistentry>
1088
1089 <varlistentry>
1090 <term>x86_64-unknown-linux
1091 <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
1092 </term>
1093 <listitem>
1094 <para>GHC currently works unregisterised. A registerised
1095 port is in progress.</para>
1096 </listitem>
1097 </varlistentry>
1098
1099 <varlistentry>
1100 <term>amd64-unknown-openbsd
1101 <indexterm><primary>amd64-unknown-linux</primary></indexterm>
1102 </term>
1103 <listitem>
1104 <para>(This is the same as x86_64-unknown-openbsd). GHC
1105 currently works unregisterised. A registerised port is in
1106 progress.</para>
1107 </listitem>
1108 </varlistentry>
1109
1110 <varlistentry>
1111 <term>mips-sgi-irix5
1112 <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
1113 </term>
1114 <listitem>
1115 <para>Port has worked in the past, but hasn't been tested
1116 for some time (and will certainly have rotted in various
1117 ways). As usual, we don't have access to machines and
1118 there hasn't been an overwhelming demand for this port,
1119 but feel free to get in touch.</para>
1120 </listitem>
1121 </varlistentry>
1122
1123 <varlistentry>
1124 <term>mips64-sgi-irix6
1125 <indexterm><primary>mips-sgi-irix6</primary></indexterm>
1126 </term>
1127 <listitem>
1128 <para>GHC currently works unregisterised.</para>
1129 </listitem>
1130 </varlistentry>
1131
1132 <varlistentry>
1133 <term>powerpc-ibm-aix
1134 <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1135 </term>
1136 <listitem>
1137 <para>Port currently doesn't work, needs some minimal
1138 porting effort. As usual, we don't have access to
1139 machines and there hasn't been an overwhelming demand for
1140 this port, but feel free to get in touch.</para>
1141 </listitem>
1142 </varlistentry>
1143
1144 <varlistentry>
1145 <term>powerpc-apple-darwin
1146 <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
1147 </term>
1148 <listitem>
1149 <para>Supported registerised. Native code generator is
1150 almost working.</para>
1151 </listitem>
1152 </varlistentry>
1153
1154 <varlistentry>
1155 <term>powerpc-apple-linux
1156 <indexterm><primary>powerpc-apple-linux</primary></indexterm>
1157 </term>
1158 <listitem>
1159 <para>Not supported (yet).</para>
1160 </listitem>
1161 </varlistentry>
1162 </variablelist>
1163
1164 <para>Various other systems have had GHC ported to them in the
1165 distant past, including various Motorola 68k boxes. The 68k
1166 support still remains, but porting to one of these systems will
1167 certainly be a non-trivial task.</para>
1168 </sect2>
1169
1170 <sect2>
1171 <title>What machines the other tools run on</title>
1172
1173 <para>Unless you hear otherwise, the other tools work if GHC
1174 works.</para>
1175 </sect2>
1176 </sect1>
1177
1178
1179 <sect1 id="sec-pre-supposed">
1180 <title>Installing pre-supposed utilities</title>
1181
1182 <indexterm><primary>pre-supposed utilities</primary></indexterm>
1183 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
1184
1185 <para>Here are the gory details about some utility programs you
1186 may need; <command>perl</command>, <command>gcc</command> and
1187 <command>happy</command> are the only important
1188 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
1189 important if you're going for Parallel Haskell.) The
1190 <command>configure</command><indexterm><primary>configure</primary></indexterm>
1191 script will tell you if you are missing something.</para>
1192
1193 <variablelist>
1194
1195 <varlistentry>
1196 <term>GHC
1197 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
1198 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
1199 </term>
1200 <listitem>
1201 <para>GHC is required to build many of the tools, including
1202 GHC itself. If you need to port GHC to your platform
1203 because there isn't a binary distribution of GHC available,
1204 then see <xref linkend="sec-porting-ghc"/>.</para>
1205
1206 <para>Which version of GHC you need will depend on the
1207 packages you intend to build. GHC itself will normally
1208 build using one of several older versions of itself - check
1209 the announcement or release notes for details.</para>
1210 </listitem>
1211 </varlistentry>
1212
1213 <varlistentry>
1214 <term>Perl
1215 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
1216 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
1217 </term>
1218 <listitem>
1219 <para><emphasis>You have to have Perl to proceed!</emphasis>
1220 Perl version 5 at least is required. GHC has been known to
1221 tickle bugs in Perl, so if you find that Perl crashes when
1222 running GHC try updating (or downgrading) your Perl
1223 installation. Versions of Perl that we use and are known to
1224 be fairly stable are 5.005 and 5.6.1.</para>
1225
1226 <para>For Win32 platforms, you should use the binary
1227 supplied in the InstallShield (copy it to
1228 <filename>/bin</filename>). The Cygwin-supplied Perl seems
1229 not to work.</para>
1230
1231 <para>Perl should be put somewhere so that it can be invoked
1232 by the <literal>&num;!</literal> script-invoking
1233 mechanism. The full pathname may need to be less than 32
1234 characters long on some systems.</para>
1235 </listitem>
1236 </varlistentry>
1237
1238 <varlistentry>
1239 <term>GNU C (<command>gcc</command>)
1240 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
1241 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
1242 </term>
1243 <listitem>
1244 <para>We recommend using GCC version 2.95.2 on all
1245 platforms. Failing that, version 2.7.2 is stable on most
1246 platforms. Earlier versions of GCC can be assumed not to
1247 work, and versions in between 2.7.2 and 2.95.2 (including
1248 <command>egcs</command>) have varying degrees of stability
1249 depending on the platform.</para>
1250
1251 <para>GCC 3.2 is currently known to have problems building
1252 GHC on Sparc, but is stable on x86.</para>
1253
1254 <para>If your GCC dies with &ldquo;internal error&rdquo; on
1255 some GHC source file, please let us know, so we can report
1256 it and get things improved. (Exception: on x86
1257 boxes&mdash;you may need to fiddle with GHC's
1258 <option>-monly-N-regs</option> option; see the User's
1259 Guide)</para>
1260 </listitem>
1261 </varlistentry>
1262
1263 <varlistentry>
1264 <term>GNU Make
1265 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
1266 </term>
1267 <listitem>
1268 <para>The fptools build system makes heavy use of features
1269 specific to GNU <command>make</command>, so you must have
1270 this installed in order to build any of the fptools
1271 suite.</para>
1272 </listitem>
1273 </varlistentry>
1274
1275 <varlistentry>
1276 <term>Happy
1277 <indexterm><primary>Happy</primary></indexterm>
1278 </term>
1279 <listitem>
1280 <para>Happy is a parser generator tool for Haskell, and is
1281 used to generate GHC's parsers. Happy is written in
1282 Haskell, and is a project in the CVS repository
1283 (<literal>fptools/happy</literal>). It can be built from
1284 source, but bear in mind that you'll need GHC installed in
1285 order to build it. To avoid the chicken/egg problem,
1286 install a binary distribution of either Happy or GHC to get
1287 started. Happy distributions are available from <ulink
1288 url="http://www.haskell.org/happy/">Happy's Web
1289 Page</ulink>.</para>
1290 </listitem>
1291 </varlistentry>
1292
1293 <varlistentry>
1294 <term>Alex
1295 <indexterm><primary>Alex</primary></indexterm>
1296 </term>
1297 <listitem>
1298 <para>Alex is a lexical-analyser generator for Haskell,
1299 which GHC uses to generate its lexer. Like Happy, Alex is
1300 written in Haskell and is a project in the CVS repository.
1301 Alex distributions are available from <ulink
1302 url="http://www.haskell.org/alex/">Alex's Web
1303 Page</ulink>.</para>
1304 </listitem>
1305 </varlistentry>
1306
1307 <varlistentry>
1308 <term>autoconf
1309 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
1310 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
1311 </term>
1312 <listitem>
1313 <para>GNU autoconf is needed if you intend to build from the
1314 CVS sources, it is <emphasis>not</emphasis> needed if you
1315 just intend to build a standard source distribution.</para>
1316
1317 <para>Version 2.52 or later of the autoconf package is required.
1318 NB. version 2.13 will no longer work, as of GHC version
1319 6.1.</para>
1320
1321 <para><command>autoreconf</command> (from the autoconf package)
1322 recursively builds <command>configure</command> scripts from
1323 the corresponding <filename>configure.ac</filename> and
1324 <filename>aclocal.m4</filename> files. If you modify one of
1325 the latter files, you'll need <command>autoreconf</command> to
1326 rebuild the corresponding <filename>configure</filename>.</para>
1327 </listitem>
1328 </varlistentry>
1329
1330 <varlistentry>
1331 <term><command>sed</command>
1332 <indexterm><primary>pre-supposed: sed</primary></indexterm>
1333 <indexterm><primary>sed, pre-supposed</primary></indexterm>
1334 </term>
1335 <listitem>
1336 <para>You need a working <command>sed</command> if you are
1337 going to build from sources. The build-configuration stuff
1338 needs it. GNU sed version 2.0.4 is no good! It has a bug
1339 in it that is tickled by the build-configuration. 2.0.5 is
1340 OK. Others are probably OK too (assuming we don't create too
1341 elaborate configure scripts.)</para>
1342 </listitem>
1343 </varlistentry>
1344 </variablelist>
1345
1346 <para>One <literal>fptools</literal> project is worth a quick note
1347 at this point, because it is useful for all the others:
1348 <literal>glafp-utils</literal> contains several utilities which
1349 aren't particularly Glasgow-ish, but Occasionally Indispensable.
1350 Like <command>lndir</command> for creating symbolic link
1351 trees.</para>
1352
1353 <sect2 id="pre-supposed-gph-tools">
1354 <title>Tools for building parallel GHC (GPH)</title>
1355
1356 <variablelist>
1357 <varlistentry>
1358 <term>PVM version 3:
1359 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1360 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
1361 </term>
1362 <listitem>
1363 <para>PVM is the Parallel Virtual Machine on which
1364 Parallel Haskell programs run. (You only need this if you
1365 plan to run Parallel Haskell. Concurrent Haskell, which
1366 runs concurrent threads on a uniprocessor doesn't need
1367 it.) Underneath PVM, you can have (for example) a network
1368 of workstations (slow) or a multiprocessor box
1369 (faster).</para>
1370
1371 <para>The current version of PVM is 3.3.11; we use 3.3.7.
1372 It is readily available on the net; I think I got it from
1373 <literal>research.att.com</literal>, in
1374 <filename>netlib</filename>.</para>
1375
1376 <para>A PVM installation is slightly quirky, but easy to
1377 do. Just follow the <filename>Readme</filename>
1378 instructions.</para>
1379 </listitem>
1380 </varlistentry>
1381
1382 <varlistentry>
1383 <term><command>bash</command>:
1384 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
1385 </term>
1386 <listitem>
1387 <para>Sadly, the <command>gr2ps</command> script, used to
1388 convert &ldquo;parallelism profiles&rdquo; to PostScript,
1389 is written in Bash (GNU's Bourne Again shell). This bug
1390 will be fixed (someday).</para>
1391 </listitem>
1392 </varlistentry>
1393 </variablelist>
1394 </sect2>
1395
1396 <sect2 id="pre-supposed-other-tools">
1397 <title>Other useful tools</title>
1398
1399 <variablelist>
1400 <varlistentry>
1401 <term>Flex
1402 <indexterm><primary>pre-supposed: flex</primary></indexterm>
1403 <indexterm><primary>flex, pre-supposed</primary></indexterm>
1404 </term>
1405 <listitem>
1406 <para>This is a quite-a-bit-better-than-Lex lexer. Used
1407 to build a couple of utilities in
1408 <literal>glafp-utils</literal>. Depending on your
1409 operating system, the supplied <command>lex</command> may
1410 or may not work; you should get the GNU version.</para>
1411 </listitem>
1412 </varlistentry>
1413 </variablelist>
1414
1415 <para>More tools are required if you want to format the documentation
1416 that comes with GHC and other fptools projects. See <xref
1417 linkend="building-docs"/>.</para>
1418 </sect2>
1419 </sect1>
1420
1421 <sect1 id="sec-building-from-source">
1422 <title>Building from source</title>
1423
1424 <indexterm><primary>Building from source</primary></indexterm>
1425 <indexterm><primary>Source, building from</primary></indexterm>
1426
1427 <para>You've been rash enough to want to build some of the Glasgow
1428 Functional Programming tools (GHC, Happy, nofib, etc.) from
1429 source. You've slurped the source, from the CVS repository or
1430 from a source distribution, and now you're sitting looking at a
1431 huge mound of bits, wondering what to do next.</para>
1432
1433 <para>Gingerly, you type <command>make</command>. Wrong
1434 already!</para>
1435
1436 <para>This rest of this guide is intended for duffers like me, who
1437 aren't really interested in Makefiles and systems configurations,
1438 but who need a mental model of the interlocking pieces so that
1439 they can make them work, extend them consistently when adding new
1440 software, and lay hands on them gently when they don't
1441 work.</para>
1442
1443 <sect2 id="quick-start">
1444 <title>Quick Start</title>
1445
1446 <para>If you are starting from a source distribution, and just
1447 want a completely standard build, then the following procedure should
1448 work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
1449
1450 <screen>$ autoreconf
1451 $ ./configure
1452 $ make
1453 $ make install</screen>
1454
1455 <para>For GHC, this will do a 2-stage bootstrap build of the
1456 compiler, with profiling libraries, and install the
1457 results.</para>
1458
1459 <para>If you want to do anything at all non-standard, or you
1460 want to do some development, read on...</para>
1461 </sect2>
1462
1463 <sect2 id="sec-source-tree">
1464 <title>Your source tree</title>
1465
1466 <para>The source code is held in your <emphasis>source
1467 tree</emphasis>. The root directory of your source tree
1468 <emphasis>must</emphasis> contain the following directories and
1469 files:</para>
1470
1471 <itemizedlist>
1472 <listitem>
1473 <para><filename>Makefile</filename>: the root
1474 Makefile.</para>
1475 </listitem>
1476
1477 <listitem>
1478 <para><filename>mk/</filename>: the directory that contains
1479 the main Makefile code, shared by all the
1480 <literal>fptools</literal> software.</para>
1481 </listitem>
1482
1483 <listitem>
1484 <para><filename>configure.ac</filename>,
1485 <filename>config.sub</filename>,
1486 <filename>config.guess</filename>: these files support the
1487 configuration process.</para>
1488 </listitem>
1489
1490 <listitem>
1491 <para><filename>install-sh</filename>.</para>
1492 </listitem>
1493 </itemizedlist>
1494
1495 <para>All the other directories are individual
1496 <emphasis>projects</emphasis> of the <literal>fptools</literal>
1497 system&mdash;for example, the Glasgow Haskell Compiler
1498 (<literal>ghc</literal>), the Happy parser generator
1499 (<literal>happy</literal>), the <literal>nofib</literal>
1500 benchmark suite, and so on. You can have zero or more of these.
1501 Needless to say, some of them are needed to build others.</para>
1502
1503 <para>The important thing to remember is that even if you want
1504 only one project (<literal>happy</literal>, say), you must have
1505 a source tree whose root directory contains
1506 <filename>Makefile</filename>, <filename>mk/</filename>,
1507 <filename>configure.ac</filename>, and the project(s) you want
1508 (<filename>happy/</filename> in this case). You cannot get by
1509 with just the <filename>happy/</filename> directory.</para>
1510 </sect2>
1511
1512 <sect2>
1513 <title>Build trees</title>
1514 <indexterm><primary>build trees</primary></indexterm>
1515 <indexterm><primary>link trees, for building</primary></indexterm>
1516
1517 <para>If you just want to build the software once on a single
1518 platform, then your source tree can also be your build tree, and
1519 you can skip the rest of this section.</para>
1520
1521 <para>We often want to build multiple versions of our software
1522 for different architectures, or with different options
1523 (e.g. profiling). It's very desirable to share a single copy of
1524 the source code among all these builds.</para>
1525
1526 <para>So for every source tree we have zero or more
1527 <emphasis>build trees</emphasis>. Each build tree is initially
1528 an exact copy of the source tree, except that each file is a
1529 symbolic link to the source file, rather than being a copy of
1530 the source file. There are &ldquo;standard&rdquo; Unix
1531 utilities that make such copies, so standard that they go by
1532 different names:
1533 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
1534 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
1535 are two (If you don't have either, the source distribution
1536 includes sources for the X11
1537 <command>lndir</command>&mdash;check out
1538 <filename>fptools/glafp-utils/lndir</filename>). See <xref
1539 linkend="sec-storysofar"/> for a typical invocation.</para>
1540
1541 <para>The build tree does not need to be anywhere near the
1542 source tree in the file system. Indeed, one advantage of
1543 separating the build tree from the source is that the build tree
1544 can be placed in a non-backed-up partition, saving your systems
1545 support people from backing up untold megabytes of
1546 easily-regenerated, and rapidly-changing, gubbins. The golden
1547 rule is that (with a single exception&mdash;<xref
1548 linkend="sec-build-config"/>) <emphasis>absolutely everything in
1549 the build tree is either a symbolic link to the source tree, or
1550 else is mechanically generated</emphasis>. It should be
1551 perfectly OK for your build tree to vanish overnight; an hour or
1552 two compiling and you're on the road again.</para>
1553
1554 <para>You need to be a bit careful, though, that any new files
1555 you create (if you do any development work) are in the source
1556 tree, not a build tree!</para>
1557
1558 <para>Remember, that the source files in the build tree are
1559 <emphasis>symbolic links</emphasis> to the files in the source
1560 tree. (The build tree soon accumulates lots of built files like
1561 <filename>Foo.o</filename>, as well.) You can
1562 <emphasis>delete</emphasis> a source file from the build tree
1563 without affecting the source tree (though it's an odd thing to
1564 do). On the other hand, if you <emphasis>edit</emphasis> a
1565 source file from the build tree, you'll edit the source-tree
1566 file directly. (You can set up Emacs so that if you edit a
1567 source file from the build tree, Emacs will silently create an
1568 edited copy of the source file in the build tree, leaving the
1569 source file unchanged; but the danger is that you think you've
1570 edited the source file whereas actually all you've done is edit
1571 the build-tree copy. More commonly you do want to edit the
1572 source file.)</para>
1573
1574 <para>Like the source tree, the top level of your build tree
1575 must be (a linked copy of) the root directory of the
1576 <literal>fptools</literal> suite. Inside Makefiles, the root of
1577 your build tree is called
1578 <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant><indexterm><primary>FPTOOLS&lowbar;TOP</primary></indexterm>.
1579 In the rest of this document path names are relative to
1580 <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> unless
1581 otherwise stated. For example, the file
1582 <filename>ghc/mk/target.mk</filename> is actually
1583 <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc/mk/target.mk</filename>.</para>
1584 </sect2>
1585
1586 <sect2 id="sec-build-config">
1587 <title>Getting the build you want</title>
1588
1589 <para>When you build <literal>fptools</literal> you will be
1590 compiling code on a particular <emphasis>host
1591 platform</emphasis>, to run on a particular <emphasis>target
1592 platform</emphasis> (usually the same as the host
1593 platform)<indexterm><primary>platform</primary></indexterm>.
1594 The difficulty is that there are minor differences between
1595 different platforms; minor, but enough that the code needs to be
1596 a bit different for each. There are some big differences too:
1597 for a different architecture we need to build GHC with a
1598 different native-code generator.</para>
1599
1600 <para>There are also knobs you can turn to control how the
1601 <literal>fptools</literal> software is built. For example, you
1602 might want to build GHC optimised (so that it runs fast) or
1603 unoptimised (so that you can compile it fast after you've
1604 modified it. Or, you might want to compile it with debugging on
1605 (so that extra consistency-checking code gets included) or off.
1606 And so on.</para>
1607
1608 <para>All of this stuff is called the
1609 <emphasis>configuration</emphasis> of your build. You set the
1610 configuration using a three-step process.</para>
1611
1612 <variablelist>
1613 <varlistentry>
1614 <term>Step 1: get ready for configuration.</term>
1615 <listitem>
1616 <para>NOTE: if you're starting from a source distribution,
1617 rather than CVS sources, you can skip this step.</para>
1618
1619 <para>Change directory to
1620 <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
1621 issue the command</para>
1622 <screen>$ autoreconf</screen>
1623 <indexterm><primary>autoreconf</primary></indexterm>
1624 <para>(with no arguments). This GNU program (recursively) converts
1625 <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure.ac</filename> and
1626 <filename>&dollar;(FPTOOLS&lowbar;TOP)/aclocal.m4</filename>
1627 to a shell script called
1628 <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure</filename>.
1629 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
1630 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
1631 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
1632 a message like "No rule to make target 'mk/config.h.in'".
1633 </para>
1634
1635 <para>Some projects, including GHC, have their own configure script.
1636 <command>autoreconf</command> takes care of that, too, so all you have
1637 to do is calling <command>autoreconf</command> in the top-level directory
1638 <filename>&dollar;(FPTOOLS&lowbar;TOP)</filename>.</para>
1639
1640 <para>These steps are completely platform-independent; they just mean
1641 that the human-written files (<filename>configure.ac</filename> and
1642 <filename>aclocal.m4</filename>) can be short, although the resulting
1643 files (the <command>configure</command> shell scripts and the C header
1644 template <filename>mk/config.h.in</filename>) are long.</para>
1645 </listitem>
1646 </varlistentry>
1647
1648 <varlistentry>
1649 <term>Step 2: system configuration.</term>
1650 <listitem>
1651 <para>Runs the newly-created <command>configure</command>
1652 script, thus:</para>
1653
1654 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
1655
1656 <para><command>configure</command>'s mission is to scurry
1657 round your computer working out what architecture it has,
1658 what operating system, whether it has the
1659 <function>vfork</function> system call, where
1660 <command>tar</command> is kept, whether
1661 <command>gcc</command> is available, where various obscure
1662 <literal>&num;include</literal> files are, whether it's a
1663 leap year, and what the systems manager had for lunch. It
1664 communicates these snippets of information in two
1665 ways:</para>
1666
1667 <itemizedlist>
1668 <listitem>
1669
1670 <para>It translates
1671 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
1672 to
1673 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
1674 substituting for things between
1675 &ldquo;<literal>@</literal>&rdquo; brackets. So,
1676 &ldquo;<literal>@HaveGcc@</literal>&rdquo; will be
1677 replaced by &ldquo;<literal>YES</literal>&rdquo; or
1678 &ldquo;<literal>NO</literal>&rdquo; depending on what
1679 <command>configure</command> finds.
1680 <filename>mk/config.mk</filename> is included by every
1681 Makefile (directly or indirectly), so the
1682 configuration information is thereby communicated to
1683 all Makefiles.</para>
1684 </listitem>
1685
1686 <listitem>
1687 <para> It translates
1688 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
1689 to
1690 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
1691 The latter is <literal>&num;include</literal>d by
1692 various C programs, which can thereby make use of
1693 configuration information.</para>
1694 </listitem>
1695 </itemizedlist>
1696
1697 <para><command>configure</command> takes some optional
1698 arguments. Use <literal>./configure --help</literal> to
1699 get a list of the available arguments. Here are some of
1700 the ones you might need:</para>
1701
1702 <variablelist>
1703 <varlistentry>
1704 <term><literal>--with-ghc=<parameter>path</parameter></literal>
1705 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
1706 </term>
1707 <listitem>
1708 <para>Specifies the path to an installed GHC which
1709 you would like to use. This compiler will be used
1710 for compiling GHC-specific code (eg. GHC itself).
1711 This option <emphasis>cannot</emphasis> be specified
1712 using <filename>build.mk</filename> (see later),
1713 because <command>configure</command> needs to
1714 auto-detect the version of GHC you're using. The
1715 default is to look for a compiler named
1716 <literal>ghc</literal> in your path.</para>
1717 </listitem>
1718 </varlistentry>
1719
1720 <varlistentry>
1721 <term><literal>--with-hc=<parameter>path</parameter></literal>
1722 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
1723 </term>
1724 <listitem>
1725 <para>Specifies the path to any installed Haskell
1726 compiler. This compiler will be used for compiling
1727 generic Haskell code. The default is to use
1728 <literal>ghc</literal>.</para>
1729 </listitem>
1730 </varlistentry>
1731
1732 <varlistentry>
1733 <term><literal>--with-gcc=<parameter>path</parameter></literal>
1734 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
1735 </term>
1736 <listitem>
1737 <para>Specifies the path to the installed GCC. This
1738 compiler will be used to compile all C files,
1739 <emphasis>except</emphasis> any generated by the
1740 installed Haskell compiler, which will have its own
1741 idea of which C compiler (if any) to use. The
1742 default is to use <literal>gcc</literal>.</para>
1743 </listitem>
1744 </varlistentry>
1745 </variablelist>
1746 </listitem>
1747 </varlistentry>
1748
1749 <varlistentry>
1750 <term>Step 3: build configuration.</term>
1751 <listitem>
1752 <para>Next, you say how this build of
1753 <literal>fptools</literal> is to differ from the standard
1754 defaults by creating a new file
1755 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
1756 <emphasis>in the build tree</emphasis>. This file is the
1757 one and only file you edit in the build tree, precisely
1758 because it says how this build differs from the source.
1759 (Just in case your build tree does die, you might want to
1760 keep a private directory of <filename>build.mk</filename>
1761 files, and use a symbolic link in each build tree to point
1762 to the appropriate one.) So
1763 <filename>mk/build.mk</filename> never exists in the
1764 source tree&mdash;you create one in each build tree from
1765 the template. We'll discuss what to put in it
1766 shortly.</para>
1767 </listitem>
1768 </varlistentry>
1769 </variablelist>
1770
1771 <para>And that's it for configuration. Simple, eh?</para>
1772
1773 <para>What do you put in your build-specific configuration file
1774 <filename>mk/build.mk</filename>? <emphasis>For almost all
1775 purposes all you will do is put make variable definitions that
1776 override those in</emphasis>
1777 <filename>mk/config.mk.in</filename>. The whole point of
1778 <filename>mk/config.mk.in</filename>&mdash;and its derived
1779 counterpart <filename>mk/config.mk</filename>&mdash;is to define
1780 the build configuration. It is heavily commented, as you will
1781 see if you look at it. So generally, what you do is look at
1782 <filename>mk/config.mk.in</filename>, and add definitions in
1783 <filename>mk/build.mk</filename> that override any of the
1784 <filename>config.mk</filename> definitions that you want to
1785 change. (The override occurs because the main boilerplate file,
1786 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
1787 includes <filename>build.mk</filename> after
1788 <filename>config.mk</filename>.)</para>
1789
1790 <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
1791 that can serve as a starting point for your <filename>build.mk</filename>.</para>
1792
1793 <para>For example, <filename>config.mk.in</filename> contains
1794 the definition:</para>
1795
1796 <programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
1797
1798 <para>The accompanying comment explains that this is the list of
1799 flags passed to GHC when building GHC itself. For doing
1800 development, it is wise to add <literal>-DDEBUG</literal>, to
1801 enable debugging code. So you would add the following to
1802 <filename>build.mk</filename>:</para>
1803
1804 <para>or, if you prefer,</para>
1805
1806 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
1807
1808 <para>GNU <command>make</command> allows existing definitions to
1809 have new text appended using the &ldquo;<literal>+=</literal>&rdquo;
1810 operator, which is quite a convenient feature.)</para>
1811
1812 <para>If you want to remove the <literal>-O</literal> as well (a
1813 good idea when developing, because the turn-around cycle gets a
1814 lot quicker), you can just override
1815 <literal>GhcLibHcOpts</literal> altogether:</para>
1816
1817 <programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
1818
1819 <para>When reading <filename>config.mk.in</filename>, remember
1820 that anything between &ldquo;@...@&rdquo; signs is going to be substituted
1821 by <command>configure</command> later. You
1822 <emphasis>can</emphasis> override the resulting definition if
1823 you want, but you need to be a bit surer what you are doing.
1824 For example, there's a line that says:</para>
1825
1826 <programlisting>TAR = @TarCmd@</programlisting>
1827
1828 <para>This defines the Make variables <constant>TAR</constant>
1829 to the pathname for a <command>tar</command> that
1830 <command>configure</command> finds somewhere. If you have your
1831 own pet <command>tar</command> you want to use instead, that's
1832 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
1833
1834 <programlisting>TAR = mytar</programlisting>
1835
1836 <para>You do not <emphasis>have</emphasis> to have a
1837 <filename>mk/build.mk</filename> file at all; if you don't,
1838 you'll get all the default settings from
1839 <filename>mk/config.mk.in</filename>.</para>
1840
1841 <para>You can also use <filename>build.mk</filename> to override
1842 anything that <command>configure</command> got wrong. One place
1843 where this happens often is with the definition of
1844 <constant>FPTOOLS&lowbar;TOP&lowbar;ABS</constant>: this
1845 variable is supposed to be the canonical path to the top of your
1846 source tree, but if your system uses an automounter then the
1847 correct directory is hard to find automatically. If you find
1848 that <command>configure</command> has got it wrong, just put the
1849 correct definition in <filename>build.mk</filename>.</para>
1850
1851 </sect2>
1852
1853 <sect2 id="sec-storysofar">
1854 <title>The story so far</title>
1855
1856 <para>Let's summarise the steps you need to carry to get
1857 yourself a fully-configured build tree from scratch.</para>
1858
1859 <orderedlist>
1860 <listitem>
1861 <para> Get your source tree from somewhere (CVS repository
1862 or source distribution). Say you call the root directory
1863 <filename>myfptools</filename> (it does not have to be
1864 called <filename>fptools</filename>). Make sure that you
1865 have the essential files (see <xref
1866 linkend="sec-source-tree"/>).</para>
1867 </listitem>
1868
1869 <listitem>
1870
1871 <para>(Optional) Use <command>lndir</command> or
1872 <command>mkshadowdir</command> to create a build tree.</para>
1873
1874 <screen>$ cd myfptools
1875 $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
1876
1877 <para>(N.B. <command>mkshadowdir</command>'s first argument
1878 is taken relative to its second.) You probably want to give
1879 the build tree a name that suggests its main defining
1880 characteristic (in your mind at least), in case you later
1881 add others.</para>
1882 </listitem>
1883
1884 <listitem>
1885 <para>Change directory to the build tree. Everything is
1886 going to happen there now.</para>
1887
1888 <screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
1889
1890 </listitem>
1891
1892 <listitem>
1893 <para>Prepare for system configuration:</para>
1894
1895 <screen>$ autoreconf</screen>
1896
1897 <para>(You can skip this step if you are starting from a
1898 source distribution, and you already have
1899 <filename>configure</filename> and
1900 <filename>mk/config.h.in</filename>.)</para>
1901 </listitem>
1902
1903 <listitem>
1904 <para>Do system configuration:</para>
1905
1906 <screen>$ ./configure</screen>
1907
1908 <para>Don't forget to check whether you need to add any
1909 arguments to <literal>configure</literal>; for example, a
1910 common requirement is to specify which GHC to use with
1911 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
1912 </listitem>
1913
1914 <listitem>
1915 <para>Create the file <filename>mk/build.mk</filename>,
1916 adding definitions for your desired configuration
1917 options.</para>
1918
1919 <screen>$ emacs mk/build.mk</screen>
1920 </listitem>
1921 </orderedlist>
1922
1923 <para>You can make subsequent changes to
1924 <filename>mk/build.mk</filename> as often as you like. You do
1925 not have to run any further configuration programs to make these
1926 changes take effect. In theory you should, however, say
1927 <command>gmake clean</command>, <command>gmake all</command>,
1928 because configuration option changes could affect
1929 anything&mdash;but in practice you are likely to know what's
1930 affected.</para>
1931 </sect2>
1932
1933 <sect2>
1934 <title>Making things</title>
1935
1936 <para>At this point you have made yourself a fully-configured
1937 build tree, so you are ready to start building real
1938 things.</para>
1939
1940 <para>The first thing you need to know is that <emphasis>you
1941 must use GNU <command>make</command>, usually called
1942 <command>gmake</command>, not standard Unix
1943 <command>make</command></emphasis>. If you use standard Unix
1944 <command>make</command> you will get all sorts of error messages
1945 (but no damage) because the <literal>fptools</literal>
1946 <command>Makefiles</command> use GNU <command>make</command>'s
1947 facilities extensively.</para>
1948
1949 <para>To just build the whole thing, <command>cd</command> to
1950 the top of your <literal>fptools</literal> tree and type
1951 <command>gmake</command>. This will prepare the tree and build
1952 the various projects in the correct order.</para>
1953 </sect2>
1954
1955 <sect2 id="sec-bootstrapping">
1956 <title>Bootstrapping GHC</title>
1957
1958 <para>GHC requires a 2-stage bootstrap in order to provide
1959 full functionality, including GHCi. By a 2-stage bootstrap, we
1960 mean that the compiler is built once using the installed GHC,
1961 and then again using the compiler built in the first stage. You
1962 can also build a stage 3 compiler, but this normally isn't
1963 necessary except to verify that the stage 2 compiler is working
1964 properly.</para>
1965
1966 <para>Note that when doing a bootstrap, the stage 1 compiler
1967 must be built, followed by the runtime system and libraries, and
1968 then the stage 2 compiler. The correct ordering is implemented
1969 by the top-level fptools <filename>Makefile</filename>, so if
1970 you want everything to work automatically it's best to start
1971 <command>make</command> from the top of the tree. When building
1972 GHC, the top-level fptools <filename>Makefile</filename> is set
1973 up to do a 2-stage bootstrap by default (when you say
1974 <command>make</command>). Some other targets it supports
1975 are:</para>
1976
1977 <variablelist>
1978 <varlistentry>
1979 <term>stage1</term>
1980 <listitem>
1981 <para>Build everything as normal, including the stage 1
1982 compiler.</para>
1983 </listitem>
1984 </varlistentry>
1985
1986 <varlistentry>
1987 <term>stage2</term>
1988 <listitem>
1989 <para>Build the stage 2 compiler only.</para>
1990 </listitem>
1991 </varlistentry>
1992
1993 <varlistentry>
1994 <term>stage3</term>
1995 <listitem>
1996 <para>Build the stage 3 compiler only.</para>
1997 </listitem>
1998 </varlistentry>
1999
2000 <varlistentry>
2001 <term>bootstrap</term> <term>bootstrap2</term>
2002 <listitem>
2003 <para>Build stage 1 followed by stage 2.</para>
2004 </listitem>
2005 </varlistentry>
2006
2007 <varlistentry>
2008 <term>bootstrap3</term>
2009 <listitem>
2010 <para>Build stages 1, 2 and 3.</para>
2011 </listitem>
2012 </varlistentry>
2013
2014 <varlistentry>
2015 <term>install</term>
2016 <listitem>
2017 <para>Install everything, including the compiler built in
2018 stage 2. To override the stage, say <literal>make install
2019 stage=<replaceable>n</replaceable></literal> where
2020 <replaceable>n</replaceable> is the stage to install.</para>
2021 </listitem>
2022 </varlistentry>
2023 </variablelist>
2024
2025 <para>The top-level <filename>Makefile</filename> also arranges
2026 to do the appropriate <literal>make boot</literal> steps (see
2027 below) before actually building anything.</para>
2028
2029 <para>The <literal>stage1</literal>, <literal>stage2</literal>
2030 and <literal>stage3</literal> targets also work in the
2031 <literal>ghc/compiler</literal> directory, but don't forget that
2032 each stage requires its own <literal>make boot</literal> step:
2033 for example, you must do</para>
2034
2035 <screen>$ make boot stage=2</screen>
2036
2037 <para>before <literal>make stage2</literal> in
2038 <literal>ghc/compiler</literal>.</para>
2039 </sect2>
2040
2041 <sect2 id="sec-standard-targets">
2042 <title>Standard Targets</title>
2043 <indexterm><primary>targets, standard makefile</primary></indexterm>
2044 <indexterm><primary>makefile targets</primary></indexterm>
2045
2046 <para>In any directory you should be able to make the following:</para>
2047
2048 <variablelist>
2049 <varlistentry>
2050 <term><literal>boot</literal></term>
2051 <listitem>
2052 <para>does the one-off preparation required to get ready
2053 for the real work. Notably, it does <command>gmake
2054 depend</command> in all directories that contain programs.
2055 It also builds the necessary tools for compilation to
2056 proceed.</para>
2057
2058 <para>Invoking the <literal>boot</literal> target
2059 explicitly is not normally necessary. From the top-level
2060 <literal>fptools</literal> directory, invoking
2061 <literal>gmake</literal> causes <literal>gmake boot
2062 all</literal> to be invoked in each of the project
2063 subdirectories, in the order specified by
2064 <literal>&dollar;(AllTargets)</literal> in
2065 <literal>config.mk</literal>.</para>
2066
2067 <para>If you're working in a subdirectory somewhere and
2068 need to update the dependencies, <literal>gmake
2069 boot</literal> is a good way to do it.</para>
2070 </listitem>
2071 </varlistentry>
2072
2073 <varlistentry>
2074 <term><literal>all</literal></term>
2075 <listitem>
2076 <para>makes all the final target(s) for this Makefile.
2077 Depending on which directory you are in a &ldquo;final
2078 target&rdquo; may be an executable program, a library
2079 archive, a shell script, or a Postscript file. Typing
2080 <command>gmake</command> alone is generally the same as
2081 typing <command>gmake all</command>.</para>
2082 </listitem>
2083 </varlistentry>
2084
2085 <varlistentry>
2086 <term><literal>install</literal></term>
2087 <listitem>
2088 <para>installs the things built by <literal>all</literal>
2089 (except for the documentation). Where does it install
2090 them? That is specified by
2091 <filename>mk/config.mk.in</filename>; you can override it
2092 in <filename>mk/build.mk</filename>, or by running
2093 <command>configure</command> with command-line arguments
2094 like <literal>--bindir=/home/simonpj/bin</literal>; see
2095 <literal>./configure --help</literal> for the full
2096 details.</para>
2097 </listitem>
2098 </varlistentry>
2099
2100 <varlistentry>
2101 <term><literal>install-docs</literal></term>
2102 <listitem>
2103 <para>installs the documentation. Otherwise behaves just
2104 like <literal>install</literal>.</para>
2105 </listitem>
2106 </varlistentry>
2107
2108 <varlistentry>
2109 <term><literal>uninstall</literal></term>
2110 <listitem>
2111 <para>reverses the effect of
2112 <literal>install</literal>.</para>
2113 </listitem>
2114 </varlistentry>
2115
2116 <varlistentry>
2117 <term><literal>clean</literal></term>
2118 <listitem>
2119 <para>Delete all files from the current directory that are
2120 normally created by building the program. Don't delete
2121 the files that record the configuration, or files
2122 generated by <command>gmake boot</command>. Also preserve
2123 files that could be made by building, but normally aren't
2124 because the distribution comes with them.</para>
2125 </listitem>
2126 </varlistentry>
2127
2128 <varlistentry>
2129 <term><literal>distclean</literal></term>
2130 <listitem>
2131 <para>Delete all files from the current directory that are
2132 created by configuring or building the program. If you
2133 have unpacked the source and built the program without
2134 creating any other files, <literal>make
2135 distclean</literal> should leave only the files that were
2136 in the distribution.</para>
2137 </listitem>
2138 </varlistentry>
2139
2140 <varlistentry>
2141 <term><literal>mostlyclean</literal></term>
2142 <listitem>
2143 <para>Like <literal>clean</literal>, but may refrain from
2144 deleting a few files that people normally don't want to
2145 recompile.</para>
2146 </listitem>
2147 </varlistentry>
2148
2149 <varlistentry>
2150 <term><literal>maintainer-clean</literal></term>
2151 <listitem>
2152 <para>Delete everything from the current directory that
2153 can be reconstructed with this Makefile. This typically
2154 includes everything deleted by
2155 <literal>distclean</literal>, plus more: C source files
2156 produced by Bison, tags tables, Info files, and so
2157 on.</para>
2158
2159 <para>One exception, however: <literal>make
2160 maintainer-clean</literal> should not delete
2161 <filename>configure</filename> even if
2162 <filename>configure</filename> can be remade using a rule
2163 in the <filename>Makefile</filename>. More generally,
2164 <literal>make maintainer-clean</literal> should not delete
2165 anything that needs to exist in order to run
2166 <filename>configure</filename> and then begin to build the
2167 program.</para>
2168 </listitem>
2169 </varlistentry>
2170
2171 <varlistentry>
2172 <term><literal>check</literal></term>
2173 <listitem>
2174 <para>run the test suite.</para>
2175 </listitem>
2176 </varlistentry>
2177 </variablelist>
2178
2179 <para>All of these standard targets automatically recurse into
2180 sub-directories. Certain other standard targets do not:</para>
2181
2182 <variablelist>
2183 <varlistentry>
2184 <term><literal>configure</literal></term>
2185 <listitem>
2186 <para>is only available in the root directory
2187 <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>; it has
2188 been discussed in <xref
2189 linkend="sec-build-config"/>.</para>
2190 </listitem>
2191 </varlistentry>
2192
2193 <varlistentry>
2194 <term><literal>depend</literal></term>
2195 <listitem>
2196 <para>make a <filename>.depend</filename> file in each
2197 directory that needs it. This <filename>.depend</filename>
2198 file contains mechanically-generated dependency
2199 information; for example, suppose a directory contains a
2200 Haskell source module <filename>Foo.lhs</filename> which
2201 imports another module <literal>Baz</literal>. Then the
2202 generated <filename>.depend</filename> file will contain
2203 the dependency:</para>
2204
2205 <programlisting>Foo.o : Baz.hi</programlisting>
2206
2207 <para>which says that the object file
2208 <filename>Foo.o</filename> depends on the interface file
2209 <filename>Baz.hi</filename> generated by compiling module
2210 <literal>Baz</literal>. The <filename>.depend</filename>
2211 file is automatically included by every Makefile.</para>
2212 </listitem>
2213 </varlistentry>
2214
2215 <varlistentry>
2216 <term><literal>binary-dist</literal></term>
2217 <listitem>
2218 <para>make a binary distribution. This is the target we
2219 use to build the binary distributions of GHC and
2220 Happy.</para>
2221 </listitem>
2222 </varlistentry>
2223
2224 <varlistentry>
2225 <term><literal>dist</literal></term>
2226 <listitem>
2227 <para>make a source distribution. Note that this target
2228 does &ldquo;make distclean&rdquo; as part of its work;
2229 don't use it if you want to keep what you've built.</para>
2230 </listitem>
2231 </varlistentry>
2232 </variablelist>
2233
2234 <para>Most <filename>Makefile</filename>s have targets other
2235 than these. You can discover them by looking in the
2236 <filename>Makefile</filename> itself.</para>
2237 </sect2>
2238
2239 <sect2>
2240 <title>Using a project from the build tree</title>
2241
2242 <para>If you want to build GHC (say) and just use it direct from
2243 the build tree without doing <literal>make install</literal>
2244 first, you can run the in-place driver script:
2245 <filename>ghc/compiler/ghc-inplace</filename>.</para>
2246
2247 <para> Do <emphasis>NOT</emphasis> use
2248 <filename>ghc/compiler/ghc</filename>, or
2249 <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
2250 scripts intended for installation, and contain hard-wired paths
2251 to the installed libraries, rather than the libraries in the
2252 build tree.</para>
2253
2254 <para>Happy can similarly be run from the build tree, using
2255 <filename>happy/src/happy-inplace</filename>, and similarly for
2256 Alex and Haddock.</para>
2257 </sect2>
2258
2259 <sect2>
2260 <title>Fast Making</title>
2261
2262 <indexterm><primary>fastmake</primary></indexterm>
2263 <indexterm><primary>dependencies, omitting</primary></indexterm>
2264 <indexterm><primary>FAST, makefile variable</primary></indexterm>
2265
2266 <para>Sometimes the dependencies get in the way: if you've made
2267 a small change to one file, and you're absolutely sure that it
2268 won't affect anything else, but you know that
2269 <command>make</command> is going to rebuild everything anyway,
2270 the following hack may be useful:</para>
2271
2272 <screen>$ gmake FAST=YES</screen>
2273
2274 <para>This tells the make system to ignore dependencies and just
2275 build what you tell it to. In other words, it's equivalent to
2276 temporarily removing the <filename>.depend</filename> file in
2277 the current directory (where <command>mkdependHS</command> and
2278 friends store their dependency information).</para>
2279
2280 <para>A bit of history: GHC used to come with a
2281 <command>fastmake</command> script that did the above job, but
2282 GNU make provides the features we need to do it without
2283 resorting to a script. Also, we've found that fastmaking is
2284 less useful since the advent of GHC's recompilation checker (see
2285 the User's Guide section on "Separate Compilation").</para>
2286 </sect2>
2287 </sect1>
2288
2289 <sect1 id="sec-makefile-arch">
2290 <title>The <filename>Makefile</filename> architecture</title>
2291 <indexterm><primary>makefile architecture</primary></indexterm>
2292
2293 <para><command>make</command> is great if everything
2294 works&mdash;you type <command>gmake install</command> and lo! the
2295 right things get compiled and installed in the right places. Our
2296 goal is to make this happen often, but somehow it often doesn't;
2297 instead some weird error message eventually emerges from the
2298 bowels of a directory you didn't know existed.</para>
2299
2300 <para>The purpose of this section is to give you a road-map to
2301 help you figure out what is going right and what is going
2302 wrong.</para>
2303
2304 <sect2>
2305 <title>Debugging</title>
2306
2307 <para>Debugging <filename>Makefile</filename>s is something of a
2308 black art, but here's a couple of tricks that we find
2309 particularly useful. The following command allows you to see
2310 the contents of any make variable in the context of the current
2311 <filename>Makefile</filename>:</para>
2312
2313 <screen>$ make show VALUE=HS_SRCS</screen>
2314
2315 <para>where you can replace <literal>HS_SRCS</literal> with the
2316 name of any variable you wish to see the value of.</para>
2317
2318 <para>GNU make has a <option>-d</option> option which generates
2319 a dump of the decision procedure used to arrive at a conclusion
2320 about which files should be recompiled. Sometimes useful for
2321 tracking down problems with superfluous or missing
2322 recompilations.</para>
2323 </sect2>
2324
2325 <sect2>
2326 <title>A small project</title>
2327
2328 <para>To get started, let us look at the
2329 <filename>Makefile</filename> for an imaginary small
2330 <literal>fptools</literal> project, <literal>small</literal>.
2331 Each project in <literal>fptools</literal> has its own directory
2332 in <constant>FPTOOLS&lowbar;TOP</constant>, so the
2333 <literal>small</literal> project will have its own directory
2334 <constant>FPOOLS&lowbar;TOP/small/</constant>. Inside the
2335 <filename>small/</filename> directory there will be a
2336 <filename>Makefile</filename>, looking something like
2337 this:</para>
2338
2339 <indexterm><primary>Makefile, minimal</primary></indexterm>
2340
2341 <programlisting># Makefile for fptools project "small"
2342
2343 TOP = ..
2344 include $(TOP)/mk/boilerplate.mk
2345
2346 SRCS = $(wildcard *.lhs) $(wildcard *.c)
2347 HS_PROG = small
2348
2349 include $(TOP)/target.mk</programlisting>
2350
2351 <para>this <filename>Makefile</filename> has three
2352 sections:</para>
2353
2354 <orderedlist>
2355 <listitem>
2356 <para>The first section includes
2357 <footnote>
2358 <para>
2359 One of the most important
2360 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
2361 include another named file, very like <command>cpp</command>'s <literal>&num;include</literal>
2362 directive.
2363 </para>
2364 </footnote>
2365
2366 a file of &ldquo;boilerplate&rdquo; code from the level
2367 above (which in this case will be
2368 <filename>FPTOOLS&lowbar;TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
2369 As its name suggests, <filename>boilerplate.mk</filename>
2370 consists of a large quantity of standard
2371 <filename>Makefile</filename> code. We discuss this
2372 boilerplate in more detail in <xref linkend="sec-boiler"/>.
2373 <indexterm><primary>include, directive in
2374 Makefiles</primary></indexterm> <indexterm><primary>Makefile
2375 inclusion</primary></indexterm></para>
2376
2377 <para>Before the <literal>include</literal> statement, you
2378 must define the <command>make</command> variable
2379 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
2380 to be the directory containing the <filename>mk</filename>
2381 directory in which the <filename>boilerplate.mk</filename>
2382 file is. It is <emphasis>not</emphasis> OK to simply say</para>
2383
2384 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
2385
2386
2387 <para>Why? Because the <filename>boilerplate.mk</filename>
2388 file needs to know where it is, so that it can, in turn,
2389 <literal>include</literal> other files. (Unfortunately,
2390 when an <literal>include</literal>d file does an
2391 <literal>include</literal>, the filename is treated relative
2392 to the directory in which <command>gmake</command> is being
2393 run, not the directory in which the
2394 <literal>include</literal>d sits.) In general,
2395 <emphasis>every file <filename>foo.mk</filename> assumes
2396 that
2397 <filename>&dollar;(TOP)/mk/foo.mk</filename>
2398 refers to itself.</emphasis> It is up to the
2399 <filename>Makefile</filename> doing the
2400 <literal>include</literal> to ensure this is the case.</para>
2401
2402 <para>Files intended for inclusion in other
2403 <filename>Makefile</filename>s are written to have the
2404 following property: <emphasis>after
2405 <filename>foo.mk</filename> is <literal>include</literal>d,
2406 it leaves <constant>TOP</constant> containing the same value
2407 as it had just before the <literal>include</literal>
2408 statement</emphasis>. In our example, this invariant
2409 guarantees that the <literal>include</literal> for
2410 <filename>target.mk</filename> will look in the same
2411 directory as that for <filename>boilerplate.mk</filename>.</para>
2412 </listitem>
2413
2414 <listitem>
2415 <para> The second section defines the following standard
2416 <command>make</command> variables:
2417 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
2418 (the source files from which is to be built), and
2419 <constant>HS&lowbar;PROG</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>
2420 (the executable binary to be built). We will discuss in
2421 more detail what the &ldquo;standard variables&rdquo; are,
2422 and how they affect what happens, in <xref
2423 linkend="sec-targets"/>.</para>
2424
2425 <para>The definition for <constant>SRCS</constant> uses the
2426 useful GNU <command>make</command> construct
2427 <literal>&dollar;(wildcard&nbsp;$pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
2428 which expands to a list of all the files matching the
2429 pattern <literal>pat</literal> in the current directory. In
2430 this example, <constant>SRCS</constant> is set to the list
2431 of all the <filename>.lhs</filename> and
2432 <filename>.c</filename> files in the directory. (Let's
2433 suppose there is one of each, <filename>Foo.lhs</filename>
2434 and <filename>Baz.c</filename>.)</para>
2435 </listitem>
2436
2437 <listitem>
2438 <para>The last section includes a second file of standard
2439 code, called
2440 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
2441 It contains the rules that tell <command>gmake</command> how
2442 to make the standard targets (<xref
2443 linkend="sec-standard-targets"/>). Why, you ask, can't this
2444 standard code be part of
2445 <filename>boilerplate.mk</filename>? Good question. We
2446 discuss the reason later, in <xref
2447 linkend="sec-boiler-arch"/>.</para>
2448
2449 <para>You do not <emphasis>have</emphasis> to
2450 <literal>include</literal> the
2451 <filename>target.mk</filename> file. Instead, you can write
2452 rules of your own for all the standard targets. Usually,
2453 though, you will find quite a big payoff from using the
2454 canned rules in <filename>target.mk</filename>; the price
2455 tag is that you have to understand what canned rules get
2456 enabled, and what they do (<xref
2457 linkend="sec-targets"/>).</para>
2458 </listitem>
2459 </orderedlist>
2460
2461 <para>In our example <filename>Makefile</filename>, most of the
2462 work is done by the two <literal>include</literal>d files. When
2463 you say <command>gmake all</command>, the following things
2464 happen:</para>
2465
2466 <itemizedlist>
2467 <listitem>
2468 <para><command>gmake</command> figures out that the object
2469 files are <filename>Foo.o</filename> and
2470 <filename>Baz.o</filename>.</para>
2471 </listitem>
2472
2473 <listitem>
2474 <para>It uses a boilerplate pattern rule to compile
2475 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
2476 using a Haskell compiler. (Which one? That is set in the
2477 build configuration.)</para>
2478 </listitem>
2479
2480 <listitem>
2481 <para>It uses another standard pattern rule to compile
2482 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
2483 using a C compiler. (Ditto.)</para>
2484 </listitem>
2485
2486 <listitem>
2487 <para>It links the resulting <filename>.o</filename> files
2488 together to make <literal>small</literal>, using the Haskell
2489 compiler to do the link step. (Why not use
2490 <command>ld</command>? Because the Haskell compiler knows
2491 what standard libraries to link in. How did
2492 <command>gmake</command> know to use the Haskell compiler to
2493 do the link, rather than the C compiler? Because we set the
2494 variable <constant>HS&lowbar;PROG</constant> rather than
2495 <constant>C&lowbar;PROG</constant>.)</para>
2496 </listitem>
2497 </itemizedlist>
2498
2499 <para>All <filename>Makefile</filename>s should follow the above
2500 three-section format.</para>
2501 </sect2>
2502
2503 <sect2>
2504 <title>A larger project</title>
2505
2506 <para>Larger projects are usually structured into a number of
2507 sub-directories, each of which has its own
2508 <filename>Makefile</filename>. (In very large projects, this
2509 sub-structure might be iterated recursively, though that is
2510 rare.) To give you the idea, here's part of the directory
2511 structure for the (rather large) GHC project:</para>
2512
2513 <programlisting>$(FPTOOLS_TOP)/ghc/
2514 Makefile
2515 mk/
2516 boilerplate.mk
2517 rules.mk
2518 docs/
2519 Makefile
2520 ...source files for documentation...
2521 driver/
2522 Makefile
2523 ...source files for driver...
2524 compiler/
2525 Makefile
2526 parser/...source files for parser...
2527 renamer/...source files for renamer...
2528 ...etc...</programlisting>
2529
2530 <para>The sub-directories <filename>docs</filename>,
2531 <filename>driver</filename>, <filename>compiler</filename>, and
2532 so on, each contains a sub-component of GHC, and each has its
2533 own <filename>Makefile</filename>. There must also be a
2534 <filename>Makefile</filename> in
2535 <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc</filename>.
2536 It does most of its work by recursively invoking
2537 <command>gmake</command> on the <filename>Makefile</filename>s
2538 in the sub-directories. We say that
2539 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
2540 <filename>Makefile</filename></emphasis>, because it does little
2541 except organise its children, while the
2542 <filename>Makefile</filename>s in the sub-directories are all
2543 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
2544 principle the sub-directories might themselves contain a
2545 non-leaf <filename>Makefile</filename> and several
2546 sub-sub-directories, but that does not happen in GHC.)</para>
2547
2548 <para>The <filename>Makefile</filename> in
2549 <filename>ghc/compiler</filename> is considered a leaf
2550 <filename>Makefile</filename> even though the
2551 <filename>ghc/compiler</filename> has sub-directories, because
2552 these sub-directories do not themselves have
2553 <filename>Makefile</filename>s in them. They are just used to
2554 structure the collection of modules that make up GHC, but all
2555 are managed by the single <filename>Makefile</filename> in
2556 <filename>ghc/compiler</filename>.</para>
2557
2558 <para>You will notice that <filename>ghc/</filename> also
2559 contains a directory <filename>ghc/mk/</filename>. It contains
2560 GHC-specific <filename>Makefile</filename> boilerplate code.
2561 More precisely:</para>
2562
2563 <itemizedlist>
2564 <listitem>
2565 <para><filename>ghc/mk/boilerplate.mk</filename> is included
2566 at the top of <filename>ghc/Makefile</filename>, and of all
2567 the leaf <filename>Makefile</filename>s in the
2568 sub-directories. It in turn <literal>include</literal>s the
2569 main boilerplate file
2570 <filename>mk/boilerplate.mk</filename>.</para>
2571 </listitem>
2572
2573 <listitem>
2574 <para><filename>ghc/mk/target.mk</filename> is
2575 <literal>include</literal>d at the bottom of
2576 <filename>ghc/Makefile</filename>, and of all the leaf
2577 <filename>Makefile</filename>s in the sub-directories. It
2578 in turn <literal>include</literal>s the file
2579 <filename>mk/target.mk</filename>.</para>
2580 </listitem>
2581 </itemizedlist>
2582
2583 <para>So these two files are the place to look for GHC-wide
2584 customisation of the standard boilerplate.</para>
2585 </sect2>
2586
2587 <sect2 id="sec-boiler-arch">
2588 <title>Boilerplate architecture</title>
2589 <indexterm><primary>boilerplate architecture</primary></indexterm>
2590
2591 <para>Every <filename>Makefile</filename> includes a
2592 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
2593 file at the top, and
2594 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2595 file at the bottom. In this section we discuss what is in these
2596 files, and why there have to be two of them. In general:</para>
2597
2598 <itemizedlist>
2599 <listitem>
2600 <para><filename>boilerplate.mk</filename> consists of:</para>
2601
2602 <itemizedlist>
2603 <listitem>
2604 <para><emphasis>Definitions of millions of
2605 <command>make</command> variables</emphasis> that
2606 collectively specify the build configuration. Examples:
2607 <constant>HC&lowbar;OPTS</constant><indexterm><primary>HC&lowbar;OPTS</primary></indexterm>,
2608 the options to feed to the Haskell compiler;
2609 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
2610 the sub-directories to enable within the
2611 <literal>nofib</literal> project;
2612 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
2613 the name of the Haskell compiler to use when compiling
2614 GHC in the <literal>ghc</literal> project.</para>
2615 </listitem>
2616
2617 <listitem>
2618 <para><emphasis>Standard pattern rules</emphasis> that
2619 tell <command>gmake</command> how to construct one file
2620 from another.</para>
2621 </listitem>
2622 </itemizedlist>
2623
2624 <para><filename>boilerplate.mk</filename> needs to be
2625 <literal>include</literal>d at the <emphasis>top</emphasis>
2626 of each <filename>Makefile</filename>, so that the user can
2627 replace the boilerplate definitions or pattern rules by
2628 simply giving a new definition or pattern rule in the
2629 <filename>Makefile</filename>. <command>gmake</command>
2630 simply takes the last definition as the definitive one.</para>
2631
2632 <para>Instead of <emphasis>replacing</emphasis> boilerplate
2633 definitions, it is also quite common to
2634 <emphasis>augment</emphasis> them. For example, a
2635 <filename>Makefile</filename> might say:</para>
2636
2637 <programlisting>SRC_HC_OPTS += -O</programlisting>
2638
2639 <para>thereby adding &ldquo;<option>-O</option>&rdquo; to
2640 the end of
2641 <constant>SRC&lowbar;HC&lowbar;OPTS</constant><indexterm><primary>SRC&lowbar;HC&lowbar;OPTS</primary></indexterm>.</para>
2642 </listitem>
2643
2644 <listitem>
2645 <para><filename>target.mk</filename> contains
2646 <command>make</command> rules for the standard targets
2647 described in <xref linkend="sec-standard-targets"/>. These
2648 rules are selectively included, depending on the setting of
2649 certain <command>make</command> variables. These variables
2650 are usually set in the middle section of the
2651 <filename>Makefile</filename> between the two
2652 <literal>include</literal>s.</para>
2653
2654 <para><filename>target.mk</filename> must be included at the
2655 end (rather than being part of
2656 <filename>boilerplate.mk</filename>) for several tiresome
2657 reasons:</para>
2658
2659 <itemizedlist>
2660 <listitem>
2661
2662 <para><command>gmake</command> commits target and
2663 dependency lists earlier than it should. For example,
2664 <filename>target.mk</filename> has a rule that looks
2665 like this:</para>
2666
2667 <programlisting>$(HS_PROG) : $(OBJS)
2668 $(HC) $(LD_OPTS) $&#60; -o $@</programlisting>
2669
2670 <para>If this rule was in
2671 <filename>boilerplate.mk</filename> then
2672 <constant>&dollar;(HS&lowbar;PROG)</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>
2673 and
2674 <constant>&dollar;(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
2675 would not have their final values at the moment
2676 <command>gmake</command> encountered the rule. Alas,
2677 <command>gmake</command> takes a snapshot of their
2678 current values, and wires that snapshot into the rule.
2679 (In contrast, the commands executed when the rule
2680 &ldquo;fires&rdquo; are only substituted at the moment
2681 of firing.) So, the rule must follow the definitions
2682 given in the <filename>Makefile</filename> itself.</para>
2683 </listitem>
2684
2685 <listitem>
2686 <para>Unlike pattern rules, ordinary rules cannot be
2687 overriden or replaced by subsequent rules for the same
2688 target (at least, not without an error message).
2689 Including ordinary rules in
2690 <filename>boilerplate.mk</filename> would prevent the
2691 user from writing rules for specific targets in specific
2692 cases.</para>
2693 </listitem>
2694
2695 <listitem>
2696 <para>There are a couple of other reasons I've
2697 forgotten, but it doesn't matter too much.</para>
2698 </listitem>
2699 </itemizedlist>
2700 </listitem>
2701 </itemizedlist>
2702 </sect2>
2703
2704 <sect2 id="sec-boiler">
2705 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
2706 <indexterm><primary>boilerplate.mk</primary></indexterm>
2707
2708 <para>If you look at
2709 <filename>&dollar;(FPTOOLS&lowbar;TOP)/mk/boilerplate.mk</filename>
2710 you will find that it consists of the following sections, each
2711 held in a separate file:</para>
2712
2713 <variablelist>
2714 <varlistentry>
2715 <term><filename>config.mk</filename>
2716 <indexterm><primary>config.mk</primary></indexterm>
2717 </term>
2718 <listitem>
2719 <para>is the build configuration file we discussed at
2720 length in <xref linkend="sec-build-config"/>.</para>
2721 </listitem>
2722 </varlistentry>
2723
2724 <varlistentry>
2725 <term><filename>paths.mk</filename>
2726 <indexterm><primary>paths.mk</primary></indexterm>
2727 </term>
2728 <listitem>
2729 <para>defines <command>make</command> variables for
2730 pathnames and file lists. This file contains code for
2731 automatically compiling lists of source files and deriving
2732 lists of object files from those. The results can be
2733 overriden in the <filename>Makefile</filename>, but in
2734 most cases the automatic setup should do the right
2735 thing.</para>
2736
2737 <para>The following variables may be set in the
2738 <filename>Makefile</filename> to affect how the automatic
2739 source file search is done:</para>
2740
2741 <variablelist>
2742 <varlistentry>
2743 <term><literal>ALL_DIRS</literal>
2744 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
2745 </term>
2746 <listitem>
2747 <para>Set to a list of directories to search in
2748 addition to the current directory for source
2749 files.</para>
2750 </listitem>
2751 </varlistentry>
2752
2753 <varlistentry>
2754 <term><literal>EXCLUDED_SRCS</literal>
2755 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
2756 </term>
2757 <listitem>
2758 <para>Set to a list of source files (relative to the
2759 current directory) to omit from the automatic
2760 search. The source searching machinery is clever
2761 enough to know that if you exclude a source file
2762 from which other sources are derived, then the
2763 derived sources should also be excluded. For
2764 example, if you set <literal>EXCLUDED_SRCS</literal>
2765 to include <filename>Foo.y</filename>, then
2766 <filename>Foo.hs</filename> will also be
2767 excluded.</para>
2768 </listitem>
2769 </varlistentry>
2770
2771 <varlistentry>
2772 <term><literal>EXTRA_SRCS</literal>
2773 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
2774 </term>
2775 <listitem>
2776 <para>Set to a list of extra source files (perhaps
2777 in directories not listed in
2778 <literal>ALL_DIRS</literal>) that should be
2779 considered.</para>
2780 </listitem>
2781 </varlistentry>
2782 </variablelist>
2783
2784 <para>The results of the automatic source file search are
2785 placed in the following make variables:</para>
2786
2787 <variablelist>
2788 <varlistentry>
2789 <term><literal>SRCS</literal>
2790 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
2791 </term>
2792 <listitem>
2793 <para>All source files found, sorted and without
2794 duplicates, including those which might not exist
2795 yet but will be derived from other existing sources.
2796 <literal>SRCS</literal> <emphasis>can</emphasis> be
2797 overriden if necessary, in which case the variables
2798 below will follow suit.</para>
2799 </listitem>
2800 </varlistentry>
2801
2802 <varlistentry>
2803 <term><literal>HS_SRCS</literal>
2804 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
2805 </term>
2806 <listitem>
2807 <para>all Haskell source files in the current
2808 directory, including those derived from other source
2809 files (eg. Happy sources also give rise to Haskell
2810 sources).</para>
2811 </listitem>
2812 </varlistentry>
2813
2814 <varlistentry>
2815 <term><literal>HS_OBJS</literal>
2816 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
2817 </term>
2818 <listitem>
2819 <para>Object files derived from
2820 <literal>HS_SRCS</literal>.</para>
2821 </listitem>
2822 </varlistentry>
2823
2824 <varlistentry>
2825 <term><literal>HS_IFACES</literal>
2826 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
2827 </term>
2828 <listitem>
2829 <para>Interface files (<literal>.hi</literal> files)
2830 derived from <literal>HS_SRCS</literal>.</para>
2831 </listitem>
2832 </varlistentry>
2833
2834 <varlistentry>
2835 <term><literal>C_SRCS</literal>
2836 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
2837 </term>
2838 <listitem>
2839 <para>All C source files found.</para>
2840 </listitem>
2841 </varlistentry>
2842
2843 <varlistentry>
2844 <term><literal>C_OBJS</literal>
2845 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
2846 </term>
2847 <listitem>
2848 <para>Object files derived from
2849 <literal>C_SRCS</literal>.</para>
2850 </listitem>
2851 </varlistentry>
2852
2853 <varlistentry>
2854 <term><literal>SCRIPT_SRCS</literal>
2855 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
2856 </term>
2857 <listitem>
2858 <para>All script source files found
2859 (<literal>.lprl</literal> files).</para>
2860 </listitem>
2861 </varlistentry>
2862
2863 <varlistentry>
2864 <term><literal>SCRIPT_OBJS</literal>
2865 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
2866 </term>
2867 <listitem>
2868 <para><quote>object</quote> files derived from
2869 <literal>SCRIPT_SRCS</literal>
2870 (<literal>.prl</literal> files).</para>
2871 </listitem>
2872 </varlistentry>
2873
2874 <varlistentry>
2875 <term><literal>HSC_SRCS</literal>
2876 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
2877 </term>
2878 <listitem>
2879 <para>All <literal>hsc2hs</literal> source files
2880 (<literal>.hsc</literal> files).</para>
2881 </listitem>
2882 </varlistentry>
2883
2884 <varlistentry>
2885 <term><literal>HAPPY_SRCS</literal>
2886 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
2887 </term>
2888 <listitem>
2889 <para>All <literal>happy</literal> source files
2890 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
2891 </listitem>
2892 </varlistentry>
2893
2894 <varlistentry>
2895 <term><literal>OBJS</literal>
2896 <indexterm><primary>OBJS</primary></indexterm>
2897 </term>
2898 <listitem>
2899 <para>the concatenation of
2900 <literal>&dollar;(HS_OBJS)</literal>,
2901 <literal>&dollar;(C_OBJS)</literal>, and
2902 <literal>&dollar;(SCRIPT_OBJS)</literal>.</para>
2903 </listitem>
2904 </varlistentry>
2905 </variablelist>
2906
2907 <para>Any or all of these definitions can easily be
2908 overriden by giving new definitions in your
2909 <filename>Makefile</filename>.</para>
2910
2911 <para>What, exactly, does <filename>paths.mk</filename>
2912 consider a <quote>source file</quote> to be? It's based
2913 on the file's suffix (e.g. <filename>.hs</filename>,
2914 <filename>.lhs</filename>, <filename>.c</filename>,
2915 <filename>.hy</filename>, etc), but this is the kind of
2916 detail that changes, so rather than enumerate the source
2917 suffices here the best thing to do is to look in
2918 <filename>paths.mk</filename>.</para>
2919 </listitem>
2920 </varlistentry>
2921
2922 <varlistentry>
2923 <term><filename>opts.mk</filename>
2924 <indexterm><primary>opts.mk</primary></indexterm>
2925 </term>
2926 <listitem>
2927 <para>defines <command>make</command> variables for option
2928 strings to pass to each program. For example, it defines
2929 <constant>HC&lowbar;OPTS</constant><indexterm><primary>HC&lowbar;OPTS</primary></indexterm>,
2930 the option strings to pass to the Haskell compiler. See
2931 <xref linkend="sec-suffix"/>.</para>
2932 </listitem>
2933 </varlistentry>
2934
2935 <varlistentry>
2936 <term><filename>suffix.mk</filename>
2937 <indexterm><primary>suffix.mk</primary></indexterm>
2938 </term>
2939 <listitem>
2940 <para>defines standard pattern rules&mdash;see <xref
2941 linkend="sec-suffix"/>.</para>
2942 </listitem>
2943 </varlistentry>
2944 </variablelist>
2945
2946 <para>Any of the variables and pattern rules defined by the
2947 boilerplate file can easily be overridden in any particular
2948 <filename>Makefile</filename>, because the boilerplate
2949 <literal>include</literal> comes first. Definitions after this
2950 <literal>include</literal> directive simply override the default
2951 ones in <filename>boilerplate.mk</filename>.</para>
2952 </sect2>
2953
2954 <sect2 id="sec-platforms">
2955 <title>Platform settings</title>
2956 <indexterm><primary>Platform settings</primary>
2957 </indexterm>
2958
2959 <para>There are three platforms of interest when building GHC:</para>
2960
2961 <variablelist>
2962 <varlistentry>
2963 <term>The <emphasis>build</emphasis> platform</term>
2964 <listitem>
2965 <para>The platform on which we are doing this build.</para>
2966 </listitem>
2967 </varlistentry>
2968
2969 <varlistentry>
2970 <term>The <emphasis>host</emphasis> platform</term>
2971 <listitem>
2972 <para>The platform on which these binaries will run.</para>
2973 </listitem>
2974 </varlistentry>
2975
2976 <varlistentry>
2977 <term>The <emphasis>target</emphasis> platform</term>
2978 <listitem>
2979 <para>The platform for which this compiler will generate code.</para>
2980 </listitem>
2981 </varlistentry>
2982 </variablelist>
2983
2984 <para>These platforms are set when running the
2985 <literal>configure</literal> script, using the
2986 <option>--build</option>, <option>--host</option>, and
2987 <option>--target</option> options. The <filename>mk/config.mk</filename>
2988 file defines several symbols related to the platform settings (see
2989 <filename>mk/config.mk</filename> for details).</para>
2990
2991 <para>We don't currently support build &amp; host being different, because
2992 the build process creates binaries that are both run during the build,
2993 and also installed.</para>
2994
2995 <para>If host and target are different, then we are building a
2996 cross-compiler. For GHC, this means a compiler
2997 which will generate intermediate .hc files to port to the target
2998 architecture for bootstrapping. The libraries and stage 2 compiler
2999 will be built as HC files for the target system (see <xref
3000 linkend="sec-porting-ghc" /> for details.</para>
3001
3002 <para>More details on when to use BUILD, HOST or TARGET can be found in
3003 the comments in <filename>config.mk</filename>.</para>
3004 </sect2>
3005
3006 <sect2 id="sec-suffix">
3007 <title>Pattern rules and options</title>
3008 <indexterm><primary>Pattern rules</primary></indexterm>
3009
3010 <para>The file
3011 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
3012 defines standard <emphasis>pattern rules</emphasis> that say how
3013 to build one kind of file from another, for example, how to
3014 build a <filename>.o</filename> file from a
3015 <filename>.c</filename> file. (GNU <command>make</command>'s
3016 <emphasis>pattern rules</emphasis> are more powerful and easier
3017 to use than Unix <command>make</command>'s <emphasis>suffix
3018 rules</emphasis>.)</para>
3019
3020 <para>Almost all the rules look something like this:</para>
3021
3022 <programlisting>%.o : %.c
3023 $(RM) $@
3024 $(CC) $(CC_OPTS) -c $&#60; -o $@</programlisting>
3025
3026 <para>Here's how to understand the rule. It says that
3027 <emphasis>something</emphasis><filename>.o</filename> (say
3028 <filename>Foo.o</filename>) can be built from
3029 <emphasis>something</emphasis><filename>.c</filename>
3030 (<filename>Foo.c</filename>), by invoking the C compiler (path
3031 name held in <constant>&dollar;(CC)</constant>), passing to it
3032 the options <constant>&dollar;(CC&lowbar;OPTS)</constant> and
3033 the rule's dependent file of the rule
3034 <literal>&dollar;&lt;</literal> (<filename>Foo.c</filename> in
3035 this case), and putting the result in the rule's target
3036 <literal>&dollar;@</literal> (<filename>Foo.o</filename> in this
3037 case).</para>
3038
3039 <para>Every program is held in a <command>make</command>
3040 variable defined in <filename>mk/config.mk</filename>&mdash;look
3041 in <filename>mk/config.mk</filename> for the complete list. One
3042 important one is the Haskell compiler, which is called
3043 <constant>&dollar;(HC)</constant>.</para>
3044
3045 <para>Every program's options are are held in a
3046 <command>make</command> variables called
3047 <constant>&lt;prog&gt;&lowbar;OPTS</constant>. the
3048 <constant>&lt;prog&gt;&lowbar;OPTS</constant> variables are
3049 defined in <filename>mk/opts.mk</filename>. Almost all of them
3050 are defined like this:</para>
3051
3052 <programlisting>CC_OPTS = \
3053 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
3054
3055 <para>The four variables from which
3056 <constant>CC&lowbar;OPTS</constant> is built have the following
3057 meaning:</para>
3058
3059 <variablelist>
3060 <varlistentry>
3061 <term><constant>SRC&lowbar;CC&lowbar;OPTS</constant><indexterm><primary>SRC&lowbar;CC&lowbar;OPTS</primary></indexterm>:</term>
3062 <listitem>
3063 <para>options passed to all C compilations.</para>
3064 </listitem>
3065 </varlistentry>
3066
3067 <varlistentry>
3068 <term><constant>WAY&lowbar;&lt;way&gt;&lowbar;CC&lowbar;OPTS</constant>:</term>
3069 <listitem>
3070 <para>options passed to C compilations for way
3071 <literal>&lt;way&gt;</literal>. For example,
3072 <constant>WAY&lowbar;mp&lowbar;CC&lowbar;OPTS</constant>
3073 gives options to pass to the C compiler when compiling way
3074 <literal>mp</literal>. The variable
3075 <constant>WAY&lowbar;CC&lowbar;OPTS</constant> holds
3076 options to pass to the C compiler when compiling the
3077 standard way. (<xref linkend="sec-ways"/> dicusses
3078 multi-way compilation.)</para>
3079 </listitem>
3080 </varlistentry>
3081
3082 <varlistentry>
3083 <term><constant>&lt;module&gt;&lowbar;CC&lowbar;OPTS</constant>:</term>
3084 <listitem>
3085 <para>options to pass to the C compiler that are specific
3086 to module <literal>&lt;module&gt;</literal>. For example,
3087 <constant>SMap&lowbar;CC&lowbar;OPTS</constant> gives the
3088 specific options to pass to the C compiler when compiling
3089 <filename>SMap.c</filename>.</para>
3090 </listitem>
3091 </varlistentry>
3092
3093 <varlistentry>
3094 <term><constant>EXTRA&lowbar;CC&lowbar;OPTS</constant><indexterm><primary>EXTRA&lowbar;CC&lowbar;OPTS</primary></indexterm>:</term>
3095 <listitem>
3096 <para>extra options to pass to all C compilations. This
3097 is intended for command line use, thus:</para>
3098
3099 <screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
3100 </listitem>
3101 </varlistentry>
3102 </variablelist>
3103 </sect2>
3104
3105 <sect2 id="sec-targets">
3106 <title>The main <filename>mk/target.mk</filename> file</title>
3107 <indexterm><primary>target.mk</primary></indexterm>
3108
3109 <para><filename>target.mk</filename> contains canned rules for
3110 all the standard targets described in <xref
3111 linkend="sec-standard-targets"/>. It is complicated by the fact
3112 that you don't want all of these rules to be active in every
3113 <filename>Makefile</filename>. Rather than have a plethora of
3114 tiny files which you can include selectively, there is a single
3115 file, <filename>target.mk</filename>, which selectively includes
3116 rules based on whether you have defined certain variables in
3117 your <filename>Makefile</filename>. This section explains what
3118 rules you get, what variables control them, and what the rules
3119 do. Hopefully, you will also get enough of an idea of what is
3120 supposed to happen that you can read and understand any weird
3121 special cases yourself.</para>
3122
3123 <variablelist>
3124 <varlistentry>
3125 <term><constant>HS&lowbar;PROG</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>.</term>
3126 <listitem>
3127 <para>If <constant>HS&lowbar;PROG</constant> is defined,
3128 you get rules with the following targets:</para>
3129
3130 <variablelist>
3131 <varlistentry>
3132 <term><filename>HS&lowbar;PROG</filename><indexterm><primary>HS&lowbar;PROG</primary></indexterm></term>
3133 <listitem>
3134 <para>itself. This rule links
3135 <constant>&dollar;(OBJS)</constant> with the Haskell
3136 runtime system to get an executable called
3137 <constant>&dollar;(HS&lowbar;PROG)</constant>.</para>
3138 </listitem>
3139 </varlistentry>
3140
3141 <varlistentry>
3142 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
3143 <listitem>
3144 <para>installs
3145 <constant>&dollar;(HS&lowbar;PROG)</constant> in
3146 <constant>&dollar;(bindir)</constant>.</para>
3147 </listitem>
3148 </varlistentry>
3149 </variablelist>
3150
3151 </listitem>
3152 </varlistentry>
3153
3154 <varlistentry>
3155 <term><constant>C&lowbar;PROG</constant><indexterm><primary>C&lowbar;PROG</primary></indexterm></term>
3156 <listitem>
3157 <para>is similar to <constant>HS&lowbar;PROG</constant>,
3158 except that the link step links
3159 <constant>&dollar;(C&lowbar;OBJS)</constant> with the C
3160 runtime system.</para>
3161 </listitem>
3162 </varlistentry>
3163
3164 <varlistentry>
3165 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
3166 <listitem>
3167 <para>is similar to <constant>HS&lowbar;PROG</constant>,
3168 except that it links
3169 <constant>&dollar;(LIB&lowbar;OBJS)</constant> to make the
3170 library archive <constant>&dollar;(LIBRARY)</constant>,
3171 and <literal>install</literal> installs it in
3172 <constant>&dollar;(libdir)</constant>.</para>
3173 </listitem>
3174 </varlistentry>
3175
3176 <varlistentry>
3177 <term><constant>LIB&lowbar;DATA</constant><indexterm><primary>LIB&lowbar;DATA</primary></indexterm></term>
3178 <listitem>
3179 <para>&hellip;</para>
3180 </listitem>
3181 </varlistentry>
3182
3183 <varlistentry>
3184 <term><constant>LIB&lowbar;EXEC</constant><indexterm><primary>LIB&lowbar;EXEC</primary></indexterm></term>
3185 <listitem>
3186 <para>&hellip;</para>
3187 </listitem>
3188 </varlistentry>
3189
3190 <varlistentry>
3191 <term><constant>HS&lowbar;SRCS</constant><indexterm><primary>HS&lowbar;SRCS</primary></indexterm>, <constant>C&lowbar;SRCS</constant><indexterm><primary>C&lowbar;SRCS</primary></indexterm>.</term>
3192 <listitem>
3193 <para>If <constant>HS&lowbar;SRCS</constant> is defined
3194 and non-empty, a rule for the target
3195 <literal>depend</literal> is included, which generates
3196 dependency information for Haskell programs. Similarly
3197 for <constant>C&lowbar;SRCS</constant>.</para>
3198 </listitem>
3199 </varlistentry>
3200 </variablelist>
3201
3202 <para>All of these rules are &ldquo;double-colon&rdquo; rules,
3203 thus</para>
3204
3205 <programlisting>install :: $(HS_PROG)
3206 ...how to install it...</programlisting>
3207
3208 <para>GNU <command>make</command> treats double-colon rules as
3209 separate entities. If there are several double-colon rules for
3210 the same target it takes each in turn and fires it if its
3211 dependencies say to do so. This means that you can, for
3212 example, define both <constant>HS&lowbar;PROG</constant> and
3213 <constant>LIBRARY</constant>, which will generate two rules for
3214 <literal>install</literal>. When you type <command>gmake
3215 install</command> both rules will be fired, and both the program
3216 and the library will be installed, just as you wanted.</para>
3217 </sect2>
3218
3219 <sect2 id="sec-subdirs">
3220 <title>Recursion</title>
3221 <indexterm><primary>recursion, in makefiles</primary></indexterm>
3222 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
3223
3224 <para>In leaf <filename>Makefile</filename>s the variable
3225 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
3226 is undefined. In non-leaf <filename>Makefile</filename>s,
3227 <constant>SUBDIRS</constant> is set to the list of
3228 sub-directories that contain subordinate
3229 <filename>Makefile</filename>s. <emphasis>It is up to you to
3230 set <constant>SUBDIRS</constant> in the
3231 <filename>Makefile</filename>.</emphasis> There is no automation
3232 here&mdash;<constant>SUBDIRS</constant> is too important to
3233 automate.</para>
3234
3235 <para>When <constant>SUBDIRS</constant> is defined,
3236 <filename>target.mk</filename> includes a rather neat rule for
3237 the standard targets (<xref linkend="sec-standard-targets"/> that
3238 simply invokes <command>make</command> recursively in each of
3239 the sub-directories.</para>
3240
3241 <para><emphasis>These recursive invocations are guaranteed to
3242 occur in the order in which the list of directories is specified
3243 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
3244 be important. For example, when you say <command>gmake
3245 boot</command> it can be important that the recursive invocation
3246 of <command>make boot</command> is done in one sub-directory
3247 (the include files, say) before another (the source files).
3248 Generally, put the most independent sub-directory first, and the
3249 most dependent last.</para>
3250 </sect2>
3251
3252 <sect2 id="sec-ways">
3253 <title>Way management</title>
3254 <indexterm><primary>way management</primary></indexterm>
3255
3256 <para>We sometimes want to build essentially the same system in
3257 several different &ldquo;ways&rdquo;. For example, we want to build GHC's
3258 <literal>Prelude</literal> libraries with and without profiling,
3259 so that there is an appropriately-built library archive to link
3260 with when the user compiles his program. It would be possible
3261 to have a completely separate build tree for each such &ldquo;way&rdquo;,
3262 but it would be horribly bureaucratic, especially since often
3263 only parts of the build tree need to be constructed in multiple
3264 ways.</para>
3265
3266 <para>Instead, the
3267 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
3268 contains some clever magic to allow you to build several
3269 versions of a system; and to control locally how many versions
3270 are built and how they differ. This section explains the
3271 magic.</para>
3272
3273 <para>The files for a particular way are distinguished by
3274 munging the suffix. The <quote>normal way</quote> is always
3275 built, and its files have the standard suffices
3276 <filename>.o</filename>, <filename>.hi</filename>, and so on.
3277 In addition, you can build one or more extra ways, each
3278 distinguished by a <emphasis>way tag</emphasis>. The object
3279 files and interface files for one of these extra ways are
3280 distinguished by their suffix. For example, way
3281 <literal>mp</literal> has files
3282 <filename>.mp&lowbar;o</filename> and
3283 <filename>.mp&lowbar;hi</filename>. Library archives have their
3284 way tag the other side of the dot, for boring reasons; thus,
3285 <filename>libHS&lowbar;mp.a</filename>.</para>
3286
3287 <para>A <command>make</command> variable called
3288 <constant>way</constant> holds the current way tag.
3289 <emphasis><constant>way</constant> is only ever set on the
3290 command line of <command>gmake</command></emphasis> (usually in
3291 a recursive invocation of <command>gmake</command> by the
3292 system). It is never set inside a
3293 <filename>Makefile</filename>. So it is a global constant for
3294 any one invocation of <command>gmake</command>. Two other
3295 <command>make</command> variables,
3296 <constant>way&lowbar;</constant> and
3297 <constant>&lowbar;way</constant> are immediately derived from
3298 <constant>&dollar;(way)</constant> and never altered. If
3299 <constant>way</constant> is not set, then neither are
3300 <constant>way&lowbar;</constant> and
3301 <constant>&lowbar;way</constant>, and the invocation of
3302 <command>make</command> will build the <quote>normal
3303 way</quote>. If <constant>way</constant> is set, then the other
3304 two variables are set in sympathy. For example, if
3305 <constant>&dollar;(way)</constant> is &ldquo;<literal>mp</literal>&rdquo;,
3306 then <constant>way&lowbar;</constant> is set to
3307 &ldquo;<literal>mp&lowbar;</literal>&rdquo; and
3308 <constant>&lowbar;way</constant> is set to
3309 &ldquo;<literal>&lowbar;mp</literal>&rdquo;. These three variables are
3310 then used when constructing file names.</para>
3311
3312 <para>So how does <command>make</command> ever get recursively
3313 invoked with <constant>way</constant> set? There are two ways
3314 in which this happens:</para>
3315
3316 <itemizedlist>
3317 <listitem>
3318 <para>For some (but not all) of the standard targets, when
3319 in a leaf sub-directory, <command>make</command> is
3320 recursively invoked for each way tag in
3321 <constant>&dollar;(WAYS)</constant>. You set
3322 <constant>WAYS</constant> in the
3323 <filename>Makefile</filename> to the list of way tags you
3324 want these targets built for. The mechanism here is very
3325 much like the recursive invocation of
3326 <command>make</command> in sub-directories (<xref
3327 linkend="sec-subdirs"/>). It is up to you to set
3328 <constant>WAYS</constant> in your
3329 <filename>Makefile</filename>; this is how you control what
3330 ways will get built.</para>
3331 </listitem>
3332
3333 <listitem>
3334 <para>For a useful collection of targets (such as
3335 <filename>libHS&lowbar;mp.a</filename>,
3336 <filename>Foo.mp&lowbar;o</filename>) there is a rule which
3337 recursively invokes <command>make</command> to make the
3338 specified target, setting the <constant>way</constant>
3339 variable. So if you say <command>gmake
3340 Foo.mp&lowbar;o</command> you should see a recursive
3341 invocation <command>gmake Foo.mp&lowbar;o way=mp</command>,
3342 and <emphasis>in this recursive invocation the pattern rule
3343 for compiling a Haskell file into a <filename>.o</filename>
3344 file will match</emphasis>. The key pattern rules (in
3345 <filename>suffix.mk</filename>) look like this:
3346
3347 <programlisting>%.$(way_)o : %.lhs
3348 $(HC) $(HC_OPTS) $&#60; -o $@</programlisting>
3349
3350 Neat, eh?</para>
3351 </listitem>
3352
3353 <listitem>
3354 <para>You can invoke <command>make</command> with a
3355 particular <literal>way</literal> setting yourself, in order
3356 to build files related to a particular
3357 <literal>way</literal> in the current directory. eg.
3358
3359 <screen>$ make way=p</screen>
3360
3361 will build files for the profiling way only in the current
3362 directory. </para>
3363 </listitem>
3364 </itemizedlist>
3365 </sect2>
3366
3367 <sect2>
3368 <title>When the canned rule isn't right</title>
3369
3370 <para>Sometimes the canned rule just doesn't do the right thing.
3371 For example, in the <literal>nofib</literal> suite we want the
3372 link step to print out timing information. The thing to do here
3373 is <emphasis>not</emphasis> to define
3374 <constant>HS&lowbar;PROG</constant> or
3375 <constant>C&lowbar;PROG</constant>, and instead define a special
3376 purpose rule in your own <filename>Makefile</filename>. By
3377 using different variable names you will avoid the canned rules
3378 being included, and conflicting with yours.</para>
3379 </sect2>
3380 </sect1>
3381
3382 <sect1 id="building-docs">
3383 <title>Building the documentation</title>
3384
3385 <sect2 id="pre-supposed-doc-tools">
3386 <title>Tools for building the Documentation</title>
3387
3388 <para>The following additional tools are required if you want to
3389 format the documentation that comes with the
3390 <literal>fptools</literal> projects:</para>
3391
3392 <variablelist>
3393 <varlistentry>
3394 <term>DocBook
3395 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
3396 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
3397 </term>
3398 <listitem>
3399 <para>Much of our documentation is written in DocBook XML, instructions
3400 on installing and configuring the DocBook tools are below.</para>
3401 </listitem>
3402 </varlistentry>
3403
3404 <varlistentry>
3405 <term>TeX
3406 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
3407 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
3408 </term>
3409 <listitem>
3410 <para>A decent TeX distribution is required if you want to
3411 produce printable documentation. We recomment teTeX,
3412 which includes just about everything you need.</para>
3413 </listitem>
3414 </varlistentry>
3415
3416 <varlistentry>
3417 <term>Haddock
3418 <indexterm><primary>Haddock</primary></indexterm>
3419 </term>
3420 <listitem>
3421 <para>Haddock is a Haskell documentation tool that we use
3422 for automatically generating documentation from the
3423 library source code. It is an <literal>fptools</literal>
3424 project in itself. To build documentation for the
3425 libraries (<literal>fptools/libraries</literal>) you
3426 should check out and build Haddock in
3427 <literal>fptools/haddock</literal>. Haddock requires GHC
3428 to build.</para>
3429 </listitem>
3430 </varlistentry>
3431 </variablelist>
3432 </sect2>
3433
3434 <sect2>
3435 <title>Installing the DocBook tools</title>
3436
3437 <sect3>
3438 <title>Installing the DocBook tools on Linux</title>
3439
3440 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
3441 you probably have working DocBook tools already installed. The
3442 configure script should detect your setup and you're away.</para>
3443
3444 <para>If you don't have DocBook tools installed, and you are
3445 using a system that can handle RPM packages, you can use <ulink
3446 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
3447 packages for your system. Search for the packages
3448 <literal>docbook-dtd</literal>,
3449 <literal>docbook-xsl-stylesheets</literal>,
3450 <literal>libxslt</literal>,
3451 <literal>libxml2</literal>,
3452 <literal>fop</literal>,
3453 <literal>xmltex</literal>, and
3454 <literal>dvips</literal>.</para>
3455 </sect3>
3456
3457 <sect3>
3458 <title>Installing DocBook on FreeBSD</title>
3459
3460 <para>On FreeBSD systems, the easiest way to get DocBook up
3461 and running is to install it from the ports tree or a
3462 pre-compiled package (packages are available from your local
3463 FreeBSD mirror site).</para>
3464
3465 <para>To use the ports tree, do this:
3466 <screen>$ cd /usr/ports/textproc/docproj
3467 $ make install</screen>
3468 This installs the FreeBSD documentation project tools, which
3469 includes everything needed to format the GHC
3470 documentation.</para>
3471 </sect3>
3472
3473 <sect3>
3474 <title>Installing from binaries on Windows</title>
3475
3476 <para>Probably the fastest route to a working DocBook environment on
3477 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
3478 with the complete <literal>Doc</literal> category. If you are using
3479 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
3480 have to help <command>configure</command> a little bit: Set the
3481 environment variables <envar>XmllintCmd</envar> and
3482 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
3483 <command>xmllint</command> and <command>xsltproc</command>,
3484 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
3485 of the directory where the XSL stylesheets are installed,
3486 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
3487 </para>
3488
3489 <para>If you want to build HTML Help, you have to install the
3490 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
3491 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
3492 </sect3>
3493
3494 </sect2>
3495
3496 <sect2>
3497 <title>Configuring the DocBook tools</title>
3498
3499 <para>Once the DocBook tools are installed, the configure script
3500 will detect them and set up the build system accordingly. If you
3501 have a system that isn't supported, let us know, and we'll try
3502 to help.</para>
3503 </sect2>
3504
3505 <sect2>
3506 <title>Building the documentation</title>
3507
3508 <para>To build documentation in a certain format, you can
3509 say, for example,</para>
3510
3511 <screen>$ make html</screen>
3512
3513 <para>to build HTML documentation below the current directory.
3514 The available formats are: <literal>dvi</literal>,
3515 <literal>ps</literal>, <literal>pdf</literal>,
3516 <literal>html</literal>, and <literal>rtf</literal>. Note that
3517 not all documentation can be built in all of these formats: HTML
3518 documentation is generally supported everywhere, and DocBook
3519 documentation might support the other formats (depending on what
3520 other tools you have installed).</para>
3521
3522 <para>All of these targets are recursive; that is, saying
3523 <literal>make html</literal> will make HTML docs for all the
3524 documents recursively below the current directory.</para>
3525
3526 <para>Because there are many different formats that the DocBook
3527 documentation can be generated in, you have to select which ones
3528 you want by setting the <literal>XMLDocWays</literal> variable
3529 to a list of them. For example, in
3530 <filename>build.mk</filename> you might have a line:</para>
3531
3532 <screen>XMLDocWays = html ps</screen>
3533
3534 <para>This will cause the documentation to be built in the requested
3535 formats as part of the main build (the default is not to build
3536 any documentation at all).</para>
3537 </sect2>
3538
3539 <sect2>
3540 <title>Installing the documentation</title>
3541
3542 <para>To install the documentation, use:</para>
3543
3544 <screen>$ make install-docs</screen>
3545
3546 <para>This will install the documentation into
3547 <literal>$(datadir)</literal> (which defaults to
3548 <literal>$(prefix)/share</literal>). The exception is HTML
3549 documentation, which goes into
3550 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
3551
3552 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
3553 to a list of formats, the <literal>install-docs</literal> target
3554 won't do anything for DocBook XML documentation.</para>
3555 </sect2>
3556
3557 </sect1>
3558
3559
3560 <sect1 id="sec-porting-ghc">
3561 <title>Porting GHC</title>
3562
3563 <para>This section describes how to port GHC to a currenly
3564 unsupported platform. There are two distinct
3565 possibilities:</para>
3566
3567 <itemizedlist>
3568 <listitem>
3569 <para>The hardware architecture for your system is already
3570 supported by GHC, but you're running an OS that isn't
3571 supported (or perhaps has been supported in the past, but
3572 currently isn't). This is the easiest type of porting job,
3573 but it still requires some careful bootstrapping. Proceed to
3574 <xref linkend="sec-booting-from-hc"/>.</para>
3575 </listitem>
3576
3577 <listitem>
3578 <para>Your system's hardware architecture isn't supported by
3579 GHC. This will be a more difficult port (though by comparison
3580 perhaps not as difficult as porting gcc). Proceed to <xref
3581 linkend="unregisterised-porting"/>.</para>
3582 </listitem>
3583 </itemizedlist>
3584
3585 <sect2 id="sec-booting-from-hc">
3586 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
3587
3588 <indexterm><primary>building GHC from .hc files</primary></indexterm>
3589 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
3590 <indexterm><primary>porting GHC</primary></indexterm>
3591
3592 <para>Bootstrapping GHC on a system without GHC already
3593 installed is achieved by taking the intermediate C files (known
3594 as HC files) from another GHC compilation, compiling them using gcc to
3595 get a working GHC.</para>
3596
3597 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
3598 from C. We recommend using GHC 6.0.1 or
3599 later.</emphasis></para>
3600
3601 <para>HC files are platform-dependent, so you have to get a set
3602 that were generated on <emphasis>the same platform</emphasis>. There
3603 may be some supplied on the GHC download page, otherwise you'll have to
3604 compile some up yourself, or start from
3605 <emphasis>unregisterised</emphasis> HC files - see <xref
3606 linkend="unregisterised-porting"/>.</para>
3607
3608 <para>The following steps should result in a working GHC build
3609 with full libraries:</para>
3610
3611 <itemizedlist>
3612 <listitem>
3613 <para>Unpack the HC files on top of a fresh source tree
3614 (make sure the source tree version matches the version of
3615 the HC files <emphasis>exactly</emphasis>!). This will
3616 place matching <filename>.hc</filename> files next to the
3617 corresponding Haskell source (<filename>.hs</filename> or
3618 <filename>.lhs</filename>) in the compiler subdirectory
3619 <filename>ghc/compiler</filename> and in the libraries
3620 (subdirectories of
3621 <literal>libraries</literal>).</para>
3622 </listitem>
3623
3624 <listitem>
3625 <para>The actual build process is fully automated by the
3626 <filename>hc-build</filename> script located in the
3627 <filename>distrib</filename> directory. If you eventually
3628 want to install GHC into the directory
3629 <replaceable>dir</replaceable>, the following
3630 command will execute the whole build process (it won't
3631 install yet):</para>
3632
3633 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
3634 <indexterm><primary>--hc-build</primary></indexterm>
3635
3636 <para>By default, the installation directory is
3637 <filename>/usr/local</filename>. If that is what you want,
3638 you may omit the argument to <filename>hc-build</filename>.
3639 Generally, any option given to <filename>hc-build</filename>
3640 is passed through to the configuration script
3641 <filename>configure</filename>. If
3642 <filename>hc-build</filename> successfully completes the
3643 build process, you can install the resulting system, as
3644 normal, with</para>
3645
3646 <screen>$ make install</screen>
3647 </listitem>
3648 </itemizedlist>
3649 </sect2>
3650
3651 <sect2 id="unregisterised-porting">
3652 <title>Porting GHC to a new architecture</title>
3653
3654 <para>The first step in porting to a new architecture is to get
3655 an <firstterm>unregisterised</firstterm> build working. An
3656 unregisterised build is one that compiles via vanilla C only.
3657 By contrast, a registerised build uses the following
3658 architecture-specific hacks for speed:</para>
3659
3660 <itemizedlist>
3661 <listitem>
3662 <para>Global register variables: certain abstract machine
3663 <quote>registers</quote> are mapped to real machine
3664 registers, depending on how many machine registers are
3665 available (see
3666 <filename>ghc/includes/MachRegs.h</filename>).</para>
3667 </listitem>
3668
3669 <listitem>
3670 <para>Assembly-mangling: when compiling via C, we feed the
3671 assembly generated by gcc though a Perl script known as the
3672 <firstterm>mangler</firstterm> (see
3673 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
3674 mangler rearranges the assembly to support tail-calls and
3675 various other optimisations.</para>
3676 </listitem>
3677 </itemizedlist>
3678
3679 <para>In an unregisterised build, neither of these hacks are
3680 used &mdash; the idea is that the C code generated by the
3681 compiler should compile using gcc only. The lack of these
3682 optimisations costs about a factor of two in performance, but
3683 since unregisterised compilation is usually just a step on the
3684 way to a full registerised port, we don't mind too much.</para>
3685
3686 <para>Notes on GHC portability in general: we've tried to stick
3687 to writing portable code in most parts of the system, so it
3688 should compile on any POSIXish system with gcc, but in our
3689 experience most systems differ from the standards in one way or
3690 another. Deal with any problems as they arise - if you get
3691 stuck, ask the experts on
3692 <email>glasgow-haskell-users@haskell.org</email>.</para>
3693
3694 <para>Lots of useful information about the innards of GHC is
3695 available in the <ulink
3696 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
3697 Commentary</ulink>, which might be helpful if you run into some
3698 code which needs tweaking for your system.</para>
3699
3700 <sect3>
3701 <title>Cross-compiling to produce an unregisterised GHC</title>
3702
3703 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
3704 later. If you need instructions for an earlier version of GHC, try
3705 to get hold of the version of this document that was current at the
3706 time. It should be available from the appropriate download page on
3707 the <ulink
3708 url="http://www.haskell.org/ghc/">GHC&nbsp;homepage</ulink>.</para>
3709
3710 <para>In this section, we explain how to bootstrap GHC on a
3711 new platform, using unregisterised intermediate C files. We
3712 haven't put a great deal of effort into automating this
3713 process, for two reasons: it is done very rarely, and the
3714 process usually requires human intervention to cope with minor
3715 porting issues anyway.</para>
3716
3717 <para>The following step-by-step instructions should result in
3718 a fully working, albeit unregisterised, GHC. Firstly, you
3719 need a machine that already has a working GHC (we'll call this
3720 the <firstterm>host</firstterm> machine), in order to
3721 cross-compile the intermediate C files that we will use to
3722 bootstrap the compiler on the <firstterm>target</firstterm>
3723 machine.</para>
3724
3725 <itemizedlist>
3726 <listitem>
3727 <para>On the target machine:</para>
3728
3729 <itemizedlist>
3730 <listitem>
3731 <para>Unpack a source tree (preferably a released
3732 version). We will call the path to the root of this
3733 tree <replaceable>T</replaceable>.</para>
3734 </listitem>
3735
3736 <listitem>
3737 <screen>$ cd <replaceable>T</replaceable>
3738 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
3739
3740 <para>You might need to update
3741 <filename>configure.in</filename> to recognise the new
3742 architecture, and re-generate
3743 <filename>configure</filename> with
3744 <literal>autoreconf</literal>.</para>
3745 </listitem>
3746
3747 <listitem>
3748 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
3749 $ make</screen>
3750 </listitem>
3751 </itemizedlist>
3752 </listitem>
3753
3754 <listitem>
3755 <para>On the host machine:</para>
3756
3757 <itemizedlist>
3758 <listitem>
3759 <para>Unpack a source tree (same released version). Call
3760 this directory <replaceable>H</replaceable>.</para>
3761 </listitem>
3762
3763 <listitem>
3764 <screen>$ cd <replaceable>H</replaceable>
3765 $ ./configure</screen>
3766 </listitem>
3767
3768 <listitem>
3769 <para>Create
3770 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
3771 with the following contents:</para>
3772
3773 <programlisting>GhcUnregisterised = YES
3774 GhcLibHcOpts = -O -fvia-C -keep-hc-files
3775 GhcRtsHcOpts = -keep-hc-files
3776 GhcLibWays =
3777 SplitObjs = NO
3778 GhcWithNativeCodeGen = NO
3779 GhcWithInterpreter = NO
3780 GhcStage1HcOpts = -O
3781 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
3782 SRC_HC_OPTS += -H32m
3783 GhcBootLibs = YES</programlisting>
3784 </listitem>
3785
3786 <listitem>
3787 <para>Edit
3788 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
3789 <itemizedlist>
3790 <listitem>
3791 <para>change <literal>TARGETPLATFORM</literal>
3792 appropriately, and set the variables involving
3793 <literal>TARGET</literal> to the correct values for
3794 the target platform. This step is necessary because
3795 currently <literal>configure</literal> doesn't cope
3796 with specifying different values for the
3797 <literal>--host</literal> and
3798 <literal>--target</literal> flags.</para>
3799 </listitem>
3800 <listitem>
3801 <para>copy <literal>LeadingUnderscore</literal>
3802 setting from target.</para>
3803 </listitem>
3804 </itemizedlist>
3805 </listitem>
3806
3807 <listitem>
3808 <para>Copy
3809 <filename><replaceable>T</replaceable>/ghc/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/ghc/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/ghc/includes/GHCConstants.h</filename>
3810 to
3811 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
3812 Note that we are building on the host machine, using the
3813 target machine's configuration files. This
3814 is so that the intermediate C files generated here will
3815 be suitable for compiling on the target system.</para>
3816 </listitem>
3817
3818 <listitem>
3819 <para>Touch the generated configuration files, just to make
3820 sure they don't get replaced during the build:</para>
3821 <screen>$ touch <filename><replaceable>H</replaceable></filename>/ghc/includes/{ghcautoconf.h,DerivedConstants.h.GHCConstants.h.mkDerivedConstants.c,mkDerivedConstantsHdr,mkDerivedConstants.o,mkGHCConstants,mkGHCConstants.o}</screen>
3822 </listitem>
3823
3824 <listitem>
3825 <para>Now build the compiler:</para>
3826 <screen>$ cd <replaceable>H</replaceable>/glafp-utils &amp;&amp; make boot &amp;&amp; make
3827 $ cd <replaceable>H</replaceable>/ghc &amp;&amp; make boot &amp;&amp; make</screen>
3828 <para>Don't worry if the build falls over in the RTS, we
3829 don't need the RTS yet.</para>
3830 </listitem>
3831
3832 <listitem>
3833 <screen>$ cd <replaceable>H</replaceable>/libraries
3834 $ make boot &amp;&amp; make</screen>
3835 </listitem>
3836
3837 <listitem>
3838 <screen>$ cd <replaceable>H</replaceable>/ghc/compiler
3839 $ make boot stage=2 &amp;&amp; make stage=2</screen>
3840 </listitem>
3841
3842 <listitem>
3843 <screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
3844 $ make clean
3845 $ rm .depend
3846 $ make boot UseStage1=YES
3847 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
3848 $ cd <replaceable>H</replaceable>/ghc/utils
3849 $ make clean
3850 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
3851 </listitem>
3852
3853 <listitem>
3854 <screen>$ cd <replaceable>H</replaceable>
3855 $ make hc-file-bundle Project=Ghc</screen>
3856 </listitem>
3857
3858 <listitem>
3859 <para>copy
3860 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
3861 to <filename><replaceable>T</replaceable>/..</filename>.</para>
3862 </listitem>
3863 </itemizedlist>
3864 </listitem>
3865
3866 <listitem>
3867 <para>On the target machine:</para>
3868
3869 <para>At this stage we simply need to bootstrap a compiler
3870 from the intermediate C files we generated above. The
3871 process of bootstrapping from C files is automated by the
3872 script in <literal>distrib/hc-build</literal>, and is
3873 described in <xref linkend="sec-booting-from-hc"/>.</para>
3874
3875 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
3876
3877 <para>However, since this is a bootstrap on a new machine,
3878 the automated process might not run to completion the
3879 first time. For that reason, you might want to treat the
3880 <literal>hc-build</literal> script as a list of
3881 instructions to follow, rather than as a fully automated
3882 script. This way you'll be able to restart the process
3883 part-way through if you need to fix anything on the
3884 way.</para>
3885
3886 <para>Don't bother with running
3887 <literal>make&nbsp;install</literal> in the newly
3888 bootstrapped tree; just use the compiler in that tree to
3889 build a fresh compiler from scratch, this time without
3890 booting from C files. Before doing this, you might want
3891 to check that the bootstrapped compiler is generating
3892 working binaries:</para>
3893
3894 <screen>$ cat >hello.hs
3895 main = putStrLn "Hello World!\n"
3896 ^D
3897 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
3898 $ ./hello
3899 Hello World!</screen>
3900
3901 <para>Once you have the unregisterised compiler up and
3902 running, you can use it to start a registerised port. The
3903 following sections describe the various parts of the
3904 system that will need architecture-specific tweaks in
3905 order to get a registerised build going.</para>
3906
3907 </listitem>
3908 </itemizedlist>
3909 </sect3>
3910
3911 <sect3>
3912 <title>Porting the RTS</title>
3913
3914 <para>The following files need architecture-specific code for a
3915 registerised build:</para>
3916
3917 <variablelist>
3918 <varlistentry>
3919 <term><filename>ghc/includes/MachRegs.h</filename>
3920 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
3921 </term>
3922 <listitem>
3923 <para>Defines the STG-register to machine-register
3924 mapping. You need to know your platform's C calling
3925 convention, and which registers are generally available
3926 for mapping to global register variables. There are
3927 plenty of useful comments in this file.</para>
3928 </listitem>
3929 </varlistentry>
3930 <varlistentry>
3931 <term><filename>ghc/includes/TailCalls.h</filename>
3932 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
3933 </term>
3934 <listitem>
3935 <para>Macros that cooperate with the mangler (see <xref
3936 linkend="sec-mangler"/>) to make proper tail-calls
3937 work.</para>
3938 </listitem>
3939 </varlistentry>
3940 <varlistentry>
3941 <term><filename>ghc/rts/Adjustor.c</filename>
3942 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
3943 </term>
3944 <listitem>
3945 <para>Support for
3946 <literal>foreign&nbsp;import&nbsp;"wrapper"</literal>
3947 (aka
3948 <literal>foreign&nbsp;export&nbsp;dynamic</literal>).
3949 Not essential for getting GHC bootstrapped, so this file
3950 can be deferred until later if necessary.</para>
3951 </listitem>
3952 </varlistentry>
3953 <varlistentry>
3954 <term><filename>ghc/rts/StgCRun.c</filename>
3955 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
3956 </term>
3957 <listitem>
3958 <para>The little assembly layer between the C world and
3959 the Haskell world. See the comments and code for the
3960 other architectures in this file for pointers.</para>
3961 </listitem>
3962 </varlistentry>
3963 <varlistentry>
3964 <term><filename>ghc/rts/MBlock.h</filename>
3965 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
3966 </term>
3967 <term><filename>ghc/rts/MBlock.c</filename>
3968 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
3969 </term>
3970 <listitem>
3971 <para>These files are really OS-specific rather than
3972 architecture-specific. In <filename>MBlock.h</filename>
3973 is specified the absolute location at which the RTS
3974 should try to allocate memory on your platform (try to
3975 find an area which doesn't conflict with code or dynamic
3976 libraries). In <filename>Mblock.c</filename> you might
3977 need to tweak the call to <literal>mmap()</literal> for
3978 your OS.</para>
3979 </listitem>
3980 </varlistentry>
3981 </variablelist>
3982 </sect3>
3983
3984 <sect3 id="sec-mangler">
3985 <title>The mangler</title>
3986
3987 <para>The mangler is an evil Perl-script
3988 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
3989 rearranges the assembly code output from gcc to do two main
3990 things:</para>
3991
3992 <itemizedlist>
3993 <listitem>
3994 <para>Remove function prologues and epilogues, and all
3995 movement of the C stack pointer. This is to support
3996 tail-calls: every code block in Haskell code ends in an
3997 explicit jump, so we don't want the C-stack overflowing
3998 while we're jumping around between code blocks.</para>
3999 </listitem>
4000 <listitem>
4001 <para>Move the <firstterm>info table</firstterm> for a
4002 closure next to the entry code for that closure. In
4003 unregisterised code, info tables contain a pointer to the
4004 entry code, but in registerised compilation we arrange
4005 that the info table is shoved right up against the entry
4006 code, and addressed backwards from the entry code pointer
4007 (this saves a word in the info table and an extra
4008 indirection when jumping to the closure entry
4009 code).</para>
4010 </listitem>
4011 </itemizedlist>
4012
4013 <para>The mangler is abstracted to a certain extent over some
4014 architecture-specific things such as the particular assembler
4015 directives used to herald symbols. Take a look at the
4016 definitions for other architectures and use these as a
4017 starting point.</para>
4018 </sect3>
4019
4020 <sect3>
4021 <title>The splitter</title>
4022
4023 <para>The splitter is another evil Perl script
4024 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
4025 cooperates with the mangler to support object splitting.
4026 Object splitting is what happens when the
4027 <option>-split-objs</option> option is passed to GHC: the
4028 object file is split into many smaller objects. This feature
4029 is used when building libraries, so that a program statically
4030 linked against the library will pull in less of the
4031 library.</para>
4032
4033 <para>The splitter has some platform-specific stuff; take a
4034 look and tweak it for your system.</para>
4035 </sect3>
4036
4037 <sect3>
4038 <title>The native code generator</title>
4039
4040 <para>The native code generator isn't essential to getting a
4041 registerised build going, but it's a desirable thing to have
4042 because it can cut compilation times in half. The native code
4043 generator is described in some detail in the <ulink
4044 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc