File: building.sgml

package info (click to toggle)
ghc-cvs 20040725-2
links: PTS
area: main
in suites: sarge
size: 68,484 kB
ctags: 19,658
sloc: haskell: 251,945; ansic: 109,709; asm: 24,961; sh: 12,825; perl: 5,786; makefile: 5,334; xml: 3,884; python: 682; yacc: 650; lisp: 477; cpp: 337; ml: 76; fortran: 24; csh: 18
file content (4909 lines) | stat: -rw-r--r-- 195,998 bytes
<!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>

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

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

      <para>The bulk of this guide applies to building on Unix
      systems; see <xref linkend="winbuild"> for Windows notes.</para>
    </abstract>

</artheader>


  <sect1 id="sec-getting">
    <title>Getting the sources</title>
    
    <para>You can get your hands on the <literal>fptools</literal>
    in two ways:</para>

    <variablelist>

      <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 (version 5.x or later) on your machine in
          order to compile (most of) the sources, however.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
	<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>

	  <para>All the <literal>fptools</literal> source code is held
          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@galois.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>
	    <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
	      <screen>/cvs : no such repository</screen></para>
	  </listitem>
	  <listitem>
            <para>Run the command</para>
<screen>$ cvs login</screen>
	    <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>
<programlisting>BatchMode Yes

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

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


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


	  </listitem>

	  <listitem>
	    <para>Send a message to to the CVS repository
            administrator (currently Jeff Lewis
            <email>jeff@galois.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>
	   <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>

             <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>
	<para>The <literal>CVSROOT</literal> environment variable will
        be recorded in the checked-out tree, so you don't need to set
        this every time. </para>

	     </listitem>

	<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
	set this to point to <filename>bash.exe</filename>.
	</para>
	</listitem>

       </itemizedlist>


	  </listitem>

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

	</orderedlist>


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



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

<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>
	  
<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>
$ cvs checkout ghc hslibs libraries</screen>

	  <para>The second command here checks out the relevant
          modules you want to work on. For a GHC build, for instance,
          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>

	  <para>Remember that if you do not have
          <literal>happy</literal> and/or <literal>Alex</literal>
          installed, you need to check them out as well.</para>
	</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>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>
	  <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 -P 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).  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
<screen>$ cvs update -d</screen>
      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>

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

<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>alex</literal>
          <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/alex/">Alex</ulink> lexical
	  analyser generator for Haskell.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
          <literal>ghc</literal>
          <indexterm><primary><literal>ghc</literal></primary>
          <secondary>project</secondary></indexterm>
        </term>
	<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>
          <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<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>greencard</literal>
	  <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/greencard/">GreenCard</ulink>
	  system for generating Haskell foreign function
	  interfaces.</para>
	</listitem>
      </varlistentry>

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

      <varlistentry>
	<term>
          <literal>haddock</literal>
	  <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/haddock/">Haddock</ulink>
	  documentation tool.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
          <literal>happy</literal>
          <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>The <ulink
	  url="http://www.haskell.org/happy/">Happy</ulink> Parser
	  generator.</para>
	</listitem>
      </varlistentry>

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

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

      <varlistentry>
	<term>
          <literal>hslibs</literal>
          <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>Supplemental libraries for GHC
	  (<emphasis>required</emphasis> for building GHC).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
          <literal>libraries</literal>
          <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
        </term>
	<listitem>
	  <para>Hierarchical Haskell library suite
	  (<emphasis>required</emphasis> for building GHC).</para>
	</listitem>
      </varlistentry>

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

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

      <varlistentry>
	<term>
          <literal>testsuite</literal>
          <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
        </term>
	<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
    <literal>ghc</literal>, <literal>libraries</literal> and
    <literal>hslibs</literal> projects (a GHC source distribution will
    already include the bits you need).</para>
  </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><para><indexterm><primary>Disk space needed</primary></indexterm>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>
	<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>
      </listitem>

      <listitem>
	<para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
        installed.  <xref linkend="sec-pre-supposed">
        elaborates.</para>
      </listitem>

      <listitem>
	<para>If you have any problem when building or installing the
        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<xref
        linkend="sec-build-pitfalls">).  Also check the FAQ for the
        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>

	<indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>

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

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

	<indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
	<para>If in doubt, please send a message to
	<email>glasgow-haskell-bugs@haskell.org</email>.
	<indexterm><primary>bugs</primary><secondary>mailing
	list</secondary></indexterm></para>
      </listitem>
    </orderedlist>
  </sect1>

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

    <sect2>
      <title>What platforms the Haskell compiler (GHC) runs on</title>

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

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

      <para>We use Sparcs running Solaris 2.7 and x86 boxes running
      FreeBSD and Linux, so those are the best supported platforms,
      unsurprisingly.</para>

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

      <variablelist>
	<varlistentry>
	  <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
	  <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>
          </term>
	  <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
	    <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
          </term>
	  <listitem>
	    <para>Probably works with minor tweaks, hasn't been tested
	    for a while.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>sparc-sun-solaris2
            <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
          </term>
	  <listitem>
	    <para>Fully supported (at least for Solaris 2.7 and 2.6),
	    including native-code generator.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>sparc-unknown-openbsd
            <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
          </term>
	  <listitem>
	    <para>Supported, including native-code generator. The
	    same should also be true of NetBSD</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
            <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
          </term>
	  <listitem>
	    <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>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>i386-unknown-linux (PCs running Linux, ELF binary format)
            <indexterm><primary>i386-*-linux</primary></indexterm>
          </term>
	  <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>
	  <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
            <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
          </term>
	  <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
            package (it might even be on your installation
            CD!).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>i386-unknown-openbsd (PCs running OpenBSD)
            <indexterm><primary>i386-unknown-openbsd</primary></indexterm> 
          </term>
	  <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)
            <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
          </term>
	  <listitem>
	    <para>Will require some minor porting effort, but should
	    work registerised.</para>
	  </listitem>
	</varlistentry>

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

	<varlistentry>
	  <term>ia64-unknown-linux
            <indexterm><primary>ia64-unknown-linux</primary></indexterm>
          </term>
	  <listitem>
	    <para>Supported, except there is no native code
	    generator.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>x86_64-unknown-linux
            <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
          </term>
	  <listitem>
	    <para>GHC currently works unregisterised.  A registerised
	    port is in progress.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>amd64-unknown-openbsd
            <indexterm><primary>amd64-unknown-linux</primary></indexterm>
          </term>
	  <listitem>
            <para>(This is the same as x86_64-unknown-openbsd). GHC
                currently works unregisterised.  A registerised port is in
                progress.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>mips-sgi-irix5
            <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
          </term>
	  <listitem>
	    <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>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>mips64-sgi-irix6
            <indexterm><primary>mips-sgi-irix6</primary></indexterm>
          </term>
	  <listitem>
	    <para>GHC currently works unregisterised.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>powerpc-ibm-aix
            <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
          </term>
	  <listitem>
	    <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>
	  <term>powerpc-apple-darwin
            <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
          </term>
	  <listitem>
	    <para>Supported registerised.  Native code generator is
	    almost working.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>powerpc-apple-linux
            <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
          </term>
	  <listitem>
	    <para>Not supported (yet).</para>
	  </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>


  <sect1 id="sec-pre-supposed">
    <title>Installing pre-supposed utilities</title>

    <indexterm><primary>pre-supposed utilities</primary></indexterm>
    <indexterm><primary>utilities, pre-supposed</primary></indexterm>

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

    <variablelist>

      <varlistentry>
	<term>GHC
          <indexterm><primary>pre-supposed: GHC</primary></indexterm>
          <indexterm><primary>GHC, pre-supposed</primary></indexterm>
        </term>
	<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>

      <varlistentry>
	<term>Perl
          <indexterm><primary>pre-supposed: Perl</primary></indexterm>
          <indexterm><primary>Perl, pre-supposed</primary></indexterm>
        </term>
	<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>

      <varlistentry>
	<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>
	<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>GCC 3.2 is currently known to have problems building
	  GHC on Sparc, but is stable on x86.</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 x86
          boxes&mdash;you may need to fiddle with GHC's
          <option>-monly-N-regs</option> option; see the User's
          Guide)</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>GNU Make
          <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
        </term>
	<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>

      <varlistentry>
	<term>Happy
          <indexterm><primary>Happy</primary></indexterm>
        </term>
	<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 distribution 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>

      <varlistentry>
	<term>Alex
          <indexterm><primary>Alex</primary></indexterm>
        </term>
	<listitem>
	  <para>Alex is a lexical-analyser generator for Haskell,
	  which GHC uses to generate its lexer.  Like Happy, Alex is
	  written in Haskell and is a project in the CVS repository.
	  Alex distributions are available from <ulink
	  url="http://www.haskell.org/alex/">Alex's Web
	  Page</ulink>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>autoconf
          <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
          <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
        </term>
	<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>Version 2.52 or later of the autoconf package is required.
	  NB. version 2.13 will no longer work, as of GHC version
	  6.1.</para>

	  <para><command>autoreconf</command> (from the autoconf package)
          recursively builds <command>configure</command> scripts from
          the corresponding <filename>configure.ac</filename> and
          <filename>aclocal.m4</filename> files.  If you modify one of
          the latter files, you'll need <command>autoreconf</command> to
          rebuild the corresponding <filename>configure</filename>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>sed</command>
          <indexterm><primary>pre-supposed: sed</primary></indexterm>
          <indexterm><primary>sed, pre-supposed</primary></indexterm>
        </term>
	<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>

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

    <sect2 id="pre-supposed-gph-tools">
      <title>Tools for building parallel GHC (GPH)</title>

      <variablelist>
	<varlistentry>
	  <term>PVM version 3:
	  <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
            <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
          </term>
	  <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.  Concurrent 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>

	<varlistentry>
	  <term><command>bash</command>:
            <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
          </term>
	  <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>

    <sect2 id="pre-supposed-other-tools">
      <title>Other useful tools</title>

      <variablelist>
	<varlistentry>
	  <term>Flex
            <indexterm><primary>pre-supposed: flex</primary></indexterm> 
            <indexterm><primary>flex, pre-supposed</primary></indexterm>
          </term>
	  <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>

      <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>
    </sect2>
  </sect1>

  <sect1 id="sec-building-from-source">
    <title>Building from source</title>

    <indexterm><primary>Building from source</primary></indexterm>
    <indexterm><primary>Source, building from</primary></indexterm>

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

    <para>Gingerly, you type <command>make</command>.  Wrong
    already!</para>

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

    <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>$ autoreconf
