building.sgml 171 KB
Newer Older
rrt's avatar
rrt committed
1 2 3 4 5 6 7 8 9
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<Article id="building-guide">

<ArtHeader>

<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>
10
<PubDate>November 2001</PubDate>
rrt's avatar
rrt committed
11

12 13 14 15 16 17
    <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
18

19 20 21 22 23
      <para>This guide is intended for people who want to build or
      modify programs from the Glasgow <Literal>fptools</Literal>
      suite (as distinct from those who merely want to
      <Emphasis>run</Emphasis> them). Installation instructions are
      now provided in the user guide.</para>
rrt's avatar
rrt committed
24

25 26 27
      <para>The bulk of this guide applies to building on Unix
      systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
    </abstract>
rrt's avatar
rrt committed
28

29
  </artheader>
rrt's avatar
rrt committed
30 31


32
  <sect1 id="sec-getting">
33 34 35 36
    <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
37

38
    <variablelist>
39

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
      <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
          version of GHC (preferably version 4.08+) on your machine in
          order to compile (most of) the sources, however.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
65

66 67 68 69 70 71 72 73 74
      <varlistentry>
	<term>The CVS repository.</term>
	<indexterm><primary>CVS repository</primary>
	</indexterm>
	<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>

75
	  <para>All the <literal>fptools</literal> source code is held
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 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 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 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 236 237 238 239 240
          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
          in <xref linkend="sec-cvs">.</para>
	</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
    <email>jlewis@galconn.com</email>). </para>

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

      <para>You can access the repository in one of two ways:
      read-only (<xref linkend="cvs-read-only">), or read-write (<xref
      linkend="cvs-read-write">).</para>

      <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>
	  </listitem>
	  <listitem>
            <para>Run the command</para>
<programlisting>
    $ cvs login
</programlisting>
	    <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>
	    <para>Now go to <xref linkend="cvs-first">.</para>
	  </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>
<screen>
     $ ssh-keygen -d
</screen>
	    <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>
<screen>
    $ ssh-keygen
</screen>

	    <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>
<screen>
   BatchMode Yes

   Host cvs.haskell.org
   Protocol 1
</screen>

	    <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>

241 242 243 244 245 246 247 248 249 250 251 252

       <para>
       [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
       and run it as follows:
       <Screen>
       c:\tmp> set CYGWIN32=tty
       c:\tmp> c:/user/local/bin/ssh-keygen1
       </Screen> </para>

	    <para>[Windows users.] To protect your
253 254 255 256 257 258 259
            <literal>.ssh</literal> from access by anyone else,
            right-click your <literal>.ssh</literal> directory, and
            select <literal>Properties</literal>.  If you are not on
            the access control list, add yourself, and give yourself
            full permissions (the second panel).  Remove everyone else
            from the access control list.  Don't leave them there but
            deny them access, because 'they' may be a list that
260
            includes you!</para>
261 262 263 264 265 266 267 268 269 270
	    <para>[March 2003] In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
	      you to have Unix permissions 600 (read/write for owner only) 
	      on the <literal>.ssh/identity</literal> file, else it 
	      bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
	      but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
	      The solution seems to be to set the CYGWIN environment
	      variable to "<literal>ntsec neta</literal>".  The CYGWIN environment variable is discussed
	      in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
	      and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
	      </para>
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
	  </listitem>

	  <listitem>
	    <para>Send a message to to the CVS repository
            administrator (currently Jeff Lewis
            <email>jeff@galconn.com</email>), containing:</para>
	    <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>
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
	   <ItemizedList>
	   <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>
311

312 313 314 315 316 317 318
             <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>
319 320
	<para>The <literal>CVSROOT</literal> environment variable will
        be recorded in the checked-out tree, so you don't need to set
321 322 323
        this every time. </para>

	     </listitem>
324

325 326 327 328 329 330 331 332 333 334
	<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
335
	set this to point to <filename>bash.exe</filename>.
336 337 338 339 340 341 342
	</para>
	</listitem>

       </ItemizedList>


	  </listitem>
343 344

	  <listitem>
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368
	  <para>
	  Put the following in <filename>$HOME/.cvsrc</filename>:
	  </para>
	  
	  <ProgramListing>
	  checkout -P
	  release -d
	  update -P
	  diff -u
	  </ProgramListing>
	  
	  <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>
369
	  </listitem>
370 371 372

	</orderedlist>

373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401

	<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>

402 403


404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
    <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>

<screen>
    $ cvs checkout fpconfig
</screen>

	  <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>

423 424 425 426 427 428 429 430 431 432 433
<para>[Windows users.]  The following messages appear to be harmless:
<Screen>
setsockopt IPTOS_LOWDELAY: Invalid argument
setsockopt IPTOS_THROUGHPUT: Invalid argument
</Screen>
</para>


	  <para>You can call the fptools directory whatever you like,
          CVS won't mind: </para>
	  
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
<screen>
    $ mv fptools <replaceable>directory</replaceable>
</screen>

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

	  <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>
<screen>
    $ cd <replaceable>directory</replaceable>
450
    $ cvs checkout ghc hslibs libraries
451 452 453 454
</screen>

	  <para>The second command here checks out the relevant
          modules you want to work on. For a GHC build, for instance,
455 456 457 458
          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
          <xref linkend="projects">).</para>
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 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 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 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
	</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>
