building.xml 193 KB
Newer Older
1
2
3
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
rrt's avatar
rrt committed
4

5
<article id="building-guide">
rrt's avatar
rrt committed
6

7
<articleinfo>
rrt's avatar
rrt committed
8

9
10
11
<title>Building the Glasgow Functional Programming Tools Suite</title>
<author><othername>The GHC Team</othername></author>
<address><email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</email></address>
rrt's avatar
rrt committed
12

13
14
15
16
17
18
    <abstract>
      <para>The Glasgow fptools suite is a collection of Functional
      Programming related tools, including the Glasgow Haskell
      Compiler (GHC).  The source code for the whole suite is kept in
      a single CVS repository and shares a common build and
      installation system.</para>
rrt's avatar
rrt committed
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>
rrt's avatar
rrt committed
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>
rrt's avatar
rrt committed
29

30
</articleinfo>
rrt's avatar
rrt committed
31
32


33
  <sect1 id="sec-getting">
34
35
36
37
    <title>Getting the sources</title>
    
    <para>You can get your hands on the <literal>fptools</literal>
    in two ways:</para>
rrt's avatar
rrt committed
38

39
    <variablelist>
40

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
      <varlistentry>
	<term><indexterm><primary>Source
	distributions</primary></indexterm>Source distributions</term>
	<listitem>
	  <para>You have a supported platform, but (a)&nbsp;you like
          the warm fuzzy feeling of compiling things yourself;
          (b)&nbsp;you want to build something ``extra&rdquo;&mdash;e.g., a
          set of libraries with strictness-analysis turned off; or
          (c)&nbsp;you want to hack on GHC yourself.</para>

	  <para>A source distribution contains complete sources for
          one or more projects in the <literal>fptools</literal>
          suite.  Not only that, but the more awkward
          machine-independent steps are done for you.  For example, if
          you don't have
          <command>happy</command><indexterm><primary>happy</primary></indexterm>
          you'll find it convenient that the source distribution
          contains the result of running <command>happy</command> on
          the parser specifications.  If you don't want to alter the
          parser then this saves you having to find and install
          <command>happy</command>. You will still need a working
62
          version of GHC (version 5.x or later) on your machine in
63
64
65
          order to compile (most of) the sources, however.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
66

67
      <varlistentry>
68
	<term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
69
70
71
72
73
	<listitem>
	  <para>We make releases infrequently.  If you want more
          up-to-the minute (but less tested) source code then you need
          to get access to our CVS repository.</para>

74
	  <para>All the <literal>fptools</literal> source code is held
75
76
77
78
79
80
81
82
83
84
85
          in a CVS repository. CVS is a pretty good source-code
          control system, and best of all it works over the
          network.</para>

	  <para>The repository holds source code only. It holds no
          mechanically generated files at all.  So if you check out a
          source tree from CVS you will need to install every utility
          so that you can build all the derived files from
          scratch.</para>

	  <para>More information about our CVS repository can be found
86
          in <xref linkend="sec-cvs"/>.</para>
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
	</listitem>
      </varlistentry>
    </variablelist>

    <para>If you are going to do any building from sources (either
    from a source distribution or the CVS repository) then you need to
    read all of this manual in detail.</para>
  </sect1>

  <sect1 id="sec-cvs">
    <title>Using the CVS repository</title>

    <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
    sources for various software projects. CVS lets several people
    work on the same software at the same time, allowing changes to be
    checked in incrementally. </para>

    <para>This section is a set of guidelines for how to use our CVS
    repository, and will probably evolve in time. The main thing to
    remember is that most mistakes can be undone, but if there's
    anything you're not sure about feel free to bug the local CVS
    meister (namely Jeff Lewis
109
    <email>jlewis@galois.com</email>). </para>
110
111
112
113
114

    <sect2 id="cvs-access">
      <title>Getting access to the CVS Repository</title>

      <para>You can access the repository in one of two ways:
115
116
      read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
      linkend="cvs-read-write"/>).</para>
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

      <sect3 id="cvs-read-only">
	<title>Remote Read-only CVS Access</title>

	<para>Read-only access is available to anyone - there's no
        need to ask us first.  With read-only CVS access you can do
        anything except commit changes to the repository.  You can
        make changes to your local tree, and still use CVS's merge
        facility to keep your tree up to date, and you can generate
        patches using 'cvs diff' in order to send to us for
        inclusion. </para>

	<para>To get read-only access to the repository:</para>

	<orderedlist>
	  <listitem>
	    <para>Make sure that <application>cvs</application> is
            installed on your machine.</para>
	  </listitem>
	  <listitem>
	    <para>Set your <literal>$CVSROOT</literal> environment variable to
            <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
139
140
141
	    <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
	      have any trailing spaces on that line, otherwise CVS will respond with 
	      a perplexing message like
142
	      <screen>/cvs : no such repository</screen></para>
143
144
145
	  </listitem>
	  <listitem>
            <para>Run the command</para>
146
<screen>$ cvs login</screen>
147
148
149
150
151
152
153
	    <para>The password is simply <literal>cvs</literal>.  This
            sets up a file in your home directory called
            <literal>.cvspass</literal>, which squirrels away the
            dummy password, so you only need to do this step once.</para>
	  </listitem>

	  <listitem>
154
	    <para>Now go to <xref linkend="cvs-first"/>.</para>
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
	  </listitem>
	</orderedlist>
      </sect3>

      <sect3 id="cvs-read-write">
	<title>Remote Read-Write CVS Access</title>

	<para>We generally supply read-write access to folk doing
        serious development on some part of the source tree, when
        going through us would be a pain. If you're developing some
        feature, or think you have the time and inclination to fix
        bugs in our sources, feel free to ask for read-write
        access. There is a certain amount of responsibility that goes
        with commit privileges; we are more likely to grant you access
        if you've demonstrated your competence by sending us patches
        via mail in the past.</para>

	<para>To get remote read-write CVS access, you need to do the
	following steps.</para>

	<orderedlist>
	  <listitem>
	    <para>Make sure that <literal>cvs</literal> and
            <literal>ssh</literal> are both installed on your
            machine.</para>
	  </listitem>

	  <listitem>
	    <para>Generate a DSA private-key/public-key pair, thus:</para>
184
<screen>$ ssh-keygen -d</screen>
185
186
187
188
189
190
191
192
193
194
195
	    <para>(<literal>ssh-keygen</literal> comes with
            <literal>ssh</literal>.)  Running <literal>ssh-keygen
            -d</literal> creates the private and public keys in
            <literal>$HOME/.ssh/id_dsa</literal> and
            <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
            (assuming you accept the standard defaults).</para>

	    <para><literal>ssh-keygen -d</literal> will only work if
            you have Version 2 <literal>ssh</literal> installed; it
            will fail harmlessly otherwise.  If you only have Version
            1 you can instead generate an RSA key pair using plain</para>
