<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+ <!ENTITY hacking SYSTEM "../../HACKING">
+]>
<article id="building-guide">
<articleinfo>
-<title>Building the Glasgow Functional Programming Tools Suite</title>
+<title>Building and developing GHC</title>
<author><othername>The GHC Team</othername></author>
<address><email>glasgow-haskell-{users,bugs}@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>This Guide is primarily aimed at those who want to build and/or
+ hack on GHC. It describes how to get started with building GHC on your
+ machine, and how to tweak the settings to get the kind of build you
+ want. It also describes the inner workings of the build system, so you
+ can extend it, modify it, and use it to build your code.</para>
<para>The bulk of this guide applies to building on Unix
systems; see <xref linkend="winbuild"/> for Windows notes.</para>
<sect1 id="sec-getting">
<title>Getting the sources</title>
- <para>You can get your hands on the <literal>fptools</literal>
- in two ways:</para>
+ <para>You can get your hands on the GHC sources in two ways:</para>
<variablelist>
(c) 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
+ GHC. 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>
</varlistentry>
<varlistentry>
- <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
+ <term>The darcs repository.<indexterm><primary>darcs 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>
+ to get access to our darcs 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>Information on accessing the darcs repository is on
+ the wiki: <ulink
+ url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs"
+ />.</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
+ source tree from darcs 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@cvs.haskell.org:/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
- ("#!"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 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>,
- 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 "read-only
- repository" 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
- "commit message", 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>&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 libraries</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>Old, now deprecated, libraries. Everything in here is in <literal>libraries</literal>.</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> and <literal>libraries</literal>
- projects (a GHC source distribution will
- already include the bits you need).</para>
</sect1>
<sect1 id="sec-build-checks">
</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>
+ <para>Use an appropriate machine / operating system. <ulink
+ url="http://hackage.haskell.org/trac/ghc/wiki/Platforms">GHC
+ Platform Support</ulink> lists the currently 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 “pre-supposed” utilities are
</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 “platform” 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) Best is a
- native-code generator; (b) next best is a
- “registerised” port; (c) the bare minimum is an
- “unregisterised” port.
- (“Unregisterised” 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 “canonical”
- 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>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>GHC is required to build GHC, because GHC itself is
+ written in Haskell, and uses GHC extensions. It is possible
+ to build GHC using just a C compiler, and indeed some
+ distributions of GHC do just that, but it isn't the best
+ supported method, and you may encounter difficulties. Full
+ instructions are in <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
<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>Most GCC versions should work with the most recent GHC
+ sources. Expect trouble if you use a recent GCC with
+ an older GHC, though (trouble in the form of mis-compiled code,
+ link errors, and errors from the <literal>ghc-asm</literal>
+ script).</para>
+
<para>If your GCC dies with “internal error” on
some GHC source file, please let us know, so we can report
it and get things improved. (Exception: on x86
<indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
</term>
<listitem>
- <para>The fptools build system makes heavy use of features
+ <para>The GHC 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>
+ this installed in order to build GHC.</para>
+
+ <para>NB. it has been reported that version 3.79 no longer
+ works to build GHC, and 3.80 is required.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Happy
+ <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
<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>
+ used to generate GHC's parsers.</para>
+
+ <para>If you start from a source tarball of GHC (i.e. not a darcs
+ checkout), then you don't need Happy, because we supply the
+ pre-processed versions of the Happy parsers. If you intend to
+ modify the compiler and/or you're using a darcs checkout, then you
+ need Happy.</para>
+
+ <para>Happy version 1.15 is currently required to build GHC.
+ Grab a copy from <ulink
+ url="http://www.haskell.org/happy/">Happy's Web
+ Page</ulink>.</para>
</listitem>
</varlistentry>
</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
+ which GHC uses to generate its lexer.</para>
+
+ <para>Like Happy, you don't need Alex if you're building GHC from a
+ source tarball, but you do need it if you're modifying GHC and/or
+ building a darcs checkout.</para>
+
+ <para>Alex is
+ written in Haskell and is a project in the darcs repository.
+ Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
Page</ulink>.</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>GNU autoconf is needed if you intend to build from the
- CVS sources, it is <emphasis>not</emphasis> needed if you
+ darcs 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.
</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>
</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
+ <para>More tools are required if you want to format the
+ documentation that comes with GHC. See <xref
linkend="building-docs"/>.</para>
</sect2>
</sect1>
<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>“I just want to build it!”</para>
- <para>If you are starting from a source distribution, and just
- want a completely standard build, then the following procedure should
- work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
+ <para>No problem. This recipe should build and install a working GHC with
+ all the default settings. (unless you're
+ on Windows, in which case go to <xref linkend="winbuild" />).</para>
-<screen>$ autoreconf
+<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
+ </footnote>
$ ./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>
+ results in the default location (under <filename>/usr/local</filename> on
+ Unix, for example).</para>
+
+ <para>The <literal>configure</literal> script is a standard GNU
+ <literal>autoconf</literal> script, and accepts the usual options for
+ changing install locations and the like. Run
+ <literal>./configure --help</literal> for a list of options.</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>
+ </sect1>
+
+ <sect1 id="quick-start">
+ <title>Quick start for GHC developers</title>
+
+ <para>This section is a copy of the file
+ <literal>HACKING</literal> from the GHC source tree. It describes
+ how to get started with setting up your build tree for developing GHC
+ or its libraries, and how to start building.</para>
+
+<screen>
+&hacking;
+ </screen>
+ </sect1>
+
+ <sect1 id="sec-working-with-the-build-system">
+ <title>Working with the build system</title>
+
+ <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>
- <para>All the other directories are individual
- <emphasis>projects</emphasis> of the <literal>fptools</literal>
- system—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>
+ <title>History</title>
+
+ <para>First, a historical note. The GHC build system used to be
+ called "fptools": a generic build system used to build multiple
+ projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a
+ concept of the generic project-independent parts, and
+ project-specific parts that resided in a project
+ subdirectory.</para>
+
+ <para>Nowadays, most of these other projects are using <ulink
+ url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded
+ away, and GHC is the only regular user of the fptools build
+ system. We decided therefore to simplify the situation for
+ developers, and specialise the build system for GHC. This
+ resulted in a simpler organisation of the source tree and the
+ build system, which hopefully makes the whole thing easier to
+ understand.</para>
+
+ <para>You might find old comments that refer to "projects" or
+ "fptools" in the documentation and/or source; please let us know
+ if you do.</para>
</sect2>
<sect2>
are two (If you don't have either, the source distribution
includes sources for the X11
<command>lndir</command>—check out
- <filename>fptools/glafp-utils/lndir</filename>). See <xref
+ <filename>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 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
+ must be (a linked copy of) the root directory of the GHC source
+ tree.. Inside Makefiles, the root of your build tree is called
<constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
In the rest of this document path names are relative to
<constant>$(FPTOOLS_TOP)</constant> unless
otherwise stated. For example, the file
- <filename>ghc/mk/target.mk</filename> is actually
- <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
+ <filename>mk/target.mk</filename> is actually
+ <filename>$(FPTOOLS_TOP)/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
+ <para>When you build GHC 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
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>
+ 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
<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>
+ rather than darcs sources, you can skip this step.</para>
<para>Change directory to
<constant>$(FPTOOLS_TOP)</constant> and
a message like "No rule to make target 'mk/config.h.in'".
</para>
- <para>Some projects, including GHC, have their own configure script.
+ <para>Some parts of the source tree, particularly
+ libraries, 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>$(FPTOOLS_TOP)</filename>.</para>
<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>
+ <literal>ghc</literal>. (NOTE: I'm not sure it
+ actually works to specify a compiler other than GHC
+ here; unless you really know what you're doing I
+ suggest not using this option at all.)</para>
</listitem>
</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
+ GHC 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
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 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>
+<programlisting>GhcHcOpts=-Rghc-timing</programlisting>
<para>The accompanying comment explains that this is the list of
flags passed to GHC when building GHC itself. For doing
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 “<literal>+=</literal>”
- operator, which is quite a convenient feature.)</para>
+ operator, which is quite a convenient feature.</para>
+
+ <para>Haskell compilations by default have <literal>-O</literal>
+ turned on, by virtue of this setting from
+ <filename>config.mk</filename>:</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>SRC_HC_OPTS += -H16m -O</programlisting>
-<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
+ <para><literal>SRC_HC_OPTS</literal> means "options for HC from
+ the source tree", where HC stands for Haskell Compiler.
+ <literal>SRC_HC_OPTS</literal> are added to every Haskell
+ compilation. To turn off optimisation, you could add this to
+ <filename>build.mk</filename>:</para>
+
+<programlisting>SRC_HC_OPTS = -H16m -O0</programlisting>
+
+ <para>Or you could just add <literal>-O0</literal> to
+ <literal>GhcHcOpts</literal> to turn off optimisation for the
+ compiler. See <xref linkend="quick-start" /> for some more
+ suggestions.</para>
<para>When reading <filename>config.mk.in</filename>, remember
that anything between “@...@” signs is going to be substituted
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">
<orderedlist>
<listitem>
- <para> Get your source tree from somewhere (CVS repository
+ <para> Get your source tree from somewhere (darcs 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>
+ <filename>myghc</filename> (it does not have to be
+ called <filename>ghc</filename>).</para>
</listitem>
<listitem>
-
<para>(Optional) Use <command>lndir</command> or
<command>mkshadowdir</command> to create a build tree.</para>
-<screen>$ cd myfptools
-$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
+<screen>$ cd myghc
+$ mkshadowdir . /scratch/joe-bloggs/myghc-x86</screen>
<para>(N.B. <command>mkshadowdir</command>'s first argument
is taken relative to its second.) You probably want to give
<para>Change directory to the build tree. Everything is
going to happen there now.</para>
-<screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
+<screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
</listitem>
<para>Create the file <filename>mk/build.mk</filename>,
adding definitions for your desired configuration
options.</para>
-
-<screen>$ emacs mk/build.mk</screen>
</listitem>
</orderedlist>
<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—but in practice you are likely to know what's
- affected.</para>
+ <command>make clean; make</command>, because configuration
+ option changes could affect anything—but in practice you
+ are likely to know what's affected.</para>
</sect2>
<sect2>
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>
+ must use GNU <command>make</command></emphasis>. On some
+ systems this is called <command>gmake</command>, whereas on
+ others it is the standard <command>make</command> command. In
+ this document we will always refer to it as
+ <command>make</command>; please substitute with
+ <command>gmake</command> if your system requires it. If you use
+ a the wrong <command>make</command> you will get all sorts of
+ error messages (but no damage) because the GHC
<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>
+ the top of your build tree and type <command>make</command>.
+ This will prepare the tree and build the various parts in the
+ correct order, resulting in a complete build of GHC that can
+ even be used directly from the tree, without being installed
+ first.</para>
</sect2>
<sect2 id="sec-bootstrapping">
<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>
+ by the top-level <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. The top-level
+ <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>
<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
+ <literal>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>
+ <literal>compiler</literal>.</para>
</sect2>
<sect2 id="sec-standard-targets">
<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
+ for the real work. Notably, it does <command>make
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
+ <literal>make</literal> causes <literal>make boot
all</literal> to be invoked in each of the project
subdirectories, in the order specified by
<literal>$(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
+ need to update the dependencies, <literal>make
boot</literal> is a good way to do it.</para>
</listitem>
</varlistentry>
Depending on which directory you are in a “final
target” 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>
+ <command>make</command> alone is generally the same as
+ typing <command>make all</command>.</para>
</listitem>
</varlistentry>
<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
+ generated by <command>make boot</command>. Also preserve
files that could be made by building, but normally aren't
because the distribution comes with them.</para>
</listitem>
<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>
+ <filename>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
+ <filename>compiler/ghc</filename>, or
+ <filename>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>
<command>make</command> is going to rebuild everything anyway,
the following hack may be useful:</para>
-<screen>$ gmake FAST=YES</screen>
+<screen>$ make FAST=YES</screen>
<para>This tells the make system to ignore dependencies and just
build what you tell it to. In other words, it's equivalent to
<indexterm><primary>makefile architecture</primary></indexterm>
<para><command>make</command> is great if everything
- works—you type <command>gmake install</command> and lo! the
+ works—you type <command>make 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
<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
+ to the directory in which <command>make</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
<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
+ It contains the rules that tell <command>make</command> how
to make the standard targets (<xref
linkend="sec-standard-targets"/>). Why, you ask, can't this
standard code be part of
<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
+ you say <command>make all</command>, the following things
happen:</para>
<itemizedlist>
<listitem>
- <para><command>gmake</command> figures out that the object
+ <para><command>make</command> figures out that the object
files are <filename>Foo.o</filename> and
<filename>Baz.o</filename>.</para>
</listitem>
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
+ <command>make</command> know to use the Haskell compiler to
do the link, rather than the C compiler? Because we set the
variable <constant>HS_PROG</constant> rather than
<constant>C_PROG</constant>.)</para>
<filename>Makefile</filename> in
<filename>$(FPTOOLS_TOP)/ghc</filename>.
It does most of its work by recursively invoking
- <command>gmake</command> on the <filename>Makefile</filename>s
+ <command>make</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
<listitem>
<para><emphasis>Standard pattern rules</emphasis> that
- tell <command>gmake</command> how to construct one file
+ tell <command>make</command> how to construct one file
from another.</para>
</listitem>
</itemizedlist>
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>
+ <filename>Makefile</filename>. <command>make</command>
simply takes the last definition as the definitive one.</para>
<para>Instead of <emphasis>replacing</emphasis> boilerplate
<itemizedlist>
<listitem>
- <para><command>gmake</command> commits target and
+ <para><command>make</command> commits target and
dependency lists earlier than it should. For example,
<filename>target.mk</filename> has a rule that looks
like this:</para>
and
<constant>$(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
+ <command>make</command> encountered the rule. Alas,
+ <command>make</command> takes a snapshot of their
current values, and wires that snapshot into the rule.
(In contrast, the commands executed when the rule
“fires” are only substituted at the moment
<para>extra options to pass to all C compilations. This
is intended for command line use, thus:</para>
-<screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
+<screen>$ make libHS.a EXTRA_CC_OPTS="-v"</screen>
</listitem>
</varlistentry>
</variablelist>
dependencies say to do so. This means that you can, for
example, define both <constant>HS_PROG</constant> and
<constant>LIBRARY</constant>, which will generate two rules for
- <literal>install</literal>. When you type <command>gmake
+ <literal>install</literal>. When you type <command>make
install</command> both rules will be fired, and both the program
and the library will be installed, just as you wanted.</para>
</sect2>
<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
+ be important. For example, when you say <command>make
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).
<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
+ command line of <command>make</command></emphasis> (usually in
+ a recursive invocation of <command>make</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
+ any one invocation of <command>make</command>. Two other
<command>make</command> variables,
<constant>way_</constant> and
<constant>_way</constant> are immediately derived from
<filename>Foo.mp_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
+ variable. So if you say <command>make
Foo.mp_o</command> you should see a recursive
- invocation <command>gmake Foo.mp_o way=mp</command>,
+ invocation <command>make Foo.mp_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
<listitem>
<para>change <literal>TARGETPLATFORM</literal>
appropriately, and set the variables involving
- <literal>TARGET</literal> to the correct values for
+ <literal>TARGET</literal> or
+ <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
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
+<screen>$ cd <replaceable>H</replaceable>/compat
$ make clean
$ rm .depend
-$ make boot UseStage1=YES
-$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
$ cd <replaceable>H</replaceable>/ghc/utils
$ make clean
$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
</itemizedlist>
-and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
+and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about
<constant><module>_HC_OPTS</constant>.)
Alternatively, just cut to the chase:
<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>.
+<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</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>:
<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
+<command>darcs</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>,
</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.
+ <command>ssh</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>
<listitem>
<para> Finally, check out a copy of GHC sources from
-the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
-</para>
+the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
</listitem>
</itemizedlist>
</para>
- add C:\ghc\ghc-6.4.1\bin to %PATH%
(Start->Control Panel->System->Advanced->Environment Variables)
-- Get cvs version of ghc
+- Get darcs version of ghc
; also, subscribe to cvs-all@haskell.org, or follow the mailing list
; archive, in case you checkout a version with problems
; http://www.haskell.org//pipermail/cvs-all/
- mkdir c:/fptools; cd c:/fptools
- ; (or whereever you want your cvs tree to be)
- - export CVSROOT=:pserver:anoncvs@cvs.haskell.org:/cvs
- - cvs login
- ; pw: cvs
- - cvs checkout fpconfig
- - cd fptools
- - cvs checkout ghc hslibs libraries
+ ; (or whereever you want your darcs tree to be)
+ - darcs get http://darcs.haskell.org/ghc
+ - cd ghc
+ - chmod +x darcs-all
+ - ./darcs-all get
- Build ghc, using cygwin and mingw, targetting mingw
- export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
projects / ghc-hetmet.git / blobdiff