<screen>
$ cvs diff
</screen>
	  <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>

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

<screen>
$ cd fptools
$ cvs update
</screen>
	  <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>

<screen>
$ cvs commit <replaceable>filename</replaceable>
</screen>

	  <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>

<screen>
$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
</screen>

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

<screen>
$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
</screen>

          <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
      updating your tree: </para>

<screen>
$ cd fptools
$ cvs update -Pd 2&gt;&amp;1 | tee log</screen>

      <para>Look at the log file, and fix any conflicts (denoted by a
      <quote>C</quote> in the first column). 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>

<screen>
$ cd <replaceable>build-tree</replaceable>
$ lndir <replaceable>source-tree</replaceable>
</screen>

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

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

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

604 605 606 607 608 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 642 643 644 645 646 647 648 649 650 651 652 653 654 655 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 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768
<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>

<screen>
     $ cvs co -r ghc-4-06 fpconfig
     $ cd fptools
     $ cvs co -r ghc-4-06 ghc hslibs
</screen>
    </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>

<screen>
$ cd fptools
$ cvs checkout nofib
</screen>

	  <para>or: </para>

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

<screen>
$ cd fptools
$ cvs checkout nofib/spectral
</screen>

	  <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>
      <varlistentry>
	<term><literal>ghc</literal></term>
	<indexterm><primary><literal>ghc</literal></primary>
	<secondary>project</secondary></indexterm>
	<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>
	<term><literal>glafp-utils</literal></term>
	<indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>Utility programs, some of which are used by the
	  build/installation system.  Required for pretty much
	  everything.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>green-card</literal></term>
	<indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/greencard/">Green Card</ulink>
	  system for generating Haskell foreign function
	  interfaces.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>haggis</literal></term>
	<indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink
	  url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
	  Haskell GUI framework.</para>
	</listitem>
      </varlistentry>

769 770 771 772 773 774 775 776 777 778
      <varlistentry>
	<term><literal>haddock</literal></term>
	<indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/haddock/">Haddock</ulink>
	  documentation tool.</para>
	</listitem>
      </varlistentry>

779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811
      <varlistentry>
	<term><literal>happy</literal></term>
	<indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/happy/">Happy</ulink> Parser
	  generator.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>hdirect</literal></term>
	<indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/hdirect/">H/Direct</ulink>
	  Haskell interoperability tool.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>hood</literal></term>
	<indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The <ulink url="http://www.haskell.org/hood/">Haskell
	  Object Observation Debugger</ulink>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>hslibs</literal></term>
	<indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
812 813
	  <para>Supplemental libraries for GHC
	  (<emphasis>required</emphasis> for building GHC).</para>
814 815 816 817 818 819 820 821
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>libraries</literal></term>
	<indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>Hierarchical Haskell library suite
822
	  (<emphasis>required</emphasis> for building GHC).</para>
823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>mhms</literal></term>
	<indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The Modular Haskell Metric System.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>nofib</literal></term>
	<indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
	<listitem>
	  <para>The NoFib suite: A collection of Haskell programs used
	  primarily for benchmarking.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>testsuite</literal></term>
	<indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
	<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