196
<screen>$ ssh-keygen</screen>
197
198
199
200
201
202
203
204
205
206

	    <para>Doing so creates the private and public RSA keys in
            <literal>$HOME/.ssh/identity</literal> and
            <literal>$HOME/.ssh/identity.pub</literal>
            respectively.</para>

            <para>[Deprecated.]  Incidentally, you can force a Version
            2 <literal>ssh</literal> to use the Version 1 protocol by
            creating <literal>$HOME/config</literal> with the
            following in it:</para>
207
<programlisting>BatchMode Yes
208

209
210
Host cvs.haskell.org
Protocol 1</programlisting>
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235

	    <para>In both cases, <literal>ssh-keygen</literal> will
            ask for a <firstterm>passphrase</firstterm>.  The
            passphrase is a password that protects your private key.
            In response to the 'Enter passphrase' question, you can
            either:</para>
	    <itemizedlist>
	      <listitem>
		<para>[Recommended.]  Enter a passphrase, which you
                will quote each time you use CVS.
                <literal>ssh-agent</literal> makes this entirely
                un-tiresome.</para>
	      </listitem>
	      <listitem>
		<para>[Deprecated.] Just hit return (i.e. use an empty
                passphrase); then you won't need to quote the
                passphrase when using CVS.  The downside is that
                anyone who can see into your <literal>.ssh</literal>
                directory, and thereby get your private key, can mess
                up the repository.  So you must keep the
                <literal>.ssh</literal> directory with draconian
                no-access permissions.</para>
	      </listitem>
	    </itemizedlist>

236
237

       <para>
238
       <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
239
240
         </para>

241

242
243
244
245
246
	  </listitem>

	  <listitem>
	    <para>Send a message to to the CVS repository
            administrator (currently Jeff Lewis
247
            <email>jeff@galois.com</email>), containing:</para>
248
249
250
251
252
253
254
255
256
257
258
259
260
261
	    <itemizedlist>
	      <listitem>
		<para>Your desired user-name.</para>
	      </listitem>
	      <listitem>
		<para>Your <literal>.ssh/id_dsa.pub</literal> (or
                <literal>.ssh/identity.pub</literal>).</para>
	      </listitem>
	    </itemizedlist>
	    <para>He will set up your account.</para>
	  </listitem>

	  <listitem>
	    <para>Set the following environment variables:</para>