$ ./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>

    <sect2 id="sec-source-tree">
      <title>Your source tree</title>

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

      <itemizedlist>
	<listitem>
	  <para><filename>Makefile</filename>: the root
	  Makefile.</para>
	</listitem>

	<listitem>
	  <para><filename>mk/</filename>: the directory that contains
          the main Makefile code, shared by all the
          <literal>fptools</literal> software.</para>
	</listitem>

	<listitem>
	  <para><filename>configure.ac</filename>,
          <filename>config.sub</filename>,
          <filename>config.guess</filename>: these files support the
          configuration process.</para>
	</listitem>

	<listitem>
	  <para><filename>install-sh</filename>.</para>
	</listitem>
      </itemizedlist>

      <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.ac</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>

    <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
      must be (a linked copy of) the root directory of the
      <literal>fptools</literal> suite.  Inside Makefiles, the root of
      your build tree is called
      <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant><indexterm><primary>FPTOOLS&lowbar;TOP</primary></indexterm>.
      In the rest of this document path names are relative to
      <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> unless
      otherwise stated.  For example, the file
      <filename>ghc/mk/target.mk</filename> is actually
      <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc/mk/target.mk</filename>.</para>
    </sect2>

    <sect2 id="sec-build-config">
      <title>Getting the build you want</title>

      <para>When you build <literal>fptools</literal> you will be
      compiling code on a particular <emphasis>host
      platform</emphasis>, to run on a particular <emphasis>target
      platform</emphasis> (usually the same as the host
      platform)<indexterm><primary>platform</primary></indexterm>.
      The difficulty is that there are minor differences between
      different platforms; minor, but enough that the code needs to be
      a bit different for each.  There are some big differences too:
      for a different architecture we need to build GHC with a
      different native-code generator.</para>

      <para>There are also knobs you can turn to control how the
      <literal>fptools</literal> software is built.  For example, you
      might want to build GHC optimised (so that it runs fast) or
      unoptimised (so that you can compile it fast after you've
      modified it.  Or, you might want to compile it with debugging on
      (so that extra consistency-checking code gets included) or off.
      And so on.</para>

      <para>All of this stuff is called the
      <emphasis>configuration</emphasis> of your build.  You set the
      configuration using a three-step process.</para>

      <variablelist>
	<varlistentry>
	  <term>Step 1: get ready for configuration.</term>
	  <listitem>
	    <para>NOTE: if you're starting from a source distribution,
	    rather than CVS sources, you can skip this step.</para>

	    <para>Change directory to
            <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
            issue the command</para>
<programlisting>autoreconf</programlisting>
            <indexterm><primary>autoreconf</primary></indexterm>
            <para>(with no arguments). This GNU program (recursively) converts
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure.ac</filename> and
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/aclocal.m4</filename>
            to a shell script called
            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure</filename>.
	      If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
	      then delete the latter and try again.  Note that you must use <command>autoreconf</command>,
	      and not the old <command>autoconf</command>!  If you erroneously use the latter, you'll get 
	      a message like "No rule to make target 'mk/config.h.in'".
            </para>

	    <para>Some projects, including GHC, have their own configure script.
            <command>autoreconf</command> takes care of that, too, so all you have
             to do is calling <command>autoreconf</command> in the top-level directory
            <filename>&dollar;(FPTOOLS&lowbar;TOP)</filename>.</para>

	    <para>These steps are completely platform-independent; they just mean
            that the human-written files (<filename>configure.ac</filename> and
            <filename>aclocal.m4</filename>) can be short, although the resulting
            files (the <command>configure</command> shell scripts and the C header
            template <filename>mk/config.h.in</filename>) are long.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Step 2: system configuration.</term>
	  <listitem>
	    <para>Runs the newly-created <command>configure</command>
	    script, thus:</para>

<programlisting>./configure <optional><parameter>args</parameter></optional></programlisting>

	    <para><command>configure</command>'s mission is to scurry
            round your computer working out what architecture it has,
            what operating system, whether it has the
            <function>vfork</function> system call, where
            <command>tar</command> is kept, whether
            <command>gcc</command> is available, where various obscure
            <literal>&num;include</literal> files are, whether it's a
            leap year, and what the systems manager had for lunch.  It
            communicates these snippets of information in two
            ways:</para>

	    <itemizedlist>
	      <listitem>
		
		<para>It translates
                <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
                to
                <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
                substituting for things between
                &ldquo;<literal>@</literal>&rdquo; brackets.  So,
                &ldquo;<literal>@HaveGcc@</literal>&rdquo; will be
                replaced by &ldquo;<literal>YES</literal>&rdquo; or
                &ldquo;<literal>NO</literal>&rdquo; depending on what
                <command>configure</command> finds.
                <filename>mk/config.mk</filename> is included by every
                Makefile (directly or indirectly), so the
                configuration information is thereby communicated to
                all Makefiles.</para>
		</listitem>

	      <listitem>
		<para> It translates
                <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
                to
                <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
                The latter is <literal>&num;include</literal>d by
                various C programs, which can thereby make use of
                configuration information.</para>
	      </listitem>
	    </itemizedlist>

	    <para><command>configure</command> takes some optional
	    arguments.  Use <literal>./configure --help</literal> to
	    get a list of the available arguments.  Here are some of
	    the ones you might need:</para>

	    <variablelist>
	      <varlistentry>
		<term><literal>--with-ghc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Specifies the path to an installed GHC which
		  you would like to use.  This compiler will be used
		  for compiling GHC-specific code (eg. GHC itself).
		  This option <emphasis>cannot</emphasis> be specified
		  using <filename>build.mk</filename> (see later),
		  because <command>configure</command> needs to
		  auto-detect the version of GHC you're using.  The
		  default is to look for a compiler named
		  <literal>ghc</literal> in your path.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal>--with-hc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Specifies the path to any installed Haskell
		  compiler.  This compiler will be used for compiling
		  generic Haskell code.  The default is to use
		  <literal>ghc</literal>.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal>--with-gcc=<parameter>path</parameter></literal>
                  <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Specifies the path to the installed GCC. This
		  compiler will be used to compile all C files,
		  <emphasis>except</emphasis> any generated by the
		  installed Haskell compiler, which will have its own
		  idea of which C compiler (if any) to use.  The
		  default is to use <literal>gcc</literal>.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term>Step 3: build configuration.</term>
	  <listitem>
	    <para>Next, you say how this build of
            <literal>fptools</literal> is to differ from the standard
            defaults by creating a new file
            <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
            <emphasis>in the build tree</emphasis>.  This file is the
            one and only file you edit in the build tree, precisely
            because it says how this build differs from the source.
            (Just in case your build tree does die, you might want to
            keep a private directory of <filename>build.mk</filename>
            files, and use a symbolic link in each build tree to point
            to the appropriate one.)  So
            <filename>mk/build.mk</filename> never exists in the
            source tree&mdash;you create one in each build tree from
            the template.  We'll discuss what to put in it
            shortly.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>And that's it for configuration. Simple, eh?</para>

      <para>What do you put in your build-specific configuration file
      <filename>mk/build.mk</filename>?  <emphasis>For almost all
      purposes all you will do is put make variable definitions that
      override those in</emphasis>
      <filename>mk/config.mk.in</filename>.  The whole point of
      <filename>mk/config.mk.in</filename>&mdash;and its derived
      counterpart <filename>mk/config.mk</filename>&mdash;is to define
      the build configuration. It is heavily commented, as you will
      see if you look at it.  So generally, what you do is look at
      <filename>mk/config.mk.in</filename>, and add definitions in
      <filename>mk/build.mk</filename> that override any of the
      <filename>config.mk</filename> definitions that you want to
      change.  (The override occurs because the main boilerplate file,
      <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
      includes <filename>build.mk</filename> after
      <filename>config.mk</filename>.)</para>

     <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
     that can serve as a starting point for your <filename>build.mk</filename>.</para>

      <para>For example, <filename>config.mk.in</filename> contains
      the definition:</para>

<programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>

      <para>The accompanying comment explains that this is the list of
      flags passed to GHC when building GHC itself.  For doing
      development, it is wise to add <literal>-DDEBUG</literal>, to
      enable debugging code.  So you would add the following to
      <filename>build.mk</filename>:</para>
      
      <para>or, if you prefer,</para>

<programlisting>GhcHcOpts += -DDEBUG</programlisting>

      <para>GNU <command>make</command> allows existing definitions to
      have new text appended using the &ldquo;<literal>+=</literal>&rdquo;
      operator, which is quite a convenient feature.)</para>

      <para>If you want to remove the <literal>-O</literal> as well (a
      good idea when developing, because the turn-around cycle gets a
      lot quicker), you can just override
      <literal>GhcLibHcOpts</literal> altogether:</para>

<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>

      <para>When reading <filename>config.mk.in</filename>, remember
      that anything between &ldquo;@...@&rdquo; signs is going to be substituted
      by <command>configure</command> later.  You
      <emphasis>can</emphasis> override the resulting definition if
      you want, but you need to be a bit surer what you are doing.
      For example, there's a line that says:</para>

<programlisting>TAR = @TarCmd@</programlisting>

      <para>This defines the Make variables <constant>TAR</constant>
      to the pathname for a <command>tar</command> that
      <command>configure</command> finds somewhere.  If you have your
      own pet <command>tar</command> you want to use instead, that's
      fine. Just add this line to <filename>mk/build.mk</filename>:</para>

<programlisting>TAR = mytar</programlisting>

      <para>You do not <emphasis>have</emphasis> to have a
      <filename>mk/build.mk</filename> file at all; if you don't,
      you'll get all the default settings from
      <filename>mk/config.mk.in</filename>.</para>

      <para>You can also use <filename>build.mk</filename> to override
      anything that <command>configure</command> got wrong.  One place
      where this happens often is with the definition of
      <constant>FPTOOLS&lowbar;TOP&lowbar;ABS</constant>: this
      variable is supposed to be the canonical path to the top of your
      source tree, but if your system uses an automounter then the
      correct directory is hard to find automatically.  If you find
      that <command>configure</command> has got it wrong, just put the
      correct definition in <filename>build.mk</filename>.</para>

    </sect2>

    <sect2 id="sec-storysofar">
      <title>The story so far</title>

      <para>Let's summarise the steps you need to carry to get
      yourself a fully-configured build tree from scratch.</para>

      <orderedlist>
	<listitem>
	  <para> Get your source tree from somewhere (CVS repository
          or source distribution).  Say you call the root directory
          <filename>myfptools</filename> (it does not have to be
          called <filename>fptools</filename>).  Make sure that you
          have the essential files (see <xref
          linkend="sec-source-tree">).</para>
	</listitem>

	<listitem>

	  <para>(Optional) Use <command>lndir</command> or
	  <command>mkshadowdir</command> to create a build tree.</para>

<programlisting>$ cd myfptools
$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</programlisting>

	  <para>(N.B. <command>mkshadowdir</command>'s first argument
          is taken relative to its second.) You probably want to give
          the build tree a name that suggests its main defining
          characteristic (in your mind at least), in case you later
          add others.</para>
	</listitem>

	<listitem>
	  <para>Change directory to the build tree.  Everything is
          going to happen there now.</para>

<programlisting>$ cd /scratch/joe-bloggs/myfptools-sun4</programlisting>

	</listitem>

	<listitem>
	  <para>Prepare for system configuration:</para>

<programlisting>$ autoreconf</programlisting>

	  <para>(You can skip this step if you are starting from a
          source distribution, and you already have
          <filename>configure</filename> and
          <filename>mk/config.h.in</filename>.)</para>
	</listitem>

	<listitem>
	  <para>Do system configuration:</para>

<programlisting>$ ./configure</programlisting>

	  <para>Don't forget to check whether you need to add any
	  arguments to <literal>configure</literal>; for example, a
	  common requirement is to specify which GHC to use with
	  <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
	</listitem>

	<listitem>
	  <para>Create the file <filename>mk/build.mk</filename>,
          adding definitions for your desired configuration
          options.</para>

<programlisting>$ emacs mk/build.mk</programlisting>
	</listitem>
      </orderedlist>

      <para>You can make subsequent changes to
      <filename>mk/build.mk</filename> as often as you like.  You do
      not have to run any further configuration programs to make these
      changes take effect. In theory you should, however, say
      <command>gmake clean</command>, <command>gmake all</command>,
      because configuration option changes could affect
      anything&mdash;but in practice you are likely to know what's
      affected.</para>
    </sect2>

    <sect2>
      <title>Making things</title>

      <para>At this point you have made yourself a fully-configured
      build tree, so you are ready to start building real
      things.</para>

      <para>The first thing you need to know is that <emphasis>you
      must use GNU <command>make</command>, usually called
      <command>gmake</command>, not standard Unix
      <command>make</command></emphasis>.  If you use standard Unix
      <command>make</command> you will get all sorts of error messages
      (but no damage) because the <literal>fptools</literal>
      <command>Makefiles</command> use GNU <command>make</command>'s
      facilities extensively.</para>

      <para>To just build the whole thing, <command>cd</command> to
      the top of your <literal>fptools</literal> tree and type
      <command>gmake</command>.  This will prepare the tree and build
      the various projects in the correct order.</para>
    </sect2>

    <sect2 id="sec-bootstrapping">
      <title>Bootstrapping GHC</title>

      <para>GHC requires a 2-stage bootstrap in order to provide 
      full functionality, including GHCi.  By a 2-stage bootstrap, we
      mean that the compiler is built once using the installed GHC,
      and then again using the compiler built in the first stage.  You
      can also build a stage 3 compiler, but this normally isn't
      necessary except to verify that the stage 2 compiler is working
      properly.</para>

      <para>Note that when doing a bootstrap, the stage 1 compiler
      must be built, followed by the runtime system and libraries, and
      then the stage 2 compiler.  The correct ordering is implemented
      by the top-level fptools <filename>Makefile</filename>, so if
      you want everything to work automatically it's best to start
      <command>make</command> from the top of the tree.  When building
      GHC, the top-level fptools <filename>Makefile</filename> is set
      up to do a 2-stage bootstrap by default (when you say
      <command>make</command>).  Some other targets it supports
      are:</para>

      <variablelist>
	<varlistentry>
	  <term>stage1</term>
	  <listitem>
	    <para>Build everything as normal, including the stage 1
	    compiler.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>stage2</term>
	  <listitem>
	    <para>Build the stage 2 compiler only.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>stage3</term>
	  <listitem>
	    <para>Build the stage 3 compiler only.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>bootstrap</term> <term>bootstrap2</term>
	  <listitem>
	    <para>Build stage 1 followed by stage 2.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>bootstrap3</term>
	  <listitem>
	    <para>Build stages 1, 2 and 3.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>install</term>
	  <listitem>
	    <para>Install everything, including the compiler built in
	    stage 2.  To override the stage, say <literal>make install
	    stage=<replaceable>n</replaceable></literal> where
	    <replaceable>n</replaceable> is the stage to install.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The top-level <filename>Makefile</filename> also arranges
      to do the appropriate <literal>make boot</literal> steps (see
      below) before actually building anything.</para>

      <para>The <literal>stage1</literal>, <literal>stage2</literal>
      and <literal>stage3</literal> targets also work in the
      <literal>ghc/compiler</literal> directory, but don't forget that
      each stage requires its own <literal>make boot</literal> step:
      for example, you must do</para>

      <screen>$ make boot stage=2</screen>

      <para>before <literal>make stage2</literal> in
      <literal>ghc/compiler</literal>.</para>
    </sect2>

    <sect2 id="sec-standard-targets">
      <title>Standard Targets</title>
      <indexterm><primary>targets, standard makefile</primary></indexterm>
      <indexterm><primary>makefile targets</primary></indexterm>

      <para>In any directory you should be able to make the following:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>boot</literal></term>
	  <listitem>
	    <para>does the one-off preparation required to get ready
            for the real work.  Notably, it does <command>gmake
            depend</command> in all directories that contain programs.
            It also builds the necessary tools for compilation to
            proceed.</para>

	    <para>Invoking the <literal>boot</literal> target
            explicitly is not normally necessary.  From the top-level
            <literal>fptools</literal> directory, invoking
            <literal>gmake</literal> causes <literal>gmake boot
            all</literal> to be invoked in each of the project
            subdirectories, in the order specified by
            <literal>&dollar;(AllTargets)</literal> in
            <literal>config.mk</literal>.</para>

	    <para>If you're working in a subdirectory somewhere and
            need to update the dependencies, <literal>gmake
            boot</literal> is a good way to do it.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>all</literal></term>
	  <listitem>
	    <para>makes all the final target(s) for this Makefile.
            Depending on which directory you are in a &ldquo;final
            target&rdquo; may be an executable program, a library
            archive, a shell script, or a Postscript file.  Typing
            <command>gmake</command> alone is generally the same as
            typing <command>gmake all</command>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>install</literal></term>
	  <listitem>
	    <para>installs the things built by <literal>all</literal>
            (except for the documentation).  Where does it install
            them?  That is specified by
            <filename>mk/config.mk.in</filename>; you can override it
            in <filename>mk/build.mk</filename>, or by running
            <command>configure</command> with command-line arguments
            like <literal>--bindir=/home/simonpj/bin</literal>; see
            <literal>./configure --help</literal> for the full
            details.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>install-docs</literal></term>
	  <listitem>
	    <para>installs the documentation. Otherwise behaves just
	    like <literal>install</literal>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>uninstall</literal></term>
	  <listitem>
	    <para>reverses the effect of
            <literal>install</literal>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>clean</literal></term>
	  <listitem>
	    <para>Delete all files from the current directory that are
            normally created by building the program.  Don't delete
            the files that record the configuration, or files
            generated by <command>gmake boot</command>.  Also preserve
            files that could be made by building, but normally aren't
            because the distribution comes with them.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>distclean</literal></term>
	  <listitem>
	    <para>Delete all files from the current directory that are
            created by configuring or building the program. If you
            have unpacked the source and built the program without
            creating any other files, <literal>make
            distclean</literal> should leave only the files that were
            in the distribution.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>mostlyclean</literal></term>
	  <listitem>
	    <para>Like <literal>clean</literal>, but may refrain from
            deleting a few files that people normally don't want to
            recompile.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>maintainer-clean</literal></term>
	  <listitem>
	    <para>Delete everything from the current directory that
            can be reconstructed with this Makefile.  This typically
            includes everything deleted by
            <literal>distclean</literal>, plus more: C source files
            produced by Bison, tags tables, Info files, and so
            on.</para>

	    <para>One exception, however: <literal>make
            maintainer-clean</literal> should not delete
            <filename>configure</filename> even if
            <filename>configure</filename> can be remade using a rule
            in the <filename>Makefile</filename>. More generally,
            <literal>make maintainer-clean</literal> should not delete
            anything that needs to exist in order to run
            <filename>configure</filename> and then begin to build the
            program.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>check</literal></term>
	  <listitem>
	    <para>run the test suite.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>All of these standard targets automatically recurse into
      sub-directories.  Certain other standard targets do not:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>configure</literal></term>
	  <listitem>
	    <para>is only available in the root directory
            <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>; it has
            been discussed in <xref
            linkend="sec-build-config">.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>depend</literal></term>
	  <listitem>
	    <para>make a <filename>.depend</filename> file in each
            directory that needs it. This <filename>.depend</filename>
            file contains mechanically-generated dependency
            information; for example, suppose a directory contains a
            Haskell source module <filename>Foo.lhs</filename> which
            imports another module <literal>Baz</literal>.  Then the
            generated <filename>.depend</filename> file will contain
            the dependency:</para>