854 855 856
    <literal>ghc</literal>, <literal>libraries</literal> and
    <literal>hslibs</literal> projects (a GHC source distribution will
    already include the bits you need).</para>
857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875
  </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>

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

      <listitem>
876 877 878 879
	<para>Use an appropriate machine / operating system.  <xref
	linkend="sec-port-info"> lists the supported platforms; if
	yours isn't amongst these then you can try porting GHC (see
	<xref linkend="sec-porting-ghc">).</para>
880 881 882
      </listitem>

      <listitem>
883
	<para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
884 885 886 887 888 889
        installed.  <Xref LinkEnd="sec-pre-supposed">
        elaborates.</para>
      </listitem>

      <listitem>
	<para>If you have any problem when building or installing the
890
        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<Xref
891
        LinkEnd="sec-build-pitfalls">).  Also check the FAQ for the
892 893 894
        version you're building, which is part of the User's Guide and
        available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
        site</ulink>.</para>
895

896
	<indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
897 898 899 900

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

901 902 903 904
	<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>
905 906 907

	<indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
	<para>If in doubt, please send a message to
908 909 910
	<email>glasgow-haskell-bugs@haskell.org</email>.
	<indexterm><primary>bugs</primary><secondary>mailing
	list</secondary></indexterm></para>
911 912 913
      </listitem>
    </orderedlist>
  </sect1>
rrt's avatar
rrt committed
914

915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
  <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
943

944 945
    <sect2>
      <title>What platforms the Haskell compiler (GHC) runs on</title>
rrt's avatar
rrt committed
946

947 948 949 950
      <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
951

952 953 954 955 956 957
      <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
958

959 960 961
      <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
962

963 964 965
      <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
966

967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996
      <variablelist>
	<varlistentry>
	  <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
	  <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>
	  
	  <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>
	  <term>sparc-sun-sunos4</term>
	  <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
	  <listitem>
	    <para>Probably works with minor tweaks, hasn't been tested
	    for a while.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>sparc-sun-solaris2</term>
	  <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
	  <listitem>
997 998
	    <para>Fully supported (at least for Solaris 2.7),
	    including native-code generator.</para>
999 1000 1001 1002 1003 1004 1005
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
	  <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
	  <listitem>
1006 1007 1008
	    <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>
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
	  <indexterm><primary>i386-*-linux</primary></indexterm>
	  <listitem>
	    <para>GHC works registerised and has a native code
            generator.  You <Emphasis>must</Emphasis> have GCC 2.7.x
            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>
1029 1030
	  <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
	  higher)</term>
1031 1032 1033 1034 1035
	  <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
	  <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
1036 1037
            package (it might even be on your installation
            CD!).</para>
1038 1039
	  </listitem>
	</varlistentry>
1040

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

	<varlistentry>
	  <term>i386-unknown-netbsd (PCs running NetBSD and
	    OpenBSD)</term>
	    <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
1055 1056 1057 1058 1059 1060 1061
	  <listitem>
	    <para>Will require some minor porting effort, but should
	    work registerised.</para>
	  </listitem>
	</varlistentry>

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

1073 1074 1075 1076 1077 1078 1079 1080 1081
	<varlistentry>
	  <term>ia64-unknown-linux</term>
	  <indexterm><primary>ia64-unknown-linux</primary></indexterm>
	  <listitem>
	    <para>GHC currently works unregisterised.  A registerised
	    port is in progress.</para>
	  </listitem>
	</varlistentry>

1082 1083 1084 1085
	<varlistentry>
	  <term>mips-sgi-irix5</term>
	  <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
	  <listitem>
1086 1087 1088 1089 1090
	    <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>
1091 1092 1093 1094 1095 1096
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>powerpc-ibm-aix</term>
	  <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
1097
	  <listitem>
1098 1099 1100 1101 1102 1103 1104 1105
	    <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>
sebc's avatar
sebc committed
1106 1107
	  <term>powerpc-apple-darwin</term>
	  <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
1108
	  <listitem>
1109 1110 1111 1112 1113 1114 1115 1116 1117 1118
	    <para>Supported registerised.  No native code
	    generator.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>powerpc-apple-linux</term>
	  <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
	  <listitem>
	    <para>Not supported (yet).</para>
