building.xml 190 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,
stolz's avatar