262
	   <itemizedlist>
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
	   <listitem>
	   <para>
	   <constant>$HOME</constant>: points to your home directory.  This is where CVS
	   will look for its <filename>.cvsrc</filename> file.
	   </para>
	   </listitem>

	   <listitem>
	   <para>
	   <constant>$CVS_RSH</constant> to <filename>ssh</filename>
	   </para>
  	   <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
            <literal>ssh</literal> assumes that your CVS client
            understands how to execute shell script
            (&quot;#!&quot;s,really), which is what
            <literal>ssh</literal> is. This may not be the case on
            Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
            <literal>ssh1</literal>.</para>
	   </listitem>
282

283
284
285
286
287
288
289
             <listitem>
		<para><literal>$CVSROOT</literal> to
		<literal>:ext:</literal><replaceable>your-username</replaceable>
                <literal>@cvs.haskell.org:/home/cvs/root</literal>
		where <replaceable>your-username</replaceable> is your user name on
		<literal>cvs.haskell.org</literal>.
		</para>
290
291
	<para>The <literal>CVSROOT</literal> environment variable will
        be recorded in the checked-out tree, so you don't need to set
292
293
294
        this every time. </para>

	     </listitem>
295

296
297
298
299
300
301
302
303
304
305
	<listitem>
	<para>
	<constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename> 
	if you want to use an Emacs buffer for typing in those long commit messages.
	</para>
	</listitem>

	<listitem>
	<para>
	<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
308
309
	</para>
	</listitem>

310
       </itemizedlist>
311
312
313


	  </listitem>
314
315

	  <listitem>
316
317
318
319
	  <para>
	  Put the following in <filename>$HOME/.cvsrc</filename>:
	  </para>
	  
320
321
322
323
<programlisting>checkout -P
release -d
update -P
diff -u</programlisting>
324
325
326
327
328
329
330
331
332
333
334
335
336
337
	  
	  <para>
	  These are the default options for the specified CVS commands,
	  and represent better defaults than the usual ones.  (Feel
	  free to change them.)
	  </para>
	  
	  <para>
	  [Windows users.]  Filenames starting with <filename>.</filename> were illegal in 
	  the 8.3 DOS filesystem, but that restriction should have
	  been lifted by now (i.e., you're using VFAT or later filesystems.) If
	  you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
	  optional.
	  </para>
338
	  </listitem>
339
340
341

	</orderedlist>

342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370

	<para>[Experts.]  Once your account is set up, you can get
        access from other machines without bothering Jeff, thus:</para>
	<orderedlist>
	  <listitem>
	    <para>Generate a public/private key pair on the new
            machine.</para>
	  </listitem>
	  <listitem>
	    <para>Use ssh to log in to
            <literal>cvs.haskell.org</literal>, from your old
            machine.</para>
	  </listitem>
	  <listitem>
	    <para>Add the public key for the new machine to the file
            <literal>$HOME/ssh/authorized_keys</literal> on
            <literal>cvs.haskell.org</literal>.
            (<literal>authorized_keys2</literal>, I think, for Version
            2 protocol.)</para>
	  </listitem>
	  <listitem>
	    <para>Make sure that the new version of
            <literal>authorized_keys</literal> still has 600 file
            permissions.</para>
	  </listitem>
	</orderedlist>
      </sect3>
    </sect2>

371
372


373
374
375
376
377
378
379
380
381
382
    <sect2 id="cvs-first">
      <title>Checking Out a Source Tree</title>

      <itemizedlist>
	<listitem>
	  <para>Make sure you set your <literal>CVSROOT</literal>
          environment variable according to either of the remote
          methods above. The Approved Way to check out a source tree
          is as follows:</para>

383
<screen>$ cvs checkout fpconfig</screen>
384
385
386
387
388
389

	  <para>At this point you have a new directory called
          <literal>fptools</literal> which contains the basic stuff
          for the fptools suite, including the configuration files and
          some other junk. </para>

390
<para>[Windows users.]  The following messages appear to be harmless:
391
392
<screen>setsockopt IPTOS_LOWDELAY: Invalid argument
setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
393
394
395
396
397
398
</para>


	  <para>You can call the fptools directory whatever you like,
          CVS won't mind: </para>
	  
399
<screen>$ mv fptools <replaceable>directory</replaceable></screen>
400
401
402

	  <para> NB: after you've read the CVS manual you might be
          tempted to try</para>
403
<screen>$ cvs checkout -d <replaceable>directory</replaceable> fpconfig</screen>
404
405
406
407
408

	  <para>instead of checking out <literal>fpconfig</literal>
          and then renaming it.  But this doesn't work, and will
          result in checking out the entire repository instead of just
          the <literal>fpconfig</literal> bit.</para>
409
410
<screen>$ cd <replaceable>directory</replaceable>
$ cvs checkout ghc hslibs libraries</screen>
411
412
413

	  <para>The second command here checks out the relevant
          modules you want to work on. For a GHC build, for instance,
414
415
416
          you need at least the <literal>ghc</literal>,
          <literal>hslibs</literal> and <literal>libraries</literal>
          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
421
          <literal>happy</literal> and/or <literal>Alex</literal>
          installed, you need to check them out as well.</para>
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="cvs-committing">
      <title>Committing Changes</title>

      <para>This is only if you have read-write access to the
      repository. For anoncvs users, CVS will issue a &quot;read-only
      repository&quot; error if you try to commit changes.</para>

      <itemizedlist>
	<listitem>
	  <para>Build the software, if necessary. Unless you're just
          working on documentation, you'll probably want to build the
          software in order to test any changes you make.</para>
	</listitem>

	<listitem>
	  <para>Make changes. Preferably small ones first.</para>
	</listitem>

	<listitem>
	  <para>Test them. You can see exactly what changes you've
          made by using the <literal>cvs diff</literal> command:</para>
447
<screen>$ cvs diff</screen>
448
449
450
451
452
453
454
	  <para>lists all the changes (using the
          <literal>diff</literal> command) in and below the current
          directory. In emacs, <literal>C-c C-v =</literal> runs
          <literal>cvs diff</literal> on the current buffer and shows
          you the results.</para>
	</listitem>

455
456
457
458
459
460
461
462
	<listitem>
	  <para>If you changed something in the 
          <literal>fptools/libraries</literal> subdirectories, also run
          <literal>make html</literal> to check if the documentation can
          be generated successfully, too.</para>
	</listitem>

	<listitem>
463
464
465
	  <para>Before checking in a change, you need to update your
          source tree:</para>

466
467
<screen>$ cd fptools
$ cvs update</screen>
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
	  <para>This pulls in any changes that other people have made,
          and merges them with yours. If there are any conflicts, CVS
          will tell you, and you'll have to resolve them before you
          can check your changes in. The documentation describes what
          to do in the event of a conflict.</para>

	  <para>It's not always necessary to do a full cvs update
          before checking in a change, since CVS will always tell you
          if you try to check in a file that someone else has changed.
          However, you should still update at regular intervals to
          avoid making changes that don't work in conjuction with
          changes that someone else made. Keeping an eye on what goes
          by on the mailing list can help here.</para>
	</listitem>

	<listitem>
	  <para>When you're happy that your change isn't going to
          break anything, check it in. For a one-file change:</para>

487
<screen>$ cvs commit <replaceable>filename</replaceable></screen>
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503

	  <para>CVS will then pop up an editor for you to enter a
          &quot;commit message&quot;, this is just a short description
          of what your change does, and will be kept in the history of
          the file.</para>

	  <para>If you're using emacs, simply load up the file into a
          buffer and type <literal>C-x C-q</literal>, and emacs will
          prompt for a commit message and then check in the file for
          you.</para>

	  <para>For a multiple-file change, things are a bit
          trickier. There are several ways to do this, but this is the
          way I find easiest. First type the commit message into a
          temporary file. Then either</para>

504
<screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable></screen>
505
506
507
508

	  <para>or, if nothing else has changed in this part of the
          source tree, </para>

509
<screen>$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable></screen>
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536

          <para>where <replaceable>directory</replaceable> is a common
          parent directory for all your changes, and
          <replaceable>commit-message</replaceable> is the name of the
          file containing the commit message.</para>

	  <para>Shortly afterwards, you'll get some mail from the
          relevant mailing list saying which files changed, and giving
          the commit message. For a multiple-file change, you should
          still get only <emphasis>one</emphasis> message.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="cvs-update">
      <title>Updating Your Source Tree</title>

      <para>It can be tempting to cvs update just part of a source
      tree to bring in some changes that someone else has made, or
      before committing your own changes. This is NOT RECOMMENDED!
      Quite often changes in one part of the tree are dependent on
      changes in another part of the tree (the
      <literal>mk/*.mk</literal> files are a good example where
      problems crop up quite often). Having an inconsistent tree is a
      major cause of headaches. </para>

      <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
544
545
      <quote>C</quote> in the first column).  New directories may have
      appeared in the repository; CVS doesn't check these out by
      default, so to get new directories you have to explicitly do
546
<screen>$ cvs update -d</screen>
547
548
549
550
551
552
553
      in each project subdirectory.  Don't do this at the top level,
      because then <emphasis>all</emphasis> the projects will be
      checked out.</para>

      <para>If you're using multiple build trees, then for every build
      tree you have pointing at this source tree, you need to update
      the links in case any new files have appeared: </para>
554

555
556
<screen>$ cd <replaceable>build-tree</replaceable>
$ lndir <replaceable>source-tree</replaceable></screen>
557
558
559
560

      <para>Some files might have been removed, so you need to remove
      the links pointing to these non-existent files:</para>

561
<screen>$ find . -xtype l -exec rm '{}' \;</screen>
562
563
564

      <para>To be <emphasis>really</emphasis> safe, you should do
      </para>
rrt's avatar
rrt committed
565

566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
<screen>$ gmake all</screen>

      <para>from the top-level, to update the dependencies and build
      any changed files. </para>
    </sect2>

    <sect2 id="cvs-tags">
      <title>GHC Tag Policy</title>

      <para>If you want to check out a particular version of GHC,
      you'll need to know how we tag versions in the repository.  The
      policy (as of 4.04) is:</para>

      <itemizedlist>
	<listitem>
	  <para>The tree is branched before every major release.  The
          branch tag is <literal>ghc-x-xx-branch</literal>, where
          <literal>x-xx</literal> is the version number of the release
          with the <literal>'.'</literal> replaced by a
          <literal>'-'</literal>.  For example, the 4.04 release lives
          on <literal>ghc-4-04-branch</literal>.</para>
	</listitem>

	<listitem>
	  <para>The release itself is tagged with
          <literal>ghc-x-xx</literal> (on the branch).  eg. 4.06 is
          called <literal>ghc-4-06</literal>.</para>
	</listitem>

	<listitem>
	  <para>We didn't always follow these guidelines, so to see
          what tags there are for previous versions, do <literal>cvs
          log</literal> on a file that's been around for a while (like
          <literal>fptools/ghc/README</literal>).</para>
	</listitem>
      </itemizedlist>

      <para>So, to check out a fresh GHC 4.06 tree you would
      do:</para>

606
607
608
<screen>$ cvs co -r ghc-4-06 fpconfig
$ cd fptools
$ cvs co -r ghc-4-06 ghc hslibs</screen>
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
    </sect2>

    <sect2 id="cvs-hints">
      <title>General Hints</title>

      <itemizedlist>
	<listitem>
	  <para>As a general rule: commit changes in small units,
          preferably addressing one issue or implementing a single
          feature.  Provide a descriptive log message so that the
          repository records exactly which changes were required to
          implement a given feature/fix a bug. I've found this
          <emphasis>very</emphasis> useful in the past for finding out
          when a particular bug was introduced: you can just wind back
          the CVS tree until the bug disappears.</para>
	</listitem>

	<listitem>
	  <para>Keep the sources at least *buildable* at any given
          time. No doubt bugs will creep in, but it's quite easy to
          ensure that any change made at least leaves the tree in a
          buildable state. We do nightly builds of GHC to keep an eye
          on what things work/don't work each day and how we're doing
          in relation to previous verions. This idea is truely wrecked
          if the compiler won't build in the first place!</para>
	</listitem>

	<listitem>
	  <para>To check out extra bits into an already-checked-out
          tree, use the following procedure.  Suppose you have a
          checked-out fptools tree containing just ghc, and you want
          to add nofib to it:</para>

642
643
<screen>$ cd fptools
$ cvs checkout nofib</screen>
644
645
646

	  <para>or: </para>

647
648
<screen>$ cd fptools
$ cvs update -d nofib</screen>
649
650
651
652
653
	  
	  <para>(the -d flag tells update to create a new
          directory). If you just want part of the nofib suite, you
          can do </para>

654
655
<screen>$ cd fptools
$ cvs checkout nofib/spectral</screen>
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680

	  <para>This works because <literal>nofib</literal> is a
          module in its own right, and spectral is a subdirectory of
          the nofib module. The path argument to checkout must always
          start with a module name. There's no equivalent form of this
          command using <literal>update</literal>.</para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="projects">
    <title>What projects are there?</title>

    <para>The <literal>fptools</literal> suite consists of several
    <firstterm>projects</firstterm>, most of which can be downloaded,
    built and installed individually.  Each project corresponds to a
    subdirectory in the source tree, and if checking out from CVS then
    each project can be checked out individually by sitting in the top
    level of your source tree and typing <command>cvs checkout
    <replaceable>project</replaceable></command>.</para>

    <para>Here is a list of the projects currently available:</para>

    <variablelist>
681
      <varlistentry>
682
683
684
685
	<term>
          <literal>alex</literal>
          <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
        </term>
686
687
688
689
690
691
692
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/alex/">Alex</ulink> lexical
	  analyser generator for Haskell.</para>
	</listitem>
      </varlistentry>

693
      <varlistentry>
694
695
696
697
698
	<term>
          <literal>ghc</literal>
          <indexterm><primary><literal>ghc</literal></primary>
          <secondary>project</secondary></indexterm>
        </term>
699
700
701
702
703
704
705
706
	<listitem>
	  <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
	  Haskell Compiler</ulink> (minus libraries).  Absolutely
	  required for building GHC.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
707
708
709
710
	<term>
          <literal>glafp-utils</literal>
          <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
        </term>
711
712
713
714
715
716
717
718
	<listitem>
	  <para>Utility programs, some of which are used by the
	  build/installation system.  Required for pretty much
	  everything.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
719
720
721
722
	<term>
          <literal>greencard</literal>
	  <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
        </term>
723
724
	<listitem>
	  <para>The <ulink
725
	  url="http://www.haskell.org/greencard/">GreenCard</ulink>
726
727
728
729
730
731
	  system for generating Haskell foreign function
	  interfaces.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
732
733
734
735
	<term>
          <literal>haggis</literal>
	  <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
        </term>
736
737
738
739
740
741
742
	<listitem>
	  <para>The <ulink
	  url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
	  Haskell GUI framework.</para>
	</listitem>
      </varlistentry>

743
      <varlistentry>
744
745
746
747
	<term>
          <literal>haddock</literal>
	  <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
        </term>
748
749
750
751
752
753
754
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/haddock/">Haddock</ulink>
	  documentation tool.</para>
	</listitem>
      </varlistentry>

755
      <varlistentry>
756
757
758
759
	<term>
          <literal>happy</literal>
          <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
        </term>
760
761
762
763
764
765
766
767
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/happy/">Happy</ulink> Parser
	  generator.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
768
769
770
771
	<term>
          <literal>hdirect</literal>
          <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
        </term>
772
773
774
775
776
777
778
779
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/hdirect/">H/Direct</ulink>
	  Haskell interoperability tool.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
780
781
782
783
	<term>
          <literal>hood</literal>
          <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
        </term>
784
785
786
787
788
789
790
	<listitem>
	  <para>The <ulink url="http://www.haskell.org/hood/">Haskell
	  Object Observation Debugger</ulink>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
791
792
793
794
	<term>
          <literal>hslibs</literal>
          <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
        </term>
795
	<listitem>
796
797
	  <para>Supplemental libraries for GHC
	  (<emphasis>required</emphasis> for building GHC).</para>
798
799
800
801
	</listitem>
      </varlistentry>

      <varlistentry>
802
803
804
805
	<term>
          <literal>libraries</literal>
          <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
        </term>
806
807
	<listitem>
	  <para>Hierarchical Haskell library suite
808
	  (<emphasis>required</emphasis> for building GHC).</para>
809
810
811
812
	</listitem>
      </varlistentry>

      <varlistentry>
813
814
815
816
	<term>
          <literal>mhms</literal>
          <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
        </term>
817
818
819
820
821
822
	<listitem>
	  <para>The Modular Haskell Metric System.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
823
824
825
826
	<term>
          <literal>nofib</literal>
          <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
        </term>
827
828
829
830
831
832
833
	<listitem>
	  <para>The NoFib suite: A collection of Haskell programs used
	  primarily for benchmarking.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
834
835
836
837
	<term>
          <literal>testsuite</literal>
          <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
        </term>
838
839
840
841
842
843
844
845
	<listitem>
	  <para>A testing framework, including GHC's regression test
	  suite.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>So, to build GHC you need at least the
846
847
848
    <literal>ghc</literal>, <literal>libraries</literal> and
    <literal>hslibs</literal> projects (a GHC source distribution will
    already include the bits you need).</para>
849
850
851
852
853
854
855
856
857
858
  </sect1>

  <sect1 id="sec-build-checks">
    <title>Things to check before you start</title>

    <para>Here's a list of things to check before you get
    started.</para>

    <orderedlist>

859
860
      <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
        space needed: from about 100Mb for a basic GHC
861
862
863
864
865
866
	build, up to probably 500Mb for a GHC build with everything
	included (libraries built several different ways,
	etc.).</para>
      </listitem>

      <listitem>
867
	<para>Use an appropriate machine / operating system.  <xref
868
	linkend="sec-port-info"/> lists the supported platforms; if
869
	yours isn't amongst these then you can try porting GHC (see
870
	<xref linkend="sec-porting-ghc"/>).</para>
871
872
873
      </listitem>

      <listitem>
874
	<para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
875
        installed.  <xref linkend="sec-pre-supposed"/>
876
877
878
879
880
        elaborates.</para>
      </listitem>

      <listitem>
	<para>If you have any problem when building or installing the
881
        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<xref
882
        linkend="sec-build-pitfalls"/>).  Also check the FAQ for the
883
        version you're building, which is part of the User's Guide and
884
        available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
885
        site</ulink>.</para>
886

887
	<indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
888
889
890
891

	<para>If you feel there is still some shortcoming in our
        procedure or instructions, please report it.</para>

892
893
894
895
	<para>For GHC, please see the <ulink
	url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
	section of the GHC Users' Guide</ulink>, to maximise the
	usefulness of your report.</para>
896
897
898

	<indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
	<para>If in doubt, please send a message to
899
900
901
	<email>glasgow-haskell-bugs@haskell.org</email>.
	<indexterm><primary>bugs</primary><secondary>mailing
	list</secondary></indexterm></para>
902
903
904
      </listitem>
    </orderedlist>
  </sect1>
rrt's avatar
rrt committed
905

906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
  <sect1 id="sec-port-info">
    <title>What machines the Glasgow tools run on</title>

<indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
<indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
<indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>

    <para>The main question is whether or not the Haskell compiler
    (GHC) runs on your platform.</para>

    <para>A &ldquo;platform&rdquo; is a
    architecture/manufacturer/operating-system combination, such as
    <literal>sparc-sun-solaris2</literal>.  Other common ones are
    <literal>alpha-dec-osf2</literal>,
    <literal>hppa1.1-hp-hpux9</literal>,
    <literal>i386-unknown-linux</literal>,
    <literal>i386-unknown-solaris2</literal>,
    <literal>i386-unknown-freebsd</literal>,
    <literal>i386-unknown-cygwin32</literal>,
    <literal>m68k-sun-sunos4</literal>,
    <literal>mips-sgi-irix5</literal>,
    <literal>sparc-sun-sunos4</literal>,
    <literal>sparc-sun-solaris2</literal>,
    <literal>powerpc-ibm-aix</literal>.</para>

    <para>Some libraries may only work on a limited number of
    platforms; for example, a sockets library is of no use unless the
    operating system supports the underlying BSDisms.</para>
rrt's avatar
rrt committed
934

935
936
    <sect2>
      <title>What platforms the Haskell compiler (GHC) runs on</title>
rrt's avatar
rrt committed
937

938
939
940
941
      <indexterm><primary>fully-supported platforms</primary></indexterm>
      <indexterm><primary>native-code generator</primary></indexterm>
      <indexterm><primary>registerised ports</primary></indexterm>
      <indexterm><primary>unregisterised ports</primary></indexterm>
rrt's avatar
rrt committed
942

943
944
945
946
947
948
      <para>The GHC hierarchy of Porting Goodness: (a)&nbsp;Best is a
      native-code generator; (b)&nbsp;next best is a
      &ldquo;registerised&rdquo; port; (c)&nbsp;the bare minimum is an
      &ldquo;unregisterised&rdquo; port.
      (&ldquo;Unregisterised&rdquo; is so terrible that we won't say
      more about it).</para>
rrt's avatar
rrt committed
949

950
951
952
      <para>We use Sparcs running Solaris 2.7 and x86 boxes running
      FreeBSD and Linux, so those are the best supported platforms,
      unsurprisingly.</para>
rrt's avatar
rrt committed
953

954
955
956
      <para>Here's everything that's known about GHC ports.  We
      identify platforms by their &ldquo;canonical&rdquo;
      CPU/Manufacturer/OS triple.</para>
rrt's avatar
rrt committed
957

958
959
      <variablelist>
	<varlistentry>
960
	  <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
961
962
963
964
965
	  <indexterm><primary>alpha-dec-osf</primary></indexterm>
	  <indexterm><primary>alpha-dec-linux</primary></indexterm>
	  <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
	  <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
	  <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
966
          </term>
967
968
969
970
971
972
973
974
975
	  <listitem>
	    <para>The OSF port is currently working (as of GHC version
	    5.02.1) and well supported.  The native code generator is
	    currently non-working.  Other operating systems will
	    require some minor porting.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
976
977
978
	  <term>sparc-sun-sunos4
	    <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
          </term>
979
980
981
982
983
984
985
	  <listitem>
	    <para>Probably works with minor tweaks, hasn't been tested
	    for a while.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
986
987
988
	  <term>sparc-sun-solaris2
            <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
          </term>
989
	  <listitem>
dons's avatar
dons committed
990
	    <para>Fully supported (at least for Solaris 2.7 and 2.6),
991
	    including native-code generator.</para>
992
993
994
	  </listitem>
	</varlistentry>

dons's avatar
dons committed
995
	<varlistentry>
996
997
998
	  <term>sparc-unknown-openbsd
            <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
          </term>
dons's avatar
dons committed
999
1000
1001
1002
1003
1004
	  <listitem>
	    <para>Supported, including native-code generator. The
	    same should also be true of NetBSD</para>
	  </listitem>
	</varlistentry>

1005
	<varlistentry>
1006
1007
1008
	  <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
            <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
          </term>
1009
	  <listitem>
1010
1011
1012
	    <para>A registerised port is available for version 4.08,
	    but GHC hasn't been built on that platform since (as far
	    as we know).  No native-code generator.</para>
1013
1014
1015
1016
	  </listitem>
	</varlistentry>

	<varlistentry>
1017
1018
1019
	  <term>i386-unknown-linux (PCs running Linux, ELF binary format)
            <indexterm><primary>i386-*-linux</primary></indexterm>
          </term>
1020
1021
	  <listitem>
	    <para>GHC works registerised and has a native code
1022
            generator.  You <emphasis>must</emphasis> have GCC 2.7.x
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
            or later.  NOTE about <literal>glibc</literal> versions:
            GHC binaries built on a system running <literal>glibc
            2.0</literal> won't work on a system running
            <literal>glibc 2.1</literal>, and vice versa.  In general,
            don't expect compatibility between
            <literal>glibc</literal> versions, even if the shared
            library version hasn't changed.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
1034
1035
1036
	  <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
            <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
          </term>
1037
1038
1039
1040
	  <listitem>
	    <para>GHC works registerised.  Pre-built packages are
            available in the native package format, so if you just
            need binaries you're better off just installing the
1041
1042
            package (it might even be on your installation
            CD!).</para>
1043
1044
	  </listitem>
	</varlistentry>
1045

1046
	<varlistentry>
1047
1048
1049
	  <term>i386-unknown-openbsd (PCs running OpenBSD)
            <indexterm><primary>i386-unknown-openbsd</primary></indexterm> 
          </term>
1050
1051
1052
1053
1054
1055
1056
1057
	  <listitem>
	    <para>Supported, with native code generator.  Packages are
	    available through the ports system in the native package
	    format.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
1058
1059
1060
	  <term>i386-unknown-netbsd (PCs running NetBSD)
            <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
          </term>
1061
1062
1063
1064
1065
1066
1067
	  <listitem>
	    <para>Will require some minor porting effort, but should
	    work registerised.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
1068
1069
1070
	  <term>i386-unknown-mingw32 (PCs running Windows)
            <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
          </term>
1071
	  <listitem>
1072
1073
	    <para>Fully supported under Win9x, WinNT, Win2k, and
            WinXP.  Includes a native code generator.  Building from
1074
1075
1076
            source requires a recent <ulink
            url="http://www.cygwin.com/">Cygwin</ulink> distribution
            to be installed.</para>
1077
1078
1079
	  </listitem>
	</varlistentry>

1080
	<varlistentry>
1081
1082
1083
	  <term>ia64-unknown-linux
            <indexterm><primary>ia64-unknown-linux</primary></indexterm>
          </term>
1084
	  <listitem>
1085
1086
	    <para>Supported, except there is no native code
	    generator.</para>
1087
1088
1089
	  </listitem>
	</varlistentry>

1090
	<varlistentry>
1091
1092
1093
	  <term>x86_64-unknown-linux
            <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
          </term>
1094
1095
1096
1097
1098
1099
	  <listitem>
	    <para>GHC currently works unregisterised.  A registerised
	    port is in progress.</para>
	  </listitem>
	</varlistentry>

dons's avatar
dons committed
1100
	<varlistentry>
1101
1102
1103
	  <term>amd64-unknown-openbsd
            <indexterm><primary>amd64-unknown-linux</primary></indexterm>
          </term>
dons's avatar
dons committed
1104
1105
1106
1107
1108
1109
1110
	  <listitem>
            <para>(This is the same as x86_64-unknown-openbsd). GHC
                currently works unregisterised.  A registerised port is in
                progress.</para>
	  </listitem>
	</varlistentry>

1111
	<varlistentry>
1112
1113
1114
	  <term>mips-sgi-irix5
            <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
          </term>
1115
	  <listitem>
1116
1117
1118
1119
1120
	    <para>Port has worked in the past, but hasn't been tested
            for some time (and will certainly have rotted in various
            ways).  As usual, we don't have access to machines and
            there hasn't been an overwhelming demand for this port,
            but feel free to get in touch.</para>
1121
1122
1123
	  </listitem>
	</varlistentry>

dons's avatar
dons committed
1124
	<varlistentry>
1125
1126
1127
	  <term>mips64-sgi-irix6
            <indexterm><primary>mips-sgi-irix6</primary></indexterm>
          </term>
dons's avatar
dons committed
1128
1129
1130
1131
1132
	  <listitem>
	    <para>GHC currently works unregisterised.</para>
	  </listitem>
	</varlistentry>

1133
	<varlistentry>
1134
1135
1136
	  <term>powerpc-ibm-aix
            <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
          </term>
1137
	  <listitem>
1138
1139
1140
1141
1142
1143
1144
1145
	    <para>Port currently doesn't work, needs some minimal
            porting effort.  As usual, we don't have access to
            machines and there hasn't been an overwhelming demand for
            this port, but feel free to get in touch.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
1146
1147
1148
	  <term>powerpc-apple-darwin
            <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
          </term>
1149
	  <listitem>
1150
1151
	    <para>Supported registerised.  Native code generator is
	    almost working.</para>
1152
1153
1154
1155
	  </listitem>
	</varlistentry>

	<varlistentry>
1156
1157
1158
	  <term>powerpc-apple-linux
            <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
          </term>
1159
1160
	  <listitem>
	    <para>Not supported (yet).</para>
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Various other systems have had GHC ported to them in the
      distant past, including various Motorola 68k boxes.  The 68k
      support still remains, but porting to one of these systems will
      certainly be a non-trivial task.</para>
    </sect2>

    <sect2>
      <title>What machines the other tools run on</title>

      <para>Unless you hear otherwise, the other tools work if GHC
      works.</para>
    </sect2>
  </sect1>
rrt's avatar
rrt committed
1178
1179


1180
1181
  <sect1 id="sec-pre-supposed">
    <title>Installing pre-supposed utilities</title>
rrt's avatar
rrt committed
1182

1183
1184
    <indexterm><primary>pre-supposed utilities</primary></indexterm>
    <indexterm><primary>utilities, pre-supposed</primary></indexterm>
rrt's avatar
rrt committed
1185

1186
1187
1188
1189
1190
1191
1192
    <para>Here are the gory details about some utility programs you
    may need; <command>perl</command>, <command>gcc</command> and
    <command>happy</command> are the only important
    ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
    important if you're going for Parallel Haskell.)  The
    <command>configure</command><indexterm><primary>configure</primary></indexterm>
    script will tell you if you are missing something.</para>
rrt's avatar
rrt committed
1193

1194
    <variablelist>
rrt's avatar
rrt committed
1195

1196
      <varlistentry>
1197
1198
1199
1200
	<term>GHC
          <indexterm><primary>pre-supposed: GHC</primary></indexterm>
          <indexterm><primary>GHC, pre-supposed</primary></indexterm>
        </term>
1201
1202
1203
1204
	<listitem>
	  <para>GHC is required to build many of the tools, including
	  GHC itself.  If you need to port GHC to your platform
	  because there isn't a binary distribution of GHC available,
1205
	  then see <xref linkend="sec-porting-ghc"/>.</para>
1206
1207
1208
1209
1210
1211
1212
1213

	  <para>Which version of GHC you need will depend on the
	  packages you intend to build.  GHC itself will normally
	  build using one of several older versions of itself - check
	  the announcement or release notes for details.</para>
	</listitem>
      </varlistentry>

1214
      <varlistentry>
1215
1216
1217
1218
	<term>Perl
          <indexterm><primary>pre-supposed: Perl</primary></indexterm>
          <indexterm><primary>Perl, pre-supposed</primary></indexterm>
        </term>
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
	<listitem>
	  <para><emphasis>You have to have Perl to proceed!</emphasis>
          Perl version 5 at least is required.  GHC has been known to
          tickle bugs in Perl, so if you find that Perl crashes when
          running GHC try updating (or downgrading) your Perl
          installation.  Versions of Perl that we use and are known to
          be fairly stable are 5.005 and 5.6.1.</para>

	  <para>For Win32 platforms, you should use the binary
          supplied in the InstallShield (copy it to
          <filename>/bin</filename>).  The Cygwin-supplied Perl seems
          not to work.</para>

	  <para>Perl should be put somewhere so that it can be invoked
          by the <literal>&num;!</literal> script-invoking
          mechanism. The full pathname may need to be less than 32
          characters long on some systems.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1238

1239
      <varlistentry>
1240
1241
1242
1243
	<term>GNU C (<command>gcc</command>)
          <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
          <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
        </term>
1244
1245
1246
1247
1248
1249
1250
1251
	<listitem>
	  <para>We recommend using GCC version 2.95.2 on all
          platforms.  Failing that, version 2.7.2 is stable on most
          platforms.  Earlier versions of GCC can be assumed not to
          work, and versions in between 2.7.2 and 2.95.2 (including
          <command>egcs</command>) have varying degrees of stability
          depending on the platform.</para>

1252
1253
1254
	  <para>GCC 3.2 is currently known to have problems building
	  GHC on Sparc, but is stable on x86.</para>
	  
1255
1256
	  <para>If your GCC dies with &ldquo;internal error&rdquo; on
          some GHC source file, please let us know, so we can report
1257
          it and get things improved.  (Exception: on x86
1258
1259
1260
1261
1262
          boxes&mdash;you may need to fiddle with GHC's
          <option>-monly-N-regs</option> option; see the User's
          Guide)</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1263

1264
      <varlistentry>
1265
1266
1267
	<term>GNU Make
          <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
        </term>
1268
1269
1270
1271
1272
1273
1274
	<listitem>
	  <para>The fptools build system makes heavy use of features
	  specific to GNU <command>make</command>, so you must have
	  this installed in order to build any of the fptools
	  suite.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1275

1276
      <varlistentry>
1277
1278
1279
	<term>Happy
          <indexterm><primary>Happy</primary></indexterm>
        </term>
1280
1281
1282
1283
1284
1285
1286
	<listitem>
	  <para>Happy is a parser generator tool for Haskell, and is
          used to generate GHC's parsers.  Happy is written in
          Haskell, and is a project in the CVS repository
          (<literal>fptools/happy</literal>).  It can be built from
          source, but bear in mind that you'll need GHC installed in
          order to build it.  To avoid the chicken/egg problem,
1287
          install a binary distribution of either Happy or GHC to get
1288
1289
1290
1291
1292
          started.  Happy distributions are available from <ulink
          url="http://www.haskell.org/happy/">Happy's Web
          Page</ulink>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1293

1294
      <varlistentry>
1295
1296
1297
	<term>Alex
          <indexterm><primary>Alex</primary></indexterm>
        </term>
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
	<listitem>
	  <para>Alex is a lexical-analyser generator for Haskell,
	  which GHC uses to generate its lexer.  Like Happy, Alex is
	  written in Haskell and is a project in the CVS repository.
	  Alex distributions are available from <ulink
	  url="http://www.haskell.org/alex/">Alex's Web
	  Page</ulink>.</para>
	</listitem>
      </varlistentry>

1308
      <varlistentry>
1309
1310
1311
1312
	<term>autoconf
          <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
          <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
        </term>
1313
	<listitem>
1314
	  <para>GNU autoconf is needed if you intend to build from the
1315
1316
1317
          CVS sources, it is <emphasis>not</emphasis> needed if you
          just intend to build a standard source distribution.</para>

1318
1319
	  <para>Version 2.52 or later of the autoconf package is required.
	  NB. version 2.13 will no longer work, as of GHC version
1320
1321
	  6.1.</para>

1322
1323
1324
1325
1326
1327
	  <para><command>autoreconf</command> (from the autoconf package)
          recursively builds <command>configure</command> scripts from
          the corresponding <filename>configure.ac</filename> and
          <filename>aclocal.m4</filename> files.  If you modify one of
          the latter files, you'll need <command>autoreconf</command> to
          rebuild the corresponding <filename>configure</filename>.</para>
1328
1329
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1330

1331
      <varlistentry>
1332
1333
1334
1335
	<term><command>sed</command>
          <indexterm><primary>pre-supposed: sed</primary></indexterm>
          <indexterm><primary>sed, pre-supposed</primary></indexterm>
        </term>
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
	<listitem>
	  <para>You need a working <command>sed</command> if you are
          going to build from sources.  The build-configuration stuff
          needs it.  GNU sed version 2.0.4 is no good!  It has a bug
          in it that is tickled by the build-configuration.  2.0.5 is
          OK. Others are probably OK too (assuming we don't create too
          elaborate configure scripts.)</para>
	</listitem>
      </varlistentry>
    </variablelist>
rrt's avatar
rrt committed
1346

1347
1348
1349
1350
1351
1352
    <para>One <literal>fptools</literal> project is worth a quick note
    at this point, because it is useful for all the others:
    <literal>glafp-utils</literal> contains several utilities which
    aren't particularly Glasgow-ish, but Occasionally Indispensable.
    Like <command>lndir</command> for creating symbolic link
    trees.</para>
rrt's avatar
rrt committed
1353

1354
1355
    <sect2 id="pre-supposed-gph-tools">
      <title>Tools for building parallel GHC (GPH)</title>
rrt's avatar
rrt committed
1356

1357
1358
      <variablelist>
	<varlistentry>
1359
	  <term>PVM version 3:
1360
	  <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
1361
1362
            <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
          </term>
1363
1364
1365
	  <listitem>
	    <para>PVM is the Parallel Virtual Machine on which
            Parallel Haskell programs run.  (You only need this if you
1366
            plan to run Parallel Haskell.  Concurrent Haskell, which
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
            runs concurrent threads on a uniprocessor doesn't need
            it.)  Underneath PVM, you can have (for example) a network
            of workstations (slow) or a multiprocessor box
            (faster).</para>

	    <para>The current version of PVM is 3.3.11; we use 3.3.7.
            It is readily available on the net; I think I got it from
            <literal>research.att.com</literal>, in
            <filename>netlib</filename>.</para>

	    <para>A PVM installation is slightly quirky, but easy to
            do.  Just follow the <filename>Readme</filename>
            instructions.</para>
	  </listitem>
	</varlistentry>
rrt's avatar
rrt committed
1382

1383
	<varlistentry>
1384
1385
1386
	  <term><command>bash</command>:
            <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
          </term>
1387
1388
1389
1390
1391
1392
1393
1394
1395
	  <listitem>
	    <para>Sadly, the <command>gr2ps</command> script, used to
            convert &ldquo;parallelism profiles&rdquo; to PostScript,
            is written in Bash (GNU's Bourne Again shell).  This bug
            will be fixed (someday).</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
rrt's avatar
rrt committed
1396

1397
1398
    <sect2 id="pre-supposed-other-tools">
      <title>Other useful tools</title>
rrt's avatar
rrt committed
1399

1400
1401
      <variablelist>
	<varlistentry>
1402
1403
1404
1405
	  <term>Flex
            <indexterm><primary>pre-supposed: flex</primary></indexterm> 
            <indexterm><primary>flex, pre-supposed</primary></indexterm>
          </term>
1406
1407
1408
1409
1410
1411
1412
1413
1414
	  <listitem>
	    <para>This is a quite-a-bit-better-than-Lex lexer.  Used
            to build a couple of utilities in
            <literal>glafp-utils</literal>.  Depending on your
            operating system, the supplied <command>lex</command> may
            or may not work; you should get the GNU version.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
1415
1416
1417

      <para>More tools are required if you want to format the documentation
      that comes with GHC and other fptools projects.  See <xref
1418
      linkend="building-docs"/>.</para>
1419
1420
    </sect2>
  </sect1>
rrt's avatar
rrt committed
1421

1422
1423
  <sect1 id="sec-building-from-source">
    <title>Building from source</title>
rrt's avatar
rrt committed
1424

1425
1426
    <indexterm><primary>Building from source</primary></indexterm>
    <indexterm><primary>Source, building from</primary></indexterm>
rrt's avatar
rrt committed
1427

1428
1429
1430
1431
1432
    <para>You've been rash enough to want to build some of the Glasgow
    Functional Programming tools (GHC, Happy, nofib, etc.) from
    source.  You've slurped the source, from the CVS repository or
    from a source distribution, and now you're sitting looking at a
    huge mound of bits, wondering what to do next.</para>
rrt's avatar
rrt committed
1433

1434
1435
    <para>Gingerly, you type <command>make</command>.  Wrong
    already!</para>
rrt's avatar
rrt committed
1436

1437
1438
1439
1440
1441
1442
    <para>This rest of this guide is intended for duffers like me, who
    aren't really interested in Makefiles and systems configurations,
    but who need a mental model of the interlocking pieces so that
    they can make them work, extend them consistently when adding new
    software, and lay hands on them gently when they don't
    work.</para>
rrt's avatar
rrt committed
1443

1444
1445
1446
1447
    <sect2 id="quick-start">
      <title>Quick Start</title>

      <para>If you are starting from a source distribution, and just
1448
1449
      want a completely standard build, then the following procedure should 
      work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
1450

1451
1452
<screen>$ autoreconf
$ ./configure
1453
$ make
1454
$ make install</screen>
1455
1456
1457
1458
1459
1460
1461
1462
1463

      <para>For GHC, this will do a 2-stage bootstrap build of the
      compiler, with profiling libraries, and install the
      results.</para>

      <para>If you want to do anything at all non-standard, or you
      want to do some development, read on...</para>
    </sect2>

1464
1465
    <sect2 id="sec-source-tree">
      <title>Your source tree</title>
rrt's avatar
rrt committed
1466

1467
1468
1469
1470
      <para>The source code is held in your <emphasis>source
      tree</emphasis>.  The root directory of your source tree
      <emphasis>must</emphasis> contain the following directories and
      files:</para>
rrt's avatar
rrt committed
1471

1472
1473
1474
1475
1476
      <itemizedlist>
	<listitem>
	  <para><filename>Makefile</filename>: the root
	  Makefile.</para>
	</listitem>
rrt's avatar
rrt committed
1477

1478
1479
1480
1481
1482
	<listitem>
	  <para><filename>mk/</filename>: the directory that contains
          the main Makefile code, shared by all the
          <literal>fptools</literal> software.</para>
	</listitem>
rrt's avatar
rrt committed
1483

1484
	<listitem>
1485
	  <para><filename>configure.ac</filename>,
1486
1487
1488
1489
          <filename>config.sub</filename>,
          <filename>config.guess</filename>: these files support the
          configuration process.</para>
	</listitem>
rrt's avatar
rrt committed
1490

1491
1492
1493
1494
	<listitem>
	  <para><filename>install-sh</filename>.</para>
	</listitem>
      </itemizedlist>
rrt's avatar
rrt committed
1495

1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
      <para>All the other directories are individual
      <emphasis>projects</emphasis> of the <literal>fptools</literal>
      system&mdash;for example, the Glasgow Haskell Compiler
      (<literal>ghc</literal>), the Happy parser generator
      (<literal>happy</literal>), the <literal>nofib</literal>
      benchmark suite, and so on.  You can have zero or more of these.
      Needless to say, some of them are needed to build others.</para>

      <para>The important thing to remember is that even if you want
      only one project (<literal>happy</literal>, say), you must have
      a source tree whose root directory contains
      <filename>Makefile</filename>, <filename>mk/</filename>,
1508
      <filename>configure.ac</filename>, and the project(s) you want
1509
1510
1511
      (<filename>happy/</filename> in this case).  You cannot get by
      with just the <filename>happy/</filename> directory.</para>
    </sect2>
rrt's avatar
rrt committed
1512

1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
152