<programlisting>Foo.o : Baz.hi</programlisting>

	    <para>which says that the object file
            <filename>Foo.o</filename> depends on the interface file
            <filename>Baz.hi</filename> generated by compiling module
            <literal>Baz</literal>.  The <filename>.depend</filename>
            file is automatically included by every Makefile.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>binary-dist</literal></term>
	  <listitem>
	    <para>make a binary distribution.  This is the target we
            use to build the binary distributions of GHC and
            Happy.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>dist</literal></term>
	  <listitem>
	    <para>make a source distribution.  Note that this target
            does &ldquo;make distclean&rdquo; as part of its work;
            don't use it if you want to keep what you've built.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Most <filename>Makefile</filename>s have targets other
      than these.  You can discover them by looking in the
      <filename>Makefile</filename> itself.</para>
    </sect2>

    <sect2>
      <title>Using a project from the build tree</title> 

      <para>If you want to build GHC (say) and just use it direct from
      the build tree without doing <literal>make install</literal>
      first, you can run the in-place driver script:
      <filename>ghc/compiler/ghc-inplace</filename>.</para>

      <para> Do <emphasis>NOT</emphasis> use
      <filename>ghc/compiler/ghc</filename>, or
      <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
      scripts intended for installation, and contain hard-wired paths
      to the installed libraries, rather than the libraries in the
      build tree.</para>

      <para>Happy can similarly be run from the build tree, using
      <filename>happy/src/happy-inplace</filename>, and similarly for
      Alex and Haddock.</para>
    </sect2>

    <sect2>
      <title>Fast Making</title>

      <indexterm><primary>fastmake</primary></indexterm>
      <indexterm><primary>dependencies, omitting</primary></indexterm>
      <indexterm><primary>FAST, makefile variable</primary></indexterm>

      <para>Sometimes the dependencies get in the way: if you've made
      a small change to one file, and you're absolutely sure that it
      won't affect anything else, but you know that
      <command>make</command> is going to rebuild everything anyway,
      the following hack may be useful:</para>

<programlisting>gmake FAST=YES</programlisting>

      <para>This tells the make system to ignore dependencies and just
      build what you tell it to.  In other words, it's equivalent to
      temporarily removing the <filename>.depend</filename> file in
      the current directory (where <command>mkdependHS</command> and
      friends store their dependency information).</para>

      <para>A bit of history: GHC used to come with a
      <command>fastmake</command> script that did the above job, but
      GNU make provides the features we need to do it without
      resorting to a script.  Also, we've found that fastmaking is
      less useful since the advent of GHC's recompilation checker (see
      the User's Guide section on "Separate Compilation").</para>
    </sect2>
  </sect1>

  <sect1 id="sec-makefile-arch">
    <title>The <filename>Makefile</filename> architecture</title>
    <indexterm><primary>makefile architecture</primary></indexterm>

    <para><command>make</command> is great if everything
    works&mdash;you type <command>gmake install</command> and lo! the
    right things get compiled and installed in the right places.  Our
    goal is to make this happen often, but somehow it often doesn't;
    instead some weird error message eventually emerges from the
    bowels of a directory you didn't know existed.</para>

    <para>The purpose of this section is to give you a road-map to
    help you figure out what is going right and what is going
    wrong.</para>

    <sect2>
      <title>Debugging</title>
      
      <para>Debugging <filename>Makefile</filename>s is something of a
      black art, but here's a couple of tricks that we find
      particularly useful.  The following command allows you to see
      the contents of any make variable in the context of the current
      <filename>Makefile</filename>:</para>

<screen>$ make show VALUE=HS_SRCS</screen>

      <para>where you can replace <literal>HS_SRCS</literal> with the
      name of any variable you wish to see the value of.</para>
      
      <para>GNU make has a <option>-d</option> option which generates
      a dump of the decision procedure used to arrive at a conclusion
      about which files should be recompiled.  Sometimes useful for
      tracking down problems with superfluous or missing
      recompilations.</para>
    </sect2>

    <sect2>
      <title>A small project</title>

      <para>To get started, let us look at the
      <filename>Makefile</filename> for an imaginary small
      <literal>fptools</literal> project, <literal>small</literal>.
      Each project in <literal>fptools</literal> has its own directory
      in <constant>FPTOOLS&lowbar;TOP</constant>, so the
      <literal>small</literal> project will have its own directory
      <constant>FPOOLS&lowbar;TOP/small/</constant>.  Inside the
      <filename>small/</filename> directory there will be a
      <filename>Makefile</filename>, looking something like
      this:</para>

<indexterm><primary>Makefile, minimal</primary></indexterm>

<programlisting># Makefile for fptools project "small"

TOP = ..
include $(TOP)/mk/boilerplate.mk

SRCS = $(wildcard *.lhs) $(wildcard *.c)
HS_PROG = small

include $(TOP)/target.mk</programlisting>

      <para>this <filename>Makefile</filename> has three
      sections:</para>

      <orderedlist>
	<listitem>
	  <para>The first section includes