1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135
	  </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
1136 1137


1138 1139
  <sect1 id="sec-pre-supposed">
    <title>Installing pre-supposed utilities</title>
rrt's avatar
rrt committed
1140

1141 1142
    <indexterm><primary>pre-supposed utilities</primary></indexterm>
    <indexterm><primary>utilities, pre-supposed</primary></indexterm>
rrt's avatar
rrt committed
1143

1144 1145 1146 1147 1148 1149 1150
    <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
1151

1152
    <variablelist>
rrt's avatar
rrt committed
1153

1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170
      <varlistentry>
	<term>GHC</term>
	<indexterm><primary>pre-supposed: GHC</primary></indexterm>
	<indexterm><primary>GHC, pre-supposed</primary></indexterm>
	<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,
	  then see <xref linkend="sec-porting-ghc">.</para>

	  <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>

1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193
      <varlistentry>
	<term>Perl</term>
	<indexterm><primary>pre-supposed: Perl</primary></indexterm>
	<indexterm><primary>Perl, pre-supposed</primary></indexterm>
	<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
1194

1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215
      <varlistentry>
	<term>GNU C (<command>gcc</command>)</term>
	<indexterm><primary>pre-supposed: GCC (GNU C
	compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
	compiler), pre-supposed</primary></indexterm>
	<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>

	  <para>If your GCC dies with &ldquo;internal error&rdquo; on
          some GHC source file, please let us know, so we can report
          it and get things improved.  (Exception: on iX86
          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
1216

1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227
      <varlistentry>
	<term>GNU Make</term>
	<indexterm><primary>make</primary><secondary>GNU</secondary>
	</indexterm>
	<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
1228

1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244
      <varlistentry>
	<term>Happy</term>
	<indexterm><primary>Happy</primary></indexterm>
	<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,
          install a binary distribtion of either Happy or GHC to get
          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
1245

1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261
      <varlistentry>
	<term>Autoconf</term>
	<indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
	<indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
	<listitem>
	  <para>GNU Autoconf is needed if you intend to build from the
          CVS sources, it is <emphasis>not</emphasis> needed if you
          just intend to build a standard source distribution.</para>

	  <para>Autoconf builds the <command>configure</command>
          script from <filename>configure.in</filename> and
          <filename>aclocal.m4</filename>.  If you modify either of
          these files, you'll need <command>autoconf</command> to
          rebuild <filename>configure</filename>.</para>
	</listitem>
      </varlistentry>
rrt's avatar
rrt committed
1262

1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276
      <varlistentry>
	<term><command>sed</command></term>
	<indexterm><primary>pre-supposed: sed</primary></indexterm>
	<indexterm><primary>sed, pre-supposed</primary></indexterm>
	<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
1277

1278 1279 1280 1281 1282 1283
    <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
1284

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

1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311
      <variablelist>
	<varlistentry>
	  <term>PVM version 3:</term>
	  <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
	  <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
	  <listitem>
	    <para>PVM is the Parallel Virtual Machine on which
            Parallel Haskell programs run.  (You only need this if you
            plan to run Parallel Haskell.  Concurent Haskell, which
            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
1312

1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324
	<varlistentry>
	  <term><command>bash</command>:</term>
	  <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
	  <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
1325

1326 1327
    <sect2 id="pre-supposed-other-tools">
      <title>Other useful tools</title>
rrt's avatar
rrt committed
1328

1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342
      <variablelist>
	<varlistentry>
	  <term>Flex</term>
	  <indexterm><primary>pre-supposed: flex</primary></indexterm> 
	  <indexterm><primary>flex, pre-supposed</primary></indexterm>
	  <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>
1343 1344 1345 1346

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

1350 1351
  <sect1 id="sec-building-from-source">
    <title>Building from source</title>
rrt's avatar
rrt committed
1352

1353 1354
    <indexterm><primary>Building from source</primary></indexterm>
    <indexterm><primary>Source, building from</primary></indexterm>
rrt's avatar
rrt committed
1355

1356 1357 1358 1359 1360
    <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
1361

1362 1363
    <para>Gingerly, you type <command>make</command>.  Wrong
    already!</para>
rrt's avatar
rrt committed
1364

1365 1366 1367 1368 1369 1370
    <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
1371

1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391
    <sect2 id="quick-start">
      <title>Quick Start</title>

      <para>If you are starting from a source distribution, and just
      want a completely standard build, then the following should
      work:</para>

<screen>$ ./configure
$ make
$ make install
</screen>

      <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>

1392 1393
    <sect2 id="sec-source-tree">
      <title>Your source tree</title>
rrt's avatar
rrt committed
1394

1395 1396 1397 1398
      <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
1399

1400 1401 1402 1403 1404
      <itemizedlist>
	<listitem>
	  <para><filename>Makefile</filename>: the root
	  Makefile.</para>
	</listitem>
rrt's avatar
rrt committed
1405

1406 1407 1408 1409 1410
	<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
1411

1412 1413 1414 1415 1416 1417
	<listitem>
	  <para><filename>configure.in</filename>,
          <filename>config.sub</filename>,
          <filename>config.guess</filename>: these files support the
          configuration process.</para>
	</listitem>
rrt's avatar
rrt committed
1418

1419 1420 1421 1422
	<listitem>
	  <para><filename>install-sh</filename>.</para>
	</listitem>
      </itemizedlist>
rrt's avatar
rrt committed
1423

1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439
      <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>,
      <filename>configure.in</filename>, and the project(s) you want
      (<filename>happy/</filename> in this case).  You cannot get by
      with just the <filename>happy/</filename> directory.</para>
    </sect2>
rrt's avatar
rrt committed
1440

1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513
    <sect2>
      <title>Build trees</title>
      <indexterm><primary>build trees</primary></indexterm>
      <indexterm><primary>link trees, for building</primary></indexterm>

      <para>If you just want to build the software once on a single
      platform, then your source tree can also be your build tree, and
      you can skip the rest of this section.</para>

      <para>We often want to build multiple versions of our software
      for different architectures, or with different options
      (e.g. profiling).  It's very desirable to share a single copy of
      the source code among all these builds.</para>

      <para>So for every source tree we have zero or more
      <emphasis>build trees</emphasis>.  Each build tree is initially
      an exact copy of the source tree, except that each file is a
      symbolic link to the source file, rather than being a copy of
      the source file.  There are &ldquo;standard&rdquo; Unix
      utilities that make such copies, so standard that they go by
      different names:
      <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
      <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
      are two (If you don't have either, the source distribution
      includes sources for the X11
      <command>lndir</command>&mdash;check out
      <filename>fptools/glafp-utils/lndir</filename>). See <Xref
      LinkEnd="sec-storysofar"> for a typical invocation.</para>

      <para>The build tree does not need to be anywhere near the
      source tree in the file system.  Indeed, one advantage of
      separating the build tree from the source is that the build tree
      can be placed in a non-backed-up partition, saving your systems
      support people from backing up untold megabytes of
      easily-regenerated, and rapidly-changing, gubbins.  The golden
      rule is that (with a single exception&mdash;<XRef
      LinkEnd="sec-build-config">) <emphasis>absolutely everything in
      the build tree is either a symbolic link to the source tree, or
      else is mechanically generated</emphasis>.  It should be
      perfectly OK for your build tree to vanish overnight; an hour or
      two compiling and you're on the road again.</para>

      <para>You need to be a bit careful, though, that any new files
      you create (if you do any development work) are in the source
      tree, not a build tree!</para>

      <para>Remember, that the source files in the build tree are
      <emphasis>symbolic links</emphasis> to the files in the source
      tree.  (The build tree soon accumulates lots of built files like
      <filename>Foo.o</filename>, as well.)  You can
      <emphasis>delete</emphasis> a source file from the build tree
      without affecting the source tree (though it's an odd thing to
      do).  On the other hand, if you <emphasis>edit</emphasis> a
      source file from the build tree, you'll edit the source-tree
      file directly.  (You can set up Emacs so that if you edit a
      source file from the build tree, Emacs will silently create an
      edited copy of the source file in the build tree, leaving the
      source file unchanged; but the danger is that you think you've
      edited the source file whereas actually all you've done is edit
      the build-tree copy.  More commonly you do want to edit the
      source file.)</para>

      <para>Like the source tree, the top level of your build tree