<footnote>
<para>
One of the most important
features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
include another named file, very like <command>cpp</command>'s <literal>&num;include</literal>
directive.
</para>
</footnote>

          a file of &ldquo;boilerplate&rdquo; code from the level
          above (which in this case will be
          <filename>FPTOOLS&lowbar;TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
          As its name suggests, <filename>boilerplate.mk</filename>
          consists of a large quantity of standard
          <filename>Makefile</filename> code.  We discuss this
          boilerplate in more detail in <xref linkend="sec-boiler">.
          <indexterm><primary>include, directive in
          Makefiles</primary></indexterm> <indexterm><primary>Makefile
          inclusion</primary></indexterm></para>

          <para>Before the <literal>include</literal> statement, you
          must define the <command>make</command> variable
          <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
          to be the directory containing the <filename>mk</filename>
          directory in which the <filename>boilerplate.mk</filename>
          file is.  It is <emphasis>not</emphasis> OK to simply say</para>

<programlisting>include ../mk/boilerplate.mk  # NO NO NO</programlisting>


          <para>Why?  Because the <filename>boilerplate.mk</filename>
          file needs to know where it is, so that it can, in turn,
          <literal>include</literal> other files.  (Unfortunately,
          when an <literal>include</literal>d file does an
          <literal>include</literal>, the filename is treated relative
          to the directory in which <command>gmake</command> is being
          run, not the directory in which the
          <literal>include</literal>d sits.)  In general,
          <emphasis>every file <filename>foo.mk</filename> assumes
          that
          <filename>&dollar;(TOP)/mk/foo.mk</filename>
          refers to itself.</emphasis> It is up to the
          <filename>Makefile</filename> doing the
          <literal>include</literal> to ensure this is the case.</para>

          <para>Files intended for inclusion in other
          <filename>Makefile</filename>s are written to have the
          following property: <emphasis>after
          <filename>foo.mk</filename> is <literal>include</literal>d,
          it leaves <constant>TOP</constant> containing the same value
          as it had just before the <literal>include</literal>
          statement</emphasis>.  In our example, this invariant
          guarantees that the <literal>include</literal> for
          <filename>target.mk</filename> will look in the same
          directory as that for <filename>boilerplate.mk</filename>.</para>
	</listitem>

	<listitem>
	  <para> The second section defines the following standard
          <command>make</command> variables:
          <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
          (the source files from which is to be built), and
          <constant>HS&lowbar;PROG</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>
          (the executable binary to be built).  We will discuss in
          more detail what the &ldquo;standard variables&rdquo; are,
          and how they affect what happens, in <xref
          linkend="sec-targets">.</para>

	  <para>The definition for <constant>SRCS</constant> uses the
          useful GNU <command>make</command> construct
          <literal>&dollar;(wildcard&nbsp;$pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
          which expands to a list of all the files matching the
          pattern <literal>pat</literal> in the current directory.  In
          this example, <constant>SRCS</constant> is set to the list
          of all the <filename>.lhs</filename> and
          <filename>.c</filename> files in the directory.  (Let's
          suppose there is one of each, <filename>Foo.lhs</filename>
          and <filename>Baz.c</filename>.)</para>
	</listitem>

	<listitem>
	  <para>The last section includes a second file of standard
          code, called
          <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
          It contains the rules that tell <command>gmake</command> how
          to make the standard targets (<xref
          linkend="sec-standard-targets">).  Why, you ask, can't this
          standard code be part of
          <filename>boilerplate.mk</filename>?  Good question.  We
          discuss the reason later, in <xref
          linkend="sec-boiler-arch">.</para>

          <para>You do not <emphasis>have</emphasis> to
          <literal>include</literal> the
          <filename>target.mk</filename> file.  Instead, you can write
          rules of your own for all the standard targets.  Usually,
          though, you will find quite a big payoff from using the
          canned rules in <filename>target.mk</filename>; the price
          tag is that you have to understand what canned rules get
          enabled, and what they do (<xref
          linkend="sec-targets">).</para>
	</listitem>
      </orderedlist>

      <para>In our example <filename>Makefile</filename>, most of the
      work is done by the two <literal>include</literal>d files.  When
      you say <command>gmake all</command>, the following things
      happen:</para>

      <itemizedlist>
	<listitem>
	  <para><command>gmake</command> figures out that the object
          files are <filename>Foo.o</filename> and
          <filename>Baz.o</filename>.</para>
	</listitem>

	<listitem>
	  <para>It uses a boilerplate pattern rule to compile
          <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
          using a Haskell compiler.  (Which one?  That is set in the
          build configuration.)</para>
	</listitem>

	<listitem>
	  <para>It uses another standard pattern rule to compile
          <filename>Baz.c</filename> to <filename>Baz.o</filename>,
          using a C compiler.  (Ditto.)</para>
	</listitem>

	<listitem>
	  <para>It links the resulting <filename>.o</filename> files
          together to make <literal>small</literal>, using the Haskell
          compiler to do the link step.  (Why not use
          <command>ld</command>?  Because the Haskell compiler knows
          what standard libraries to link in.  How did
          <command>gmake</command> know to use the Haskell compiler to
          do the link, rather than the C compiler?  Because we set the
          variable <constant>HS&lowbar;PROG</constant> rather than
          <constant>C&lowbar;PROG</constant>.)</para>
	</listitem>
      </itemizedlist>

      <para>All <filename>Makefile</filename>s should follow the above
      three-section format.</para>
    </sect2>

    <sect2>
      <title>A larger project</title>

      <para>Larger projects are usually structured into a number of
      sub-directories, each of which has its own
      <filename>Makefile</filename>.  (In very large projects, this
      sub-structure might be iterated recursively, though that is
      rare.)  To give you the idea, here's part of the directory
      structure for the (rather large) GHC project:</para>

<screen>$(FPTOOLS_TOP)/ghc/
  Makefile
  mk/
    boilerplate.mk
    rules.mk
   docs/
    Makefile
    ...source files for documentation...
   driver/
    Makefile
    ...source files for driver...
   compiler/
    Makefile
    parser/...source files for parser...
    renamer/...source files for renamer...
    ...etc...</screen>

      <para>The sub-directories <filename>docs</filename>,
      <filename>driver</filename>, <filename>compiler</filename>, and
      so on, each contains a sub-component of GHC, and each has its
      own <filename>Makefile</filename>.  There must also be a
      <filename>Makefile</filename> in
      <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc</filename>.
      It does most of its work by recursively invoking
      <command>gmake</command> on the <filename>Makefile</filename>s
      in the sub-directories.  We say that
      <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
      <filename>Makefile</filename></emphasis>, because it does little
      except organise its children, while the
      <filename>Makefile</filename>s in the sub-directories are all
      <emphasis>leaf <filename>Makefile</filename>s</emphasis>.  (In
      principle the sub-directories might themselves contain a
      non-leaf <filename>Makefile</filename> and several
      sub-sub-directories, but that does not happen in GHC.)</para>

      <para>The <filename>Makefile</filename> in
      <filename>ghc/compiler</filename> is considered a leaf
      <filename>Makefile</filename> even though the
      <filename>ghc/compiler</filename> has sub-directories, because
      these sub-directories do not themselves have
      <filename>Makefile</filename>s in them.  They are just used to
      structure the collection of modules that make up GHC, but all
      are managed by the single <filename>Makefile</filename> in
      <filename>ghc/compiler</filename>.</para>

      <para>You will notice that <filename>ghc/</filename> also
      contains a directory <filename>ghc/mk/</filename>.  It contains
      GHC-specific <filename>Makefile</filename> boilerplate code.
      More precisely:</para>

      <itemizedlist>
	<listitem>
	  <para><filename>ghc/mk/boilerplate.mk</filename> is included
          at the top of <filename>ghc/Makefile</filename>, and of all
          the leaf <filename>Makefile</filename>s in the
          sub-directories.  It in turn <literal>include</literal>s the
          main boilerplate file
          <filename>mk/boilerplate.mk</filename>.</para>
	</listitem>

	<listitem>
	  <para><filename>ghc/mk/target.mk</filename> is
          <literal>include</literal>d at the bottom of
          <filename>ghc/Makefile</filename>, and of all the leaf
          <filename>Makefile</filename>s in the sub-directories.  It
          in turn <literal>include</literal>s the file
          <filename>mk/target.mk</filename>.</para>
	</listitem>
      </itemizedlist>

      <para>So these two files are the place to look for GHC-wide
      customisation of the standard boilerplate.</para>
    </sect2>

    <sect2 id="sec-boiler-arch">
      <title>Boilerplate architecture</title>
      <indexterm><primary>boilerplate architecture</primary></indexterm>

      <para>Every <filename>Makefile</filename> includes a
      <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
      file at the top, and
      <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
      file at the bottom.  In this section we discuss what is in these
      files, and why there have to be two of them.  In general:</para>

      <itemizedlist>
	<listitem>
	  <para><filename>boilerplate.mk</filename> consists of:</para>

	  <itemizedlist>
	    <listitem>
	      <para><emphasis>Definitions of millions of
              <command>make</command> variables</emphasis> that
              collectively specify the build configuration.  Examples:
              <constant>HC&lowbar;OPTS</constant><indexterm><primary>HC&lowbar;OPTS</primary></indexterm>,
              the options to feed to the Haskell compiler;
              <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
              the sub-directories to enable within the
              <literal>nofib</literal> project;
              <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
              the name of the Haskell compiler to use when compiling
              GHC in the <literal>ghc</literal> project.</para>
	    </listitem>

	    <listitem>
	      <para><emphasis>Standard pattern rules</emphasis> that
              tell <command>gmake</command> how to construct one file
              from another.</para>
	    </listitem>
	  </itemizedlist>

	  <para><filename>boilerplate.mk</filename> needs to be
          <literal>include</literal>d at the <emphasis>top</emphasis>
          of each <filename>Makefile</filename>, so that the user can
          replace the boilerplate definitions or pattern rules by
          simply giving a new definition or pattern rule in the
          <filename>Makefile</filename>.  <command>gmake</command>
          simply takes the last definition as the definitive one.</para>

	  <para>Instead of <emphasis>replacing</emphasis> boilerplate
          definitions, it is also quite common to
          <emphasis>augment</emphasis> them. For example, a
          <filename>Makefile</filename> might say:</para>

<programlisting>SRC_HC_OPTS += -O</programlisting>

	  <para>thereby adding &ldquo;<option>-O</option>&rdquo; to
	  the end of
	  <constant>SRC&lowbar;HC&lowbar;OPTS</constant><indexterm><primary>SRC&lowbar;HC&lowbar;OPTS</primary></indexterm>.</para>
	</listitem>

	<listitem>
	  <para><filename>target.mk</filename> contains
          <command>make</command> rules for the standard targets
          described in <xref linkend="sec-standard-targets">.  These
          rules are selectively included, depending on the setting of
          certain <command>make</command> variables.  These variables
          are usually set in the middle section of the
          <filename>Makefile</filename> between the two
          <literal>include</literal>s.</para>

	  <para><filename>target.mk</filename> must be included at the
          end (rather than being part of
          <filename>boilerplate.mk</filename>) for several tiresome
          reasons:</para>

	  <itemizedlist>
	    <listitem>

	      <para><command>gmake</command> commits target and
              dependency lists earlier than it should.  For example,
              <filename>target.mk</filename> has a rule that looks
              like this:</para>

<programlisting>$(HS_PROG) : $(OBJS)
      $(HC) $(LD_OPTS) $&#60; -o $@</programlisting>

	      <para>If this rule was in
              <filename>boilerplate.mk</filename> then
              <constant>&dollar;(HS&lowbar;PROG)</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>
              and
              <constant>&dollar;(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
              would not have their final values at the moment
              <command>gmake</command> encountered the rule.  Alas,
              <command>gmake</command> takes a snapshot of their
              current values, and wires that snapshot into the rule.
              (In contrast, the commands executed when the rule
              &ldquo;fires&rdquo; are only substituted at the moment
              of firing.)  So, the rule must follow the definitions
              given in the <filename>Makefile</filename> itself.</para>
	    </listitem>

	    <listitem>
	      <para>Unlike pattern rules, ordinary rules cannot be
              overriden or replaced by subsequent rules for the same
              target (at least, not without an error message).
              Including ordinary rules in
              <filename>boilerplate.mk</filename> would prevent the
              user from writing rules for specific targets in specific
              cases.</para>
	    </listitem>

	    <listitem>
	      <para>There are a couple of other reasons I've
              forgotten, but it doesn't matter too much.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="sec-boiler">
      <title>The main <filename>mk/boilerplate.mk</filename> file</title>
      <indexterm><primary>boilerplate.mk</primary></indexterm>

      <para>If you look at
      <filename>&dollar;(FPTOOLS&lowbar;TOP)/mk/boilerplate.mk</filename>
      you will find that it consists of the following sections, each
      held in a separate file:</para>

      <variablelist>
	<varlistentry>
	  <term><filename>config.mk</filename>
            <indexterm><primary>config.mk</primary></indexterm>
          </term>
	  <listitem>
	    <para>is the build configuration file we discussed at
            length in <xref linkend="sec-build-config">.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><filename>paths.mk</filename>
            <indexterm><primary>paths.mk</primary></indexterm>
          </term>
	  <listitem>
	    <para>defines <command>make</command> variables for
            pathnames and file lists.  This file contains code for
            automatically compiling lists of source files and deriving
            lists of object files from those.  The results can be
            overriden in the <filename>Makefile</filename>, but in
            most cases the automatic setup should do the right
            thing.</para>
	    
	    <para>The following variables may be set in the
	    <filename>Makefile</filename> to affect how the automatic
	    source file search is done:</para>

	    <variablelist>
	      <varlistentry>
		<term><literal>ALL_DIRS</literal>
                  <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Set to a list of directories to search in
		  addition to the current directory for source
		  files.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>EXCLUDE_SRCS</literal>
                  <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Set to a list of source files (relative to the
		  current directory) to omit from the automatic
		  search.  The source searching machinery is clever
		  enough to know that if you exclude a source file
		  from which other sources are derived, then the
		  derived sources should also be excluded.  For
		  example, if you set <literal>EXCLUDED_SRCS</literal>
		  to include <filename>Foo.y</filename>, then
		  <filename>Foo.hs</filename> will also be
		  excluded.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>EXTRA_SRCS</literal>
                  <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
                </term>
		  <listitem>
		  <para>Set to a list of extra source files (perhaps
		  in directories not listed in
		  <literal>ALL_DIRS</literal>) that should be
		  considered.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>

	    <para>The results of the automatic source file search are
	    placed in the following make variables:</para>

	    <variablelist>
	      <varlistentry>
		<term><literal>SRCS</literal>
                  <indexterm><primary><literal>SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>All source files found, sorted and without
		  duplicates, including those which might not exist
		  yet but will be derived from other existing sources.
		  <literal>SRCS</literal> <emphasis>can</emphasis> be
		  overriden if necessary, in which case the variables
		  below will follow suit.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>HS_SRCS</literal>
                  <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>all Haskell source files in the current
                  directory, including those derived from other source
                  files (eg. Happy sources also give rise to Haskell
                  sources).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>HS_OBJS</literal>
                  <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Object files derived from
		  <literal>HS_SRCS</literal>.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>HS_IFACES</literal>
                  <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Interface files (<literal>.hi</literal> files)
		  derived from <literal>HS_SRCS</literal>.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>C_SRCS</literal>
		<indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>All C source files found.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>C_OBJS</literal>
		<indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>Object files derived from
		  <literal>C_SRCS</literal>.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>SCRIPT_SRCS</literal>
		<indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>All script source files found
		  (<literal>.lprl</literal> files).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>SCRIPT_OBJS</literal>
		<indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para><quote>object</quote> files derived from
		  <literal>SCRIPT_SRCS</literal>
		  (<literal>.prl</literal> files).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>HSC_SRCS</literal>
		<indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>All <literal>hsc2hs</literal> source files
		  (<literal>.hsc</literal> files).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>HAPPY_SRCS</literal>
		<indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
                </term>
		<listitem>
		  <para>All <literal>happy</literal> source files
		  (<literal>.y</literal> or <literal>.hy</literal> files).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>OBJS</literal>
		<indexterm><primary>OBJS</primary></indexterm>
                </term>
		<listitem>
		  <para>the concatenation of
		  <literal>&dollar;(HS_OBJS)</literal>,
		  <literal>&dollar;(C_OBJS)</literal>, and
		  <literal>&dollar;(SCRIPT_OBJS)</literal>.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>

	    <para>Any or all of these definitions can easily be
            overriden by giving new definitions in your
            <filename>Makefile</filename>.</para>

	    <para>What, exactly, does <filename>paths.mk</filename>
            consider a <quote>source file</quote> to be?  It's based
            on the file's suffix (e.g. <filename>.hs</filename>,
            <filename>.lhs</filename>, <filename>.c</filename>,
            <filename>.hy</filename>, etc), but this is the kind of
            detail that changes, so rather than enumerate the source
            suffices here the best thing to do is to look in
            <filename>paths.mk</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><filename>opts.mk</filename>
            <indexterm><primary>opts.mk</primary></indexterm>
          </term>
	  <listitem>
	    <para>defines <command>make</command> variables for option
            strings to pass to each program. For example, it defines
            <constant>HC&lowbar;OPTS</constant><indexterm><primary>HC&lowbar;OPTS</primary></indexterm>,
            the option strings to pass to the Haskell compiler.  See
            <xref linkend="sec-suffix">.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><filename>suffix.mk</filename>
            <indexterm><primary>suffix.mk</primary></indexterm>
          </term>
	  <listitem>
	    <para>defines standard pattern rules&mdash;see <xref
	    linkend="sec-suffix">.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Any of the variables and pattern rules defined by the
      boilerplate file can easily be overridden in any particular
      <filename>Makefile</filename>, because the boilerplate
      <literal>include</literal> comes first.  Definitions after this
      <literal>include</literal> directive simply override the default
      ones in <filename>boilerplate.mk</filename>.</para>
    </sect2>

    <sect2 id="sec-suffix">
      <title>Pattern rules and options</title>
      <indexterm><primary>Pattern rules</primary></indexterm>

      <para>The file
      <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
      defines standard <emphasis>pattern rules</emphasis> that say how
      to build one kind of file from another, for example, how to
      build a <filename>.o</filename> file from a
      <filename>.c</filename> file.  (GNU <command>make</command>'s
      <emphasis>pattern rules</emphasis> are more powerful and easier
      to use than Unix <command>make</command>'s <emphasis>suffix
      rules</emphasis>.)</para>

      <para>Almost all the rules look something like this:</para>

<programlisting>%.o : %.c
      $(RM) $@
      $(CC) $(CC_OPTS) -c $&#60; -o $@</programlisting>

      <para>Here's how to understand the rule.  It says that
      <emphasis>something</emphasis><filename>.o</filename> (say
      <filename>Foo.o</filename>) can be built from
      <emphasis>something</emphasis><filename>.c</filename>
      (<filename>Foo.c</filename>), by invoking the C compiler (path
      name held in <constant>&dollar;(CC)</constant>), passing to it
      the options <constant>&dollar;(CC&lowbar;OPTS)</constant> and
      the rule's dependent file of the rule
      <literal>&dollar;&lt;</literal> (<filename>Foo.c</filename> in
      this case), and putting the result in the rule's target
      <literal>&dollar;@</literal> (<filename>Foo.o</filename> in this
      case).</para>

      <para>Every program is held in a <command>make</command>
      variable defined in <filename>mk/config.mk</filename>&mdash;look
      in <filename>mk/config.mk</filename> for the complete list.  One
      important one is the Haskell compiler, which is called
      <constant>&dollar;(HC)</constant>.</para>

      <para>Every program's options are are held in a
      <command>make</command> variables called
      <constant>&lt;prog&gt;&lowbar;OPTS</constant>.  the
      <constant>&lt;prog&gt;&lowbar;OPTS</constant> variables are
      defined in <filename>mk/opts.mk</filename>.  Almost all of them
      are defined like this:</para>

<programlisting>CC_OPTS = \
  $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>

      <para>The four variables from which
       <constant>CC&lowbar;OPTS</constant> is built have the following
      meaning:</para>

      <variablelist>
	<varlistentry>
	  <term><constant>SRC&lowbar;CC&lowbar;OPTS</constant><indexterm><primary>SRC&lowbar;CC&lowbar;OPTS</primary></indexterm>:</term>
	  <listitem>
	    <para>options passed to all C compilations.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>WAY&lowbar;&lt;way&gt;&lowbar;CC&lowbar;OPTS</constant>:</term>
	  <listitem>
	    <para>options passed to C compilations for way
            <literal>&lt;way&gt;</literal>. For example,
            <constant>WAY&lowbar;mp&lowbar;CC&lowbar;OPTS</constant>
            gives options to pass to the C compiler when compiling way
            <literal>mp</literal>.  The variable
            <constant>WAY&lowbar;CC&lowbar;OPTS</constant> holds
            options to pass to the C compiler when compiling the
            standard way.  (<xref linkend="sec-ways"> dicusses
            multi-way compilation.)</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>&lt;module&gt;&lowbar;CC&lowbar;OPTS</constant>:</term>
	  <listitem>
	    <para>options to pass to the C compiler that are specific
            to module <literal>&lt;module&gt;</literal>.  For example,
            <constant>SMap&lowbar;CC&lowbar;OPTS</constant> gives the
            specific options to pass to the C compiler when compiling
            <filename>SMap.c</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>EXTRA&lowbar;CC&lowbar;OPTS</constant><indexterm><primary>EXTRA&lowbar;CC&lowbar;OPTS</primary></indexterm>:</term>
	  <listitem>
	    <para>extra options to pass to all C compilations.  This
            is intended for command line use, thus:</para>

<programlisting>gmake libHS.a EXTRA_CC_OPTS="-v"</programlisting>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="sec-targets">
      <title>The main <filename>mk/target.mk</filename> file</title>
      <indexterm><primary>target.mk</primary></indexterm>

      <para><filename>target.mk</filename> contains canned rules for
      all the standard targets described in <xref
      linkend="sec-standard-targets">.  It is complicated by the fact
      that you don't want all of these rules to be active in every
      <filename>Makefile</filename>.  Rather than have a plethora of
      tiny files which you can include selectively, there is a single
      file, <filename>target.mk</filename>, which selectively includes
      rules based on whether you have defined certain variables in
      your <filename>Makefile</filename>.  This section explains what
      rules you get, what variables control them, and what the rules
      do.  Hopefully, you will also get enough of an idea of what is
      supposed to happen that you can read and understand any weird
      special cases yourself.</para>

      <variablelist>
	<varlistentry>
	  <term><constant>HS&lowbar;PROG</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>.</term>
	  <listitem>
	    <para>If <constant>HS&lowbar;PROG</constant> is defined,
            you get rules with the following targets:</para>

	    <variablelist>
	      <varlistentry>
		<term><filename>HS&lowbar;PROG</filename><indexterm><primary>HS&lowbar;PROG</primary></indexterm></term>
		<listitem>
		  <para>itself.  This rule links
                  <constant>&dollar;(OBJS)</constant> with the Haskell
                  runtime system to get an executable called
                  <constant>&dollar;(HS&lowbar;PROG)</constant>.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
		<listitem>
		  <para>installs
                  <constant>&dollar;(HS&lowbar;PROG)</constant> in
                  <constant>&dollar;(bindir)</constant>.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>

	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>C&lowbar;PROG</constant><indexterm><primary>C&lowbar;PROG</primary></indexterm></term>
	  <listitem>
	    <para>is similar to <constant>HS&lowbar;PROG</constant>,
            except that the link step links
            <constant>&dollar;(C&lowbar;OBJS)</constant> with the C
            runtime system.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
	  <listitem>
	    <para>is similar to <constant>HS&lowbar;PROG</constant>,
            except that it links
            <constant>&dollar;(LIB&lowbar;OBJS)</constant> to make the
            library archive <constant>&dollar;(LIBRARY)</constant>,
            and <literal>install</literal> installs it in
            <constant>&dollar;(libdir)</constant>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>LIB&lowbar;DATA</constant><indexterm><primary>LIB&lowbar;DATA</primary></indexterm></term>
	  <listitem>
	    <para>&hellip;</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>LIB&lowbar;EXEC</constant><indexterm><primary>LIB&lowbar;EXEC</primary></indexterm></term>
	  <listitem>
	    <para>&hellip;</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><constant>HS&lowbar;SRCS</constant><indexterm><primary>HS&lowbar;SRCS</primary></indexterm>, <constant>C&lowbar;SRCS</constant><indexterm><primary>C&lowbar;SRCS</primary></indexterm>.</term>
	  <listitem>
	    <para>If <constant>HS&lowbar;SRCS</constant> is defined
            and non-empty, a rule for the target
            <literal>depend</literal> is included, which generates
            dependency information for Haskell programs.  Similarly
            for <constant>C&lowbar;SRCS</constant>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>All of these rules are &ldquo;double-colon&rdquo; rules,
      thus</para>

<programlisting>install :: $(HS_PROG)
      ...how to install it...</programlisting>

      <para>GNU <command>make</command> treats double-colon rules as
      separate entities.  If there are several double-colon rules for
      the same target it takes each in turn and fires it if its
      dependencies say to do so.  This means that you can, for
      example, define both <constant>HS&lowbar;PROG</constant> and
      <constant>LIBRARY</constant>, which will generate two rules for
      <literal>install</literal>.  When you type <command>gmake
      install</command> both rules will be fired, and both the program
      and the library will be installed, just as you wanted.</para>
    </sect2>

    <sect2 id="sec-subdirs">
      <title>Recursion</title>
      <indexterm><primary>recursion, in makefiles</primary></indexterm>
      <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>

      <para>In leaf <filename>Makefile</filename>s the variable
      <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
      is undefined.  In non-leaf <filename>Makefile</filename>s,
      <constant>SUBDIRS</constant> is set to the list of
      sub-directories that contain subordinate
      <filename>Makefile</filename>s.  <emphasis>It is up to you to
      set <constant>SUBDIRS</constant> in the
      <filename>Makefile</filename>.</emphasis> There is no automation
      here&mdash;<constant>SUBDIRS</constant> is too important to
      automate.</para>

      <para>When <constant>SUBDIRS</constant> is defined,
      <filename>target.mk</filename> includes a rather neat rule for
      the standard targets (<xref linkend="sec-standard-targets"> that
      simply invokes <command>make</command> recursively in each of
      the sub-directories.</para>

      <para><emphasis>These recursive invocations are guaranteed to
      occur in the order in which the list of directories is specified
      in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
      be important.  For example, when you say <command>gmake
      boot</command> it can be important that the recursive invocation
      of <command>make boot</command> is done in one sub-directory
      (the include files, say) before another (the source files).
      Generally, put the most independent sub-directory first, and the
      most dependent last.</para>
    </sect2>

    <sect2 id="sec-ways">
      <title>Way management</title>
      <indexterm><primary>way management</primary></indexterm>

      <para>We sometimes want to build essentially the same system in
      several different &ldquo;ways&rdquo;.  For example, we want to build GHC's
      <literal>Prelude</literal> libraries with and without profiling,
      so that there is an appropriately-built library archive to link
      with when the user compiles his program.  It would be possible
      to have a completely separate build tree for each such &ldquo;way&rdquo;,
      but it would be horribly bureaucratic, especially since often
      only parts of the build tree need to be constructed in multiple
      ways.</para>

      <para>Instead, the
      <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
      contains some clever magic to allow you to build several
      versions of a system; and to control locally how many versions
      are built and how they differ.  This section explains the
      magic.</para>

      <para>The files for a particular way are distinguished by
      munging the suffix.  The <quote>normal way</quote> is always
      built, and its files have the standard suffices
      <filename>.o</filename>, <filename>.hi</filename>, and so on.
      In addition, you can build one or more extra ways, each
      distinguished by a <emphasis>way tag</emphasis>.  The object
      files and interface files for one of these extra ways are
      distinguished by their suffix.  For example, way
      <literal>mp</literal> has files
      <filename>.mp&lowbar;o</filename> and
      <filename>.mp&lowbar;hi</filename>.  Library archives have their
      way tag the other side of the dot, for boring reasons; thus,
      <filename>libHS&lowbar;mp.a</filename>.</para>

      <para>A <command>make</command> variable called
      <constant>way</constant> holds the current way tag.
      <emphasis><constant>way</constant> is only ever set on the
      command line of <command>gmake</command></emphasis> (usually in
      a recursive invocation of <command>gmake</command> by the
      system).  It is never set inside a
      <filename>Makefile</filename>.  So it is a global constant for
      any one invocation of <command>gmake</command>.  Two other
      <command>make</command> variables,
      <constant>way&lowbar;</constant> and
      <constant>&lowbar;way</constant> are immediately derived from
      <constant>&dollar;(way)</constant> and never altered.  If
      <constant>way</constant> is not set, then neither are
      <constant>way&lowbar;</constant> and
      <constant>&lowbar;way</constant>, and the invocation of
      <command>make</command> will build the <quote>normal
      way</quote>.  If <constant>way</constant> is set, then the other
      two variables are set in sympathy.  For example, if
      <constant>&dollar;(way)</constant> is &ldquo;<literal>mp</literal>&rdquo;,
      then <constant>way&lowbar;</constant> is set to
      &ldquo;<literal>mp&lowbar;</literal>&rdquo; and
      <constant>&lowbar;way</constant> is set to
      &ldquo;<literal>&lowbar;mp</literal>&rdquo;.  These three variables are
      then used when constructing file names.</para>

      <para>So how does <command>make</command> ever get recursively
      invoked with <constant>way</constant> set?  There are two ways
      in which this happens:</para>

      <itemizedlist>
	<listitem>
	  <para>For some (but not all) of the standard targets, when
          in a leaf sub-directory, <command>make</command> is
          recursively invoked for each way tag in
          <constant>&dollar;(WAYS)</constant>.  You set
          <constant>WAYS</constant> in the
          <filename>Makefile</filename> to the list of way tags you
          want these targets built for.  The mechanism here is very
          much like the recursive invocation of
          <command>make</command> in sub-directories (<xref
          linkend="sec-subdirs">).  It is up to you to set
          <constant>WAYS</constant> in your
          <filename>Makefile</filename>; this is how you control what
          ways will get built.</para>
	</listitem>

	<listitem>
	  <para>For a useful collection of targets (such as
          <filename>libHS&lowbar;mp.a</filename>,
          <filename>Foo.mp&lowbar;o</filename>) there is a rule which
          recursively invokes <command>make</command> to make the
          specified target, setting the <constant>way</constant>
          variable.  So if you say <command>gmake
          Foo.mp&lowbar;o</command> you should see a recursive
          invocation <command>gmake Foo.mp&lowbar;o way=mp</command>,
          and <emphasis>in this recursive invocation the pattern rule
          for compiling a Haskell file into a <filename>.o</filename>
          file will match</emphasis>.  The key pattern rules (in
          <filename>suffix.mk</filename>) look like this:

<programlisting>%.$(way_)o : %.lhs
      $(HC) $(HC_OPTS) $&#60; -o $@</programlisting>

          Neat, eh?</para>
	</listitem>

	<listitem>
	  <para>You can invoke <command>make</command> with a
	  particular <literal>way</literal> setting yourself, in order
	  to build files related to a particular
	  <literal>way</literal> in the current directory.  eg.

<screen>$ make way=p</screen>

          will build files for the profiling way only in the current
          directory. </para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>When the canned rule isn't right</title>

      <para>Sometimes the canned rule just doesn't do the right thing.
      For example, in the <literal>nofib</literal> suite we want the
      link step to print out timing information.  The thing to do here
      is <emphasis>not</emphasis> to define
      <constant>HS&lowbar;PROG</constant> or
      <constant>C&lowbar;PROG</constant>, and instead define a special
      purpose rule in your own <filename>Makefile</filename>.  By
      using different variable names you will avoid the canned rules
      being included, and conflicting with yours.</para>
    </sect2>
  </sect1>

  <sect1 id="building-docs">
    <title>Building the documentation</title>

    <sect2 id="pre-supposed-doc-tools">
      <title>Tools for building the Documentation</title>

      <para>The following additional tools are required if you want to
      format the documentation that comes with the
      <literal>fptools</literal> projects:</para>
      
      <variablelist>
	<varlistentry>
	  <term>DocBook
            <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
            <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
          </term>
	  <listitem>
	    <para>Much of our documentation is written in SGML, using
            the DocBook DTD.  Instructions on installing and
            configuring the DocBook tools are below.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>TeX
            <indexterm><primary>pre-supposed: TeX</primary></indexterm>
            <indexterm><primary>TeX, pre-supposed</primary></indexterm>
          </term>
	  <listitem>
	    <para>A decent TeX distribution is required if you want to
            produce printable documentation.  We recomment teTeX,
            which includes just about everything you need.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Haddock
            <indexterm><primary>Haddock</primary></indexterm>
          </term>
	  <listitem>
	    <para>Haddock is a Haskell documentation tool that we use
	    for automatically generating documentation from the
	    library source code.  It is an <literal>fptools</literal>
	    project in itself.  To build documentation for the
	    libraries (<literal>fptools/libraries</literal>) you
	    should check out and build Haddock in
	    <literal>fptools/haddock</literal>.  Haddock requires GHC
	    to build.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2>
      <title>Installing the DocBook tools</title>

      <sect3>
	<title>Installing the DocBook tools on Linux</title>

	<para>If you're on a recent RedHat system (7.0+), you probably
        have working DocBook tools already installed.  The configure
        script should detect your setup and you're away.</para>

	<para>If you don't have DocBook tools installed, and you are
        using a system that can handle RedHat RPM packages, you can
        probably use the <ulink
        url="http://sourceware.cygnus.com/docbook-tools/">Cygnus
        DocBook tools</ulink>, which is the most shrink-wrapped SGML
        suite that we could find. You need all the RPMs except for
        psgml (i.e.  <filename>docbook</filename>,
        <filename>jade</filename>, <filename>jadetex</filename>,
        <filename>sgmlcommon</filename> and
        <filename>stylesheets</filename>). Note that most of these
        RPMs are architecture neutral, so are likely to be found in a
        <filename>noarch</filename> directory. The SuSE RPMs also
        work; the RedHat ones <emphasis>don't</emphasis> in RedHat 6.2
        (7.0 and later should be OK), but they are easy to fix: just
        make a symlink from
        <filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</filename>
        to <filename>/usr/lib/sgml/lib/dblib.dsl</filename>. </para>
      </sect3>
    
      <sect3>
	<title>Installing DocBook on FreeBSD</title>

	<para>On FreeBSD systems, the easiest way to get DocBook up
        and running is to install it from the ports tree or a
        pre-compiled package (packages are available from your local
        FreeBSD mirror site).</para>

	<para>To use the ports tree, do this:
<screen>$ cd /usr/ports/textproc/docproj
$ make install</screen>
        This installs the FreeBSD documentation project tools, which
        includes everything needed to format the GHC
        documentation.</para>
      </sect3>

      <sect3>
	<title>Installing from binaries on Windows</title>
	
	<para>It's a good idea to use Norman Walsh's <ulink
        url="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
        notes</ulink> as a guide. You should get version 3.1 of
        DocBook, and note that his file <filename>test.sgm</filename>
        won't work, as it needs version 3.0. You should unpack Jade
        into <filename>\Jade</filename>, along with the entities,
        DocBook into <filename>\docbook</filename>, and the DocBook
        stylesheets into <filename>\docbook\stylesheets</filename> (so
        they actually end up in
        <filename>\docbook\stylesheets\docbook</filename>).</para>
      </sect3>


      <sect3>
	<title>Installing the DocBook tools from source</title>

	<sect4>
	  <title>Jade</title>

	  <para>Install <ulink
          url="http://openjade.sourceforge.net/">OpenJade</ulink>
          (Windows binaries are available as well as sources). If you
          want DVI, PS, or PDF then install JadeTeX from the
          <filename>dsssl</filename> subdirectory. (If you get the
          error:

<screen>! LaTeX Error: Unknown option implicit=false' for package hyperref'.</screen>

          your version of <command>hyperref</command> is out of date;
          download it from CTAN
          (<filename>macros/latex/contrib/supported/hyperref</filename>),
          and make it, ensuring that you have first removed or renamed
          your old copy. If you start getting file not found errors
          when making the test for <command>hyperref</command>, you
          can abort at that point and proceed straight to
          <command>make install</command>, or enter them as
          <filename>../</filename><emphasis>filename</emphasis>.)</para>

	  <para>Make links from <filename>virtex</filename> to
          <filename>jadetex</filename> and
          <filename>pdfvirtex</filename> to
          <filename>pdfjadetex</filename> (otherwise DVI, PostScript
          and PDF output will not work). Copy
          <filename>dsssl/*.{dtd,dsl}</filename> and
          <filename>catalog</filename> to
          <filename>/usr/[local/]lib/sgml</filename>.</para>
	</sect4>

	<sect4>
	  <title>DocBook and the DocBook stylesheets</title>

	  <para>Get a Zip of <ulink
          url="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ulink>
          and install the contents in
          <filename>/usr/[local/]/lib/sgml</filename>.</para>

	  <para>Get the <ulink
          url="http://nwalsh.com/docbook/dsssl/">DocBook
          stylesheets</ulink> and install in
          <filename>/usr/[local/]lib/sgml/stylesheets</filename>
          (thereby creating a subdirectory docbook). For indexing,
          copy or link <filename>collateindex.pl</filename> from the
          DocBook stylesheets archive in <filename>bin</filename> into
          a directory on your <constant>PATH</constant>.</para>

	  <para>Download the <ulink
          url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
          entities</ulink> into
          <filename>/usr/[local/]lib/sgml</filename>.</para>
	</sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>Configuring the DocBook tools</title>

      <para>Once the DocBook tools are installed, the configure script
      will detect them and set up the build system accordingly. If you
      have a system that isn't supported, let us know, and we'll try
      to help.</para>
    </sect2>

    <sect2>
      <title>Remaining problems</title>

      <para>If you install from source, you'll get a pile of warnings
      of the form

<screen>DTDDECL catalog entries are not supported</screen>

      every time you build anything. These can safely be ignored, but
      if you find them tedious you can get rid of them by removing all
      the <constant>DTDDECL</constant> entries from
      <filename>docbook.cat</filename>.</para>
    </sect2>

    <sect2>
      <title>Building the documentation</title>

      <para>To build documentation in a certain format, you can
      say, for example,</para>

<screen>$ make html</screen>

      <para>to build HTML documentation below the current directory.
      The available formats are: <literal>dvi</literal>,
      <literal>ps</literal>, <literal>pdf</literal>,
      <literal>html</literal>, and <literal>rtf</literal>.  Note that
      not all documentation can be built in all of these formats: HTML
      documentation is generally supported everywhere, and DocBook
      documentation might support the other formats (depending on what
      other tools you have installed).</para>

      <para>All of these targets are recursive; that is, saying
      <literal>make html</literal> will make HTML docs for all the
      documents recursively below the current directory.</para>

      <para>Because there are many different formats that the DocBook
      documentation can be generated in, you have to select which ones
      you want by setting the <literal>SGMLDocWays</literal> variable
      to a list of them.  For example, in
      <filename>build.mk</filename> you might have a line:</para>

<screen>SGMLDocWays = html ps</screen>

      <para>This will cause the documentation to be built in the requested
      formats as part of the main build (the default is not to build
      any documentation at all).</para>
    </sect2>

    <sect2>
      <title>Installing the documentation</title>

      <para>To install the documentation, use:</para>

<screen>$ make install-docs</screen>

      <para>This will install the documentation into
      <literal>$(datadir)</literal> (which defaults to
      <literal>$(prefix)/share</literal>).  The exception is HTML
      documentation, which goes into
      <literal>$(datadir)/html</literal>, to keep things tidy.</para>

      <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
      to a list of formats, the <literal>install-docs</literal> target
      won't do anything for SGML documentation.</para>
    </sect2>

  </sect1>
    

  <sect1 id="sec-porting-ghc">
    <title>Porting GHC</title>

    <para>This section describes how to port GHC to a currenly
    unsupported platform.  There are two distinct
    possibilities:</para>

    <itemizedlist>
      <listitem>
	<para>The hardware architecture for your system is already
	supported by GHC, but you're running an OS that isn't
	supported (or perhaps has been supported in the past, but
	currently isn't).  This is the easiest type of porting job,
	but it still requires some careful bootstrapping.  Proceed to
	<xref linkend="sec-booting-from-hc">.</para>
      </listitem>
      
      <listitem>
	<para>Your system's hardware architecture isn't supported by
	GHC.  This will be a more difficult port (though by comparison
	perhaps not as difficult as porting gcc).  Proceed to <xref
	linkend="unregisterised-porting">.</para>
      </listitem>
    </itemizedlist>
    
    <sect2 id="sec-booting-from-hc">
      <title>Booting/porting from C (<filename>.hc</filename>) files</title>

      <indexterm><primary>building GHC from .hc files</primary></indexterm>
      <indexterm><primary>booting GHC from .hc files</primary></indexterm>
      <indexterm><primary>porting GHC</primary></indexterm>

      <para>Bootstrapping GHC on a system without GHC already
      installed is achieved by taking the intermediate C files (known
      as HC files) from a GHC compilation on a supported system to the
      target machine, and compiling them using gcc to get a working
      GHC.</para>

      <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
      from C.  We recommend using GHC 6.0.1 or
      later.</emphasis></para>

      <para>HC files are platform-dependent, so you have to get a set
      that were generated on similar hardware.  There may be some
      supplied on the GHC download page, otherwise you'll have to
      compile some up yourself, or start from
      <emphasis>unregisterised</emphasis> HC files - see <xref
      linkend="unregisterised-porting">.</para>

      <para>The following steps should result in a working GHC build
      with full libraries:</para>

      <itemizedlist>
	<listitem>
	  <para>Unpack the HC files on top of a fresh source tree
          (make sure the source tree version matches the version of
          the HC files <emphasis>exactly</emphasis>!).  This will
          place matching <filename>.hc</filename> files next to the
          corresponding Haskell source (<filename>.hs</filename> or
          <filename>.lhs</filename>) in the compiler subdirectory
          <filename>ghc/compiler</filename> and in the libraries
          (subdirectories of <filename>hslibs</filename> and
          <literal>libraries</literal>).</para>
	</listitem>

	<listitem>
	  <para>The actual build process is fully automated by the
          <filename>hc-build</filename> script located in the
          <filename>distrib</filename> directory.  If you eventually
          want to install GHC into the directory
          <replaceable>dir</replaceable>, the following
          command will execute the whole build process (it won't
          install yet):</para>

<screen>foo% distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
<indexterm><primary>--hc-build</primary></indexterm>

	  <para>By default, the installation directory is
          <filename>/usr/local</filename>.  If that is what you want,
          you may omit the argument to <filename>hc-build</filename>.
          Generally, any option given to <filename>hc-build</filename>
          is passed through to the configuration script
          <filename>configure</filename>.  If
          <filename>hc-build</filename> successfully completes the
          build process, you can install the resulting system, as
          normal, with</para>

<screen>foo% make install</screen>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="unregisterised-porting">
      <title>Porting GHC to a new architecture</title>
      
      <para>The first step in porting to a new architecture is to get
      an <firstterm>unregisterised</firstterm> build working.  An
      unregisterised build is one that compiles via vanilla C only.
      By contrast, a registerised build uses the following
      architecture-specific hacks for speed:</para>

      <itemizedlist>
	<listitem>
	  <para>Global register variables: certain abstract machine
	  <quote>registers</quote> are mapped to real machine
	  registers, depending on how many machine registers are
	  available (see
	  <filename>ghc/includes/MachRegs.h</filename>).</para>
	</listitem>

	<listitem>
	  <para>Assembly-mangling: when compiling via C, we feed the
	  assembly generated by gcc though a Perl script known as the
	  <firstterm>mangler</firstterm> (see
	  <filename>ghc/driver/mangler/ghc-asm.lprl</filename>).  The
	  mangler rearranges the assembly to support tail-calls and
	  various other optimisations.</para>
	</listitem>
      </itemizedlist>

      <para>In an unregisterised build, neither of these hacks are
      used &mdash; the idea is that the C code generated by the
      compiler should compile using gcc only.  The lack of these
      optimisations costs about a factor of two in performance, but
      since unregisterised compilation is usually just a step on the
      way to a full registerised port, we don't mind too much.</para>

      <para>Notes on GHC portability in general: we've tried to stick
      to writing portable code in most parts of the system, so it
      should compile on any POSIXish system with gcc, but in our
      experience most systems differ from the standards in one way or
      another.  Deal with any problems as they arise - if you get
      stuck, ask the experts on
      <email>glasgow-haskell-users@haskell.org</email>.</para>
	
      <para>Lots of useful information about the innards of GHC is
      available in the <ulink
      url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
      Commentary</ulink>, which might be helpful if you run into some
      code which needs tweaking for your system.</para>

      <sect3>
	<title>Cross-compiling to produce an unregisterised GHC</title>

	<para>In this section, we explain how to bootstrap GHC on a
	new platform, using unregisterised intermediate C files.  We
	haven't put a great deal of effort into automating this
	process, for two reasons: it is done very rarely, and the
	process usually requires human intervention to cope with minor
	porting issues anyway.</para>

	<para>The following step-by-step instructions should result in
	a fully working, albeit unregisterised, GHC.  Firstly, you
	need a machine that already has a working GHC (we'll call this
	the <firstterm>host</firstterm> machine), in order to
	cross-compile the intermediate C files that we will use to
	bootstrap the compiler on the <firstterm>target</firstterm>
	machine.</para>

	<itemizedlist>
	  <listitem>
	    <para>On the target machine:</para>

	  <itemizedlist>
	    <listitem>
	      <para>Unpack a source tree (preferably a released
	      version).  We will call the path to the root of this
	      tree <replaceable>T</replaceable>.</para>
	    </listitem>

	    <listitem>
<screen>$ cd <replaceable>T</replaceable>
$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>

	      <para>You might need to update
              <filename>configure.in</filename> to recognise the new
              architecture, and re-generate
              <filename>configure</filename> with
              <literal>autoreconf</literal>.</para>
	    </listitem>
  
	    <listitem>
<screen>$ cd <replaceable>T</replaceable>/ghc/includes
$ make config.h</screen>
	    </listitem>
	  </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>On the host machine:</para>
	      
	  <itemizedlist>
	    <listitem>
	      <para>Unpack a source tree (same released version).  Call
              this directory <replaceable>H</replaceable>.</para>
	    </listitem>
 
	    <listitem>
<screen>$ cd <replaceable>H</replaceable>
$ ./configure</screen>
	    </listitem>

	    <listitem>
	      <para>Create
	      <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
	      with the following contents:</para>

<programlisting>GhcUnregisterised = YES
GhcLibHcOpts = -O -H32m -keep-hc-files
GhcLibWays =
SplitObjs = NO
GhcWithNativeCodeGen = NO
GhcWithInterpreter = NO
GhcStage1HcOpts = -O -H32m -fasm
GhcStage2HcOpts = -O -fvia-C -keep-hc-files</programlisting>
	    </listitem>

	    <listitem>
	      <para>Edit
	      <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
	      <itemizedlist>
		<listitem>
		  <para>change <literal>TARGETPLATFORM</literal>
                  appropriately, and set the variables involving
                  <literal>TARGET</literal> to the correct values for
                  the target platform.  This step is necessary because
                  currently <literal>configure</literal> doesn't cope
                  with specifying different values for the
                  <literal>--host</literal> and
                  <literal>--target</literal> flags.</para>
		</listitem>
		<listitem>
		  <para>copy <literal>LeadingUnderscore</literal>
		  setting from target.</para>
		</listitem>
	      </itemizedlist>
	    </listitem>

	    <listitem>
	      <para>Copy
	      <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
	      to
	      <filename><replaceable>H</replaceable>/ghc/includes</filename>.
	      Note that we are building on the host machine, using the
	      target machine's <literal>config.h</literal> file.  This
	      is so that the intermediate C files generated here will
	      be suitable for compiling on the target system.</para>

	    </listitem>

	      <listitem>
		<para>Touch <literal>config.h</literal>, just to make
		sure it doesn't get replaced during the build:</para>
<screen>$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
	      </listitem>

	    <listitem>
		<para>Now build the compiler:</para>
<screen>$ cd <replaceable>H</replaceable>/glafp-utils &amp;&amp; make boot &amp;&amp; make
$ cd <replaceable>H</replaceable>/ghc &amp;&amp; make boot &amp;&amp; make</screen>
	      <para>Don't worry if the build falls over in the RTS, we
              don't need the RTS yet.</para>
	    </listitem>

	    <listitem>
<screen>$ cd <replaceable>H</replaceable>/libraries
$ make boot &amp;&amp; make</screen>
	    </listitem>

	    <listitem>
<screen>$ cd <replaceable>H</replaceable>/ghc
$ make boot stage=2 &amp;&amp; make stage=2</screen>
	    </listitem>
	    
	    <listitem>
<screen>$ cd <replaceable>H</replaceable>/ghc/utils
$ make clean
$ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
		EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
	    </listitem>
	    
	    <listitem>
<screen>$ cd <replaceable>H</replaceable>
$ make hc-file-bundle Project=Ghc</screen>
	    </listitem>

	    <listitem>
	      <para>copy
	      <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
	      to <filename><replaceable>T</replaceable>/..</filename>.</para>
	    </listitem>
	  </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>On the target machine:</para>

	    <para>At this stage we simply need to bootstrap a compiler
	    from the intermediate C files we generated above.  The
	    process of bootstrapping from C files is automated by the
	    script in <literal>distrib/hc-build</literal>, and is
	    described in <xref linkend="sec-booting-from-hc">.</para>

<screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>

	    <para>However, since this is a bootstrap on a new machine,
	    the automated process might not run to completion the
	    first time.  For that reason, you might want to treat the
	    <literal>hc-build</literal> script as a list of
	    instructions to follow, rather than as a fully automated
	    script.  This way you'll be able to restart the process
	    part-way through if you need to fix anything on the
	    way.</para>

	    <para>Don't bother with running
	    <literal>make&nbsp;install</literal> in the newly
	    bootstrapped tree; just use the compiler in that tree to
	    build a fresh compiler from scratch, this time without
	    booting from C files.  Before doing this, you might want
	    to check that the bootstrapped compiler is generating
	    working binaries:</para>

<screen>$ cat >hello.hs
main = putStrLn "Hello World!\n"
^D
$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
$ ./hello
Hello World!</screen>

	    <para>Once you have the unregisterised compiler up and
	    running, you can use it to start a registerised port.  The
	    following sections describe the various parts of the
	    system that will need architecture-specific tweaks in
	    order to get a registerised build going.</para>

	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Porting the RTS</title>
	
	<para>The following files need architecture-specific code for a
	registerised build:</para>

	<variablelist>
	  <varlistentry>
	    <term><filename>ghc/includes/MachRegs.h</filename>
	    <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
            </term>
	    <listitem>
	      <para>Defines the STG-register to machine-register
	      mapping.  You need to know your platform's C calling
	      convention, and which registers are generally available
	      for mapping to global register variables.  There are
	      plenty of useful comments in this file.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>ghc/includes/TailCalls.h</filename>
	    <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
            </term>
	    <listitem>
	      <para>Macros that cooperate with the mangler (see <xref
	      linkend="sec-mangler">) to make proper tail-calls
	      work.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>ghc/rts/Adjustor.c</filename>
	    <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
            </term>
	    <listitem>
	      <para>Support for
	      <literal>foreign&nbsp;import&nbsp;"wrapper"</literal>
	      (aka
	      <literal>foreign&nbsp;export&nbsp;dynamic</literal>).
	      Not essential for getting GHC bootstrapped, so this file
	      can be deferred until later if necessary.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>ghc/rts/StgCRun.c</filename>
	    <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
            </term>
	    <listitem>
	      <para>The little assembly layer between the C world and
	      the Haskell world.  See the comments and code for the
	      other architectures in this file for pointers.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>ghc/rts/MBlock.h</filename>
              <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
            </term>
	    <term><filename>ghc/rts/MBlock.c</filename>
              <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
            </term>
	    <listitem>
	      <para>These files are really OS-specific rather than
	      architecture-specific.  In <filename>MBlock.h</filename>
	      is specified the absolute location at which the RTS
	      should try to allocate memory on your platform (try to
	      find an area which doesn't conflict with code or dynamic
	      libraries).  In <filename>Mblock.c</filename> you might
	      need to tweak the call to <literal>mmap()</literal> for
	      your OS.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>

      <sect3 id="sec-mangler">
	<title>The mangler</title>
	
	<para>The mangler is an evil Perl-script
	(<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
	rearranges the assembly code output from gcc to do two main
	things:</para>

	<itemizedlist>
	  <listitem>
	    <para>Remove function prologues and epilogues, and all
	    movement of the C stack pointer.  This is to support
	    tail-calls: every code block in Haskell code ends in an
	    explicit jump, so we don't want the C-stack overflowing
	    while we're jumping around between code blocks.</para>
	  </listitem>
	  <listitem>
	    <para>Move the <firstterm>info table</firstterm> for a
	    closure next to the entry code for that closure.  In
	    unregisterised code, info tables contain a pointer to the
	    entry code, but in registerised compilation we arrange
	    that the info table is shoved right up against the entry
	    code, and addressed backwards from the entry code pointer
	    (this saves a word in the info table and an extra
	    indirection when jumping to the closure entry
	    code).</para>
	  </listitem>
	</itemizedlist>

	<para>The mangler is abstracted to a certain extent over some
	architecture-specific things such as the particular assembler
	directives used to herald symbols.  Take a look at the
	definitions for other architectures and use these as a
	starting point.</para>
      </sect3>

      <sect3>
	<title>The splitter</title>

	<para>The splitter is another evil Perl script
	(<filename>ghc/driver/split/ghc-split.lprl</filename>).  It
	cooperates with the mangler to support object splitting.
	Object splitting is what happens when the
	<option>-split-objs</option> option is passed to GHC: the
	object file is split into many smaller objects.  This feature
	is used when building libraries, so that a program statically
	linked against the library will pull in less of the
	library.</para>

	<para>The splitter has some platform-specific stuff; take a
	look and tweak it for your system.</para>
      </sect3>

      <sect3>
	<title>The native code generator</title>

	<para>The native code generator isn't essential to getting a
	registerised build going, but it's a desirable thing to have
	because it can cut compilation times in half.  The native code
	generator is described in some detail in the <ulink
	url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
	commentary</ulink>.</para>
      </sect3>

      <sect3>
	<title>GHCi</title>

	<para>To support GHCi, you need to port the dynamic linker
	(<filename>fptools/ghc/rts/Linker.c</filename>).  The linker
	currently supports the ELF and PEi386 object file formats - if
	your platform uses one of these then things will be
	significantly easier.  The majority of Unix platforms use the
	ELF format these days.  Even so, there are some
	machine-specific parts of the ELF linker: for example, the
	code for resolving particular relocation types is
	machine-specific, so some porting of this code to your
	architecture will probaly be necessary.</para>
	
	<para>If your system uses a different object file format, then
	you have to write a linker &mdash; good luck!</para>
      </sect3>
    </sect2>

  </sect1>

<sect1 id="sec-build-pitfalls">
<title>Known pitfalls in building Glasgow Haskell

<indexterm><primary>problems, building</primary></indexterm>
<indexterm><primary>pitfalls, in building</primary></indexterm>
<indexterm><primary>building pitfalls</primary></indexterm></title>

<para>
WARNINGS about pitfalls and known &ldquo;problems&rdquo;:
</para>

<para>

<orderedlist>
<listitem>

<para>
One difficulty that comes up from time to time is running out of space
in <literal>TMPDIR</literal>.  (It is impossible for the configuration stuff to
compensate for the vagaries of different sysadmin approaches to temp
space.)
<indexterm><primary>tmp, running out of space in</primary></indexterm>

The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
of choice).

The best way around it is to say

<programlisting>export TMPDIR=&#60;dir&#62;</programlisting>

in your <filename>build.mk</filename> file.
Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
in all cases.


</para>
</listitem>
<listitem>

<para>
In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
in <filename>ghc/lib</filename>, you may get a few C-compiler warnings.  We think these
are OK.

</para>
</listitem>
<listitem>

<para>
When compiling via C, you'll sometimes get &ldquo;warning: assignment from
incompatible pointer type&rdquo; out of GCC.  Harmless.

</para>
</listitem>
<listitem>

<para>
Similarly, <command>ar</command>chiving warning messages like the following are not
a problem:

<screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
...</screen>


</para>
</listitem>
<listitem>

<para>
 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
get an &ldquo;Out of heap space&rdquo; error message.  These can vary with the
vagaries of different systems, it seems.  The solution is simple:


<itemizedlist>
<listitem>

<para>
 If you're compiling with GHC 4.00 or later, then the
<emphasis>maximum</emphasis> heap size must have been reached.  This
is somewhat unlikely, since the maximum is set to 64M by default.
Anyway, you can raise it with the
<option>-optCrts-M&lt;size&gt;</option> flag (add this flag to
<constant>&lt;module&gt;&lowbar;HC&lowbar;OPTS</constant>
<command>make</command> variable in the appropriate
<filename>Makefile</filename>).

</para>
</listitem>
<listitem>

<para>
 For GHC &#60; 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
above.

</para>
</listitem>

</itemizedlist>


and try again: <command>gmake</command>.  (see <xref linkend="sec-suffix"> for information about
<constant>&lt;module&gt;&lowbar;HC&lowbar;OPTS</constant>.)

Alternatively, just cut to the chase:

<screen>% cd ghc/compiler
% make EXTRA_HC_OPTS=-optCrts-M128M</screen>


</para>
</listitem>
<listitem>

<para>
If you try to compile some Haskell, and you get errors from GCC about
lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
mis-installed.  <command>fixincludes</command> wasn't run when it should've been.

As <command>fixincludes</command> is now automagically run as part of GCC installation,
this bug also suggests that you have an old GCC.


</para>
</listitem>
<listitem>

<para>
You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).


<screen>% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
?    ranlib $i
?    # or, on some machines: ar s $i
? end</screen>


We'd be interested to know if this is still necessary.


</para>
</listitem>
<listitem>

<para>
GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
a bit from one Unix to another.  One particular gotcha is macro calls
like this:


<programlisting>SLIT("Hello, world")</programlisting>


Some <command>cpp</command>s treat the comma inside the string as separating two macro
arguments, so you get


<screen>:731: macro `SLIT' used with too many (2) args</screen>


Alas, <command>cpp</command> doesn't tell you the offending file!

Workaround: don't put weird things in string args to <command>cpp</command> macros.
</para>
</listitem>

</orderedlist>

</para>

</sect1>


<sect1 id="platforms"><title>Platforms, scripts, and file names</title>
<para>
GHC is designed both to be built, and to run, on both Unix and Windows.  This flexibility
gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
</para>

<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>

<para> The build system is built around Unix-y makefiles.  Because it's not native,
the Windows situation for building GHC is particularly confusing.  This section
tries to clarify, and to establish terminology.</para>

<sect3 id="ghc-mingw"><title>MinGW</title>

<para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink> 
is a collection of header
files and import libraries that allow one to use <command>gcc</command> and produce
native Win32 programs that do not rely on any third-party DLLs. The
current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
other utilities. 
</para>

<para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
Posix interface.  
</para>
</sect3>

<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>

<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink> 
and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:

<itemizedlist>
<listitem><para>
Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
compile code that has access to all of Posix.  The price is that the executables must be 
dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
that doesn't have Cygwin</emphasis>.  Worse, Cygwin is a moving target.  The name of the main DLL, <literal>cygwin1.dll</literal>
does not change, but the implementation certainly does.  Even the interfaces to functions
it exports seem to change occasionally. </para>
</listitem>

<listitem><para>
MSYS is a fork of the Cygwin tree, so they
are fundamentally similar.  However, MSYS is by design much smaller and simpler.  Access to the file system goes
through fewer layers, so MSYS is quite a bit faster too.
</para>

<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
compile binaries that run with no DLL support, on any Win32 system.
However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>, 
<command>cvs</command>, <command>ssh</command> etc.  To get these, you have to download the 
MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
</para>
<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>, 
<command>ssh</command> and so on),
not by programs compiled under MSYS.
</para></listitem>

</itemizedlist>

</para>
</sect3>

<sect3><title>Targeting MinGW</title>

<para>We want GHC to compile programs that work on any Win32 system.  Hence:
<itemizedlist>
<listitem><para>
GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
invokes the MinGW tools, not the Cygwin ones.  That means that the programs GHC compiles
will work on any system, but it also means that the programs GHC compiles do not have access
to all of Posix.  In particular, they cannot import the (Haskell) Posix 
library; they have to do
their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
</listitem>

<listitem><para>
To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.  
</para></listitem>
</itemizedlist>
So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>, 
that targets Cygwin instead.  The up-side of GHC-cygwin is
that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
</para>

<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about 
how GHC is <emphasis>built</emphasis>.  We use both MSYS and Cygwin as build environments for
GHC; both work fine, though MSYS is rather lighter weight.</para>

<para>In your build tree, you build a compiler called <command>ghc-inplace</command>.  It
uses the <command>gcc</command> that you specify using the
<option>--with-gcc</option> flag when you run
<command>configure</command> (see below).
The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
whatever one happens to be in your path.  However, the makefiles do use whatever <command>ld</command> 
and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
used to glom together .o files into a bigger .o file, or a .a file, 
so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
Cygwin and MinGW use the same .o file format.  So its ok.
</para>
</sect3>

<sect3><title> File names </title>

<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
However:
<itemizedlist>
<listitem><para>
MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
<filename>/c/tmp/foo</filename> etc.  The exact mount table is given in the doc subdirectory of the MSYS distribution.
</para>
<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
directory.  If so, it just invokes it.  If not, it assumes the program is no an MSYS program, and walks over the command-line
arguments changing MSYS paths into native-compatible paths.  It does this inside sub-arguments and inside quotes. For example,
if you invoke
<programlisting>foogle -B/c/tmp/baz</programlisting>
the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
</para></listitem>

<listitem><para>
Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
</para>
<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
</para></listitem>
</itemizedlist>
</para>
</sect3>

<sect3><title>Host System vs Target System</title>

<para>
In the source code you'll find various ifdefs looking like:
<programlisting>#ifdef mingw32_HOST_OS
  ...blah blah...
#endif</programlisting>
and 
<programlisting>#ifdef mingw32_TARGET_OS
  ...blah blah...
#endif</programlisting>
These macros are set by the configure script (via the file config.h).
Which is which?  The criterion is this.  In the ifdefs in GHC's source code:
<itemizedlist>
  <listitem>
    <para>The "host" system is the one on which GHC itself will be run.</para>
  </listitem>
  <listitem>
    <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
  </listitem>
</itemizedlist>
For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.

</para>
</sect3>

</sect2>

<sect2><title>Wrapper scripts</title>

<para>
Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
For <emphasis>installed</emphasis> programs, the strategy depends on the platform.  We'll use
GHC itself as an example:
<itemizedlist>
  <listitem> <para>
  On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
  paths to the front of the source file <filename>ghc.sh</filename>, 
  that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
  where to find its supporting files. 
  </para> </listitem>

  <listitem> <para>
  On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
  native Windows shell <command>cmd</command> (e.g. limits on the length
   of the command line).  So instead we invoke the GHC binary directly, with no -B flag.
  GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
  and from that figures out where the supporting files are.
  </para> </listitem>
</itemizedlist>
(You can find the layout of GHC's supporting files in the
  section "Layout of installed files" of Section 2 of the GHC user guide.)
</para>
<para>
Things work differently for <emphasis>in-place</emphasis> execution, where you want to
execute a program that has just been built in a build tree. The difference is that the
layout of the supporting files is different.
In this case, whether on Windows or Unix, we always use a shell script. This works OK
on Windows because the script is executed by MSYS or Cygwin, which don't have the
shortcomings of the native Windows <command>cmd</command> shell.
</para>

</sect2>

</sect1>

<sect1 id="winbuild"><title>Instructions for building under Windows</title>

<para>
This section gives detailed instructions for how to build 
GHC from source on your Windows machine. Similar instructions for
installing and running GHC may be found in the user guide. In general,
Win95/Win98 behave the same, and WinNT/Win2k behave the same.
</para>
<para>
Make sure you read the preceding section on platforms (<xref linkend="platforms">)
before reading section.
You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC, 
but you do need one or the other to <emphasis>build</emphasis> GHC.</para>


<sect2 id="msys-install"><title>Installing and configuring MSYS</title>

<para>
MSYS is a lightweight alternative to Cygwin.  
You don't need MSYS to <emphasis>use</emphasis> GHC, 
but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
Here's how to install MSYS.
<itemizedlist>
<listitem><para>
Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and 
download the following (of course, the version numbers will differ):
<itemizedlist>
  <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
  </para></listitem>
  <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
		    This provides <command>make</command>, <command>autoconf</command>, 
		    <command>ssh</command>, <command>cvs</command> and probably more besides.
  </para></listitem>
</itemizedlist>
Run both executables (in the order given above) to install them.  I put them in <literal>c:/msys</literal>
</para></listitem>

<listitem><para>
Set the following environment variables
<itemizedlist>
  <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path.  (Of course, the version number may differ.)
  </para></listitem>

  <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
  This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
  </para></listitem>  

  <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
  </para></listitem>

  <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>.  Only necessary if
	      you are using CVS.
  </para></listitem>

  <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>.  (I'm not certain this is necessary for MSYS.)
  </para></listitem>

</itemizedlist>
</para></listitem>

<listitem><para>
Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set.  It's a bad bug
that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
file has too-liberal permissinos.
</para></listitem>

</itemizedlist>
</para>
<para>Here are some points to bear in mind when using MSYS:
<itemizedlist>
<listitem> <para> MSYS does some kind of special magic to binaries stored in 
<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories: 
they fail in mysterious ways.  However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>

<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
</para></listitem>

<listitem> <para>
Win32 has a <command>find</command> command which is not the same as MSYS's find.
You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> 
environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> 
variable.  You can always invoke <command>find</command> with an absolute path, or rename it.
</para></listitem>

<listitem> <para>
MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal> 
will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>).  Useful when you get a
bzip'd dump.</para></listitem>

</itemizedlist>
</para>
</sect2>

<sect2><title>Installing and configuring Cygwin</title>

<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
During the installation dialogue, make sure that you select all of the following:
	      <command>cvs</command>, 
	      <command>openssh</command>,
	      <command>autoconf</command>,
	      <command>binutils</command> (includes ld and (I think) ar),
	      <command>gcc</command>,
	      <command>flex</command>,
	      <command>make</command>.
If you miss out any of these, strange things will happen to you.   To see thse packages, 
click on the "View" button in the "Select Packages" 
stage of Cygwin's installation dialogue, until the view says "Full".  The default view, which is
"Category" isn't very helpful, and the "View" button is rather unobtrousive.
</para>
<para> Now set the following user environment variables:
<itemizedlist>

<listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your 
<constant>PATH</constant></para></listitem>

<listitem>
<para>
Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
don't do this you get very weird messages when you type
<command>make</command>, such as:
<screen>/c: /c: No such file or directory</screen>
</para>
</listitem>

<listitem><para> Set <constant>SHELL</constant> to
<filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
<constant>SHELL</constant> is what you get.
</para></listitem>

<listitem><para> Set <constant>HOME</constant> to point to your 
home directory.  This is where, for example,
<command>bash</command> will look for your <filename>.bashrc</filename>
file.  Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
</para></listitem>
</itemizedlist>
</para>

<para>
There are a few other things to do:
<itemizedlist>
<listitem>
<para>
By default, cygwin provides the command shell <filename>ash</filename>
as <filename>sh.exe</filename>. We have often seen build-system problems that 
turn out to be due to bugs in <filename>ash</filename>
(to do with quoting
and length of command lines).  On the other hand <filename>bash</filename> seems
to be rock solid.
So, in <filename>cygwin/bin</filename>
remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
and copy <filename>bash.exe</filename> to  <filename>sh.exe</filename>.
You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
you can't rename a running program!
</para>
</listitem>

<listitem>
<para>
Some script files used in the make system start with "<command>#!/bin/perl</command>",
(and similarly for <command>sh</command>).  Notice the hardwired path!
So you need to ensure that your <filename>/bin</filename> directory has the following
binaries in it:
<itemizedlist>
<listitem> <para><command>sh</command></para></listitem>
<listitem> <para><command>perl</command></para></listitem>
<listitem> <para><command>cat</command></para></listitem>
</itemizedlist>
All these come in Cygwin's <filename>bin</filename> directory, which you probably have
installed as <filename>c:/cygwin/bin</filename>.  By default Cygwin mounts "<filename>/</filename>" as
<filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
(You can discover where your Cygwin
root directory <filename>/</filename> is by typing <command>mount</command>.)
Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
directory, there's no need to copy anything.  If not, copy these binaries from the <filename>cygwin/bin</filename>
directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
</para>
</listitem>
</itemizedlist>
</para>

<para>Finally, here are some things to be aware of when using Cygwin:
<itemizedlist>
<listitem> <para>Cygwin doesn't deal well with filenames that include
spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
common gotchas.
</para></listitem>

<listitem> <para> Cygwin implements a symbolic link as a text file with some
magical text in it.  So other programs that don't use Cygwin's
I/O libraries won't recognise such files as symlinks.  
In particular, programs compiled by GHC are meant to be runnable
without having Cygwin, so they don't use the Cygwin library, so
they don't recognise symlinks.
</para></listitem>

<listitem> <para>
See the notes in <xref linkend="msys-install"> about <command>find</command> and <command>bzip</command>,
which apply to Cygwin too.
</para></listitem>
</itemizedlist>
</para>

</sect2>


<sect2 id="configure-ssh"><title>Configuring SSH</title>

<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
you install Cygwin.  (If not, the installer lets you update easily.)  Look for <command>openssh</command> 
(not ssh) in the Cygwin list of applications!</para>

<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
<itemizedlist>
<listitem>
<para>
       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>
</listitem>

<listitem><para> (Cygwin-only problem, I think.)
<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.  
To determine your home directory <command>ssh</command> first looks in 
<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed).  If there's an entry
there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
the setting of the environment variable $HOME</emphasis>.  If the home directory is
bogus, <command>ssh</command> fails horribly.   The best way to see what is going on is to say
<programlisting>ssh -v cvs.haskell.org</programlisting>
which makes <command>ssh</command> print out information about its activity.
</para>
<para> You can fix this problem, either by correcting the home-directory field in 
<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
you do that, <command>ssh</command> uses the $HOME environment variable instead.
</para>

</listitem>

<listitem>
	    <para>To protect your
            <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
            includes you!</para>
</listitem>

<listitem>
	    <para>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>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2><title>Other things you need to install</title>

<para>You have to install the following other things to build GHC, listed below.</para>

<para>On Windows you often install executables in directories with spaces, such as 
"<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't 
deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
to put binaries for all tools in places with no spaces in their path.
On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>.  But it doesn't matter,
provided they are in your path.
<itemizedlist>
<listitem>
<para>
Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
This is what you will use to compile GHC.  Add it in your
<constant>PATH</constant>: the installer tells you the path element
you need to add upon completion.
</para>
</listitem>

<listitem>
<para>
Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
Happy is a parser generator used to compile the Haskell grammar.  Under MSYS or Cygwin you can easily
build it from the source distribution using
<programlisting>./configure
make
make install</programlisting>
This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
on MSYS).
Make sure the installation directory is in your
<constant>PATH</constant>.
</para>
</listitem>

	  <listitem>
	    <para>Install Alex.  This can be done by building from the
	    source distribution in the same way as Happy.  Sources are
	    available from <ulink
	    url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
	  </listitem>

<listitem>
<para>GHC uses the <emphasis>mingw</emphasis> C compiler to
generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">). 
Just pick up a mingw bundle at
<ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
We install it in <filename>c:/mingw</filename>.
</para>
<para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your  path.
They are only going to get used by explicit access (via the --with-gcc flag you
give to <command>configure</command> later).  If you do add them to your path
you are likely to get into a mess because their names overlap with Cygwin binaries.
</para>
</listitem>


<listitem>
<para>We use <command>emacs</command> a lot, so we install that too.
When you are in <filename>fptools/ghc/compiler</filename>, you can use
"<literal>make tags</literal>" to make a TAGS file for emacs.  That uses the utility
<filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
</para>
</listitem>


<listitem>
<para> Finally, check out a copy of GHC sources from
the CVS repository, following the instructions above (<xref linkend="cvs-access">).
</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2><title>Building GHC</title>

<para>OK!  
Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">); 
the bullets below only tell
you about Windows-specific wrinkles.</para>
<itemizedlist>
<listitem>
<para>
If you used <command>autoconf</command> instead of <command>autoreconf</command>,
you'll get an error when you run <filename>./configure</filename>:
<screen>
...lots of stuff...
creating mk/config.h
mk/config.h is unchanged
configuring in ghc
running /bin/sh ./configure  --cache-file=.././config.cache --srcdir=.
./configure: ./configure: No such file or directory
configure: error: ./configure failed for ghc</screen>
</para>
</listitem>

<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
read-only.  So if you need to run autoreconf again (which I sometimes do for safety's sake),
you get
<screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
Solution: delete <filename>configure</filename> first.
</para></listitem>

<listitem>
  <para> 
    After <command>autoreconf</command> run <command>./configure</command> in
    <filename>fptools/</filename> thus:

<screen>./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
This is the point at which you specify that you are building GHC-mingw
(see <xref linkend="ghc-mingw">). </para>

<para> Both these options are important! It's possible to get into
trouble using the wrong C compiler!</para>
<para>
Furthermore, it's <emphasis>very important</emphasis> that you specify a 
full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
uses this path to invoke <command>gcc</command>) is a MinGW program and won't
understand a Cygwin path.  For example, if you 
say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
<filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
time it tries to invoke it.   Worse, the failure comes with
no error message whatsoever.  GHC simply fails silently when first invoked, 
typically leaving you with this:
<screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O 
  -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes 
  -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return 
  -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes 
  -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS 
  -optc-fomit-frame-pointer -O2 -static 
  -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
make[2]: *** [Adjustor.o] Error 1
make[1]: *** [all] Error 1
make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
make: *** [all] Error 1</screen>
Be warned!
</para>

<para>
If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
you'll have to do something more like:
<screen>./configure --with-gcc=...the Cygwin gcc...</screen>
</para>
</listitem>

<listitem><para>
If you are paranoid, delete <filename>config.cache</filename> if it exists.
This file occasionally remembers out-of-date configuration information, which 
can be really confusing.
</para>
</listitem>

<listitem><para> You almost certainly want to set
<programlisting>SplitObjs = NO</programlisting>
in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
This tells the build system not to split each library into a myriad of little object files, one
for each function.  Doing so reduces binary sizes for statically-linked binaries, but on Windows
it dramatically increases the time taken to build the libraries in the first place.
</para>
</listitem>

<listitem><para> Do not attempt to build the documentation.
It needs all kinds of wierd Jade stuff that we haven't worked out for
Win32.</para></listitem>
</itemizedlist>
</sect2>


</sect1>

</article>