<?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@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
- ("#!"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 "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 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">
</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 “pre-supposed” 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 “known pitfalls” (<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 “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>
+ <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>
- <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>
+ <listitem>
+ <para>Be sure that the “pre-supposed” utilities are
+ installed. <xref linkend="sec-pre-supposed"/>
+ elaborates.</para>
+ </listitem>
- <varlistentry>
- <term>powerpc-apple-linux
- <indexterm><primary>powerpc-apple-linux</primary></indexterm>
- </term>
- <listitem>
- <para>Not supported (yet).</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para>If you have any problem when building or installing the
+ Glasgow tools, please check the “known pitfalls” (<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>
- <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>
+ <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
- <sect2>
- <title>What machines the other tools run on</title>
+ <para>If you feel there is still some shortcoming in our
+ procedure or instructions, please report it.</para>
- <para>Unless you hear otherwise, the other tools work if GHC
- works.</para>
- </sect2>
- </sect1>
+ <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-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>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>
+ <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>GHC can be built using either an earlier released
+ version of GHC (currently 5.04 and later are supported), or
+ bootstrapped using a GHC built from exactly the same
+ sources. Note that this means you cannot in general build
+ GHC using an arbitrary development snapshot, or a build from
+ say last week. It might work, it might not - we don't
+ guarantee anything. To be on the safe side, start your
+ build using the most recently released stable version of
+ GHC.</para>
</listitem>
</varlistentry>
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>
+ installation. Versions of Perl before 5.6 have been known to have
+ various bugs tickled by GHC, so the configure script
+ will look for version 5.6 or later.</para>
<para>For Win32 platforms, you should use the binary
supplied in the InstallShield (copy it to
<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
- <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
+ 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>$(GHC_TOP)</constant><indexterm><primary>GHC_TOP</primary></indexterm>.
In the rest of this document path names are relative to
- <constant>$(FPTOOLS_TOP)</constant> unless
+ <constant>$(GHC_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>$(GHC_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
+ <constant>$(GHC_TOP)</constant> and
issue the command</para>
<screen>$ autoreconf</screen>
<indexterm><primary>autoreconf</primary></indexterm>
<para>(with no arguments). This GNU program (recursively) converts
- <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
- <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
+ <filename>$(GHC_TOP)/configure.ac</filename> and
+ <filename>$(GHC_TOP)/aclocal.m4</filename>
to a shell script called
- <filename>$(FPTOOLS_TOP)/configure</filename>.
+ <filename>$(GHC_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.
+ <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>
+ <filename>$(GHC_TOP)</filename>.</para>
<para>These steps are completely platform-independent; they just mean
that the human-written files (<filename>configure.ac</filename> and
<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>
+
+<programlisting>SRC_HC_OPTS += -H16m -O</programlisting>
- <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>
+ <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>
-<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</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
<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_TOP_ABS</constant>: this
+ <constant>GHC_TOP_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">
<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 (eg. FreeBSD) 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>
<replaceable>n</replaceable> is the stage to install.</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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>dist</literal></term>
+ <listitem>
+ <para>make a source distribution. Note that this target
+ does “make distclean” as part of its work;
+ don't use it if you want to keep what you've built.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>The top-level <filename>Makefile</filename> also arranges
<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
- 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>
+ directory, invoking <literal>make</literal> causes
+ <literal>make boot</literal> to be invoked in various
+ subdirectories first, in the right order. Unless you
+ really know what you are doing, it is best to always say
+ <literal>make</literal> from the top level first.</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>
<term><literal>uninstall</literal></term>
<listitem>
<para>reverses the effect of
- <literal>install</literal>.</para>
+ <literal>install</literal> (WARNING: probably doesn't work).</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>
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>
+ <para>After a <literal>maintainer-clean</literal>, a
+ <literal>configure</literal> will be necessary before
+ building again.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term><literal>configure</literal></term>
- <listitem>
- <para>is only available in the root directory
- <constant>$(FPTOOLS_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
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 “make distclean” 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
+ <para>Some <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>
+ <title>Using GHC 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>If you want to build GHC and just use it direct from the
+ build tree without doing <literal>make install</literal> first,
+ you can run the in-place driver script. To run the stage 1
+ compiler, use <filename>compiler/stage1/ghc-inplace</filename>,
+ stage 2 is <filename>compiler/stage2/ghc-inplace</filename>, and
+ so on.</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/stage1/ghc</filename>, or
+ <filename>compiler/stage1/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>
<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
</sect2>
<sect2>
- <title>A small project</title>
+ <title>A small example</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_TOP</constant>, so the
- <literal>small</literal> project will have its own directory
- <constant>FPOOLS_TOP/small/</constant>. Inside the
- <filename>small/</filename> directory there will be a
+ <filename>Makefile</filename> for an imaginary small program,
+ <literal>small</literal>. Each program or library in the GHC
+ source tree typically has its own directory, in this case we'll
+ use <filename>$(GHC_TOP)/small</filename>.
+ 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"
-
+<programlisting># Makefile for program "small"
TOP = ..
include $(TOP)/mk/boilerplate.mk
-SRCS = $(wildcard *.lhs) $(wildcard *.c)
HS_PROG = small
include $(TOP)/target.mk</programlisting>
</para>
</footnote>
- a file of “boilerplate” code from the level
- above (which in this case will be
- <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
+ a file of “boilerplate” code from the top level
+ <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
<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>
+ to be the top-level directory of the source tree, 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
+ 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
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
+ <para> The second section defines the standard
+ <command>make</command> variable
<constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
(the executable binary to be built). We will discuss in
more detail what the “standard variables” 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>$(wildcard $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
+ 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
- files are <filename>Foo.o</filename> and
- <filename>Baz.o</filename>.</para>
+ <para><command>make</command> looks in the current directory
+ to see what source files it can find
+ (eg. <filename>Foo.hs</filename>,
+ <filename>Baz.c</filename>), and from that it figures out
+ what object files need to be built
+ (eg. <filename>Foo.o</filename>,
+ <filename>Baz.o</filename>). Because source files are found
+ and used automatically, omitting them from a program or
+ library has to be done manually (see
+ <literal>EXCLUDED_SRCS</literal> in <xref
+ linkend="sec-boiler" />).</para>
</listitem>
<listitem>
<para>It uses a boilerplate pattern rule to compile
- <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
+ <filename>Foo.hs</filename> to <filename>Foo.o</filename>
using a Haskell compiler. (Which one? That is set in the
build configuration.)</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>
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>
-
-<programlisting>$(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...</programlisting>
-
- <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>$(FPTOOLS_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>
<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
</sect2>
<sect2 id="sec-boiler">
- <title>The main <filename>mk/boilerplate.mk</filename> file</title>
+ <title>The <filename>mk/boilerplate.mk</filename> file</title>
<indexterm><primary>boilerplate.mk</primary></indexterm>
<para>If you look at
- <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
+ <filename>$(GHC_TOP)/mk/boilerplate.mk</filename>
you will find that it consists of the following sections, each
held in a separate file:</para>
<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_HC_OPTS="-v"</screen>
</listitem>
</varlistentry>
</variablelist>
<constant>$(libdir)</constant>.</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
- <listitem>
- <para>…</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
- <listitem>
- <para>…</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
- <listitem>
- <para>If <constant>HS_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_SRCS</constant>.</para>
- </listitem>
- </varlistentry>
</variablelist>
- <para>All of these rules are “double-colon” rules,
+ <para>Some rules are “double-colon” rules,
thus</para>
<programlisting>install :: $(HS_PROG)
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
<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>
+ format the documentation that comes with GHC:</para>
<variablelist>
<varlistentry>
<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
+ library source code. To build documentation for the
+ libraries (<literal>$(GHC_TOP)/libraries</literal>) you
+ should build and install Haddock. Haddock requires GHC
to build.</para>
</listitem>
</varlistentry>
<title>Porting GHC</title>
<para>This section describes how to port GHC to a currenly
- unsupported platform. There are two distinct
- possibilities:</para>
+ unsupported platform. To avoid confusion, when we say
+ “architecture” we are referring to the processor, and
+ we use the term “platform” to refer to the combination
+ of architecture and operating system.</para>
+
+ <para>There are two distinct porting scenarios:</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>
+ <para>Your platform is already supported, but you want to
+ compile up GHC using just a C compiler. This is a
+ straightforward bootstrap from HC files, and is described in
+ <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>
+ <para>Your platform isn't supported by GHC. You will need to
+ do an <emphasis>unregisterised bootstrap</emphasis>, proceed
+ to <xref linkend="unregisterised-porting"/>.</para>
</listitem>
</itemizedlist>
later.</emphasis></para>
<para>HC files are platform-dependent, so you have to get a set
- that were generated on <emphasis>the same platform</emphasis>. 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>
+ that were generated on <emphasis>the same platform</emphasis>.
+ There may be some supplied on the GHC download page, otherwise
+ you'll have to compile some up yourself.</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
+ <para>Make a set of HC files. On an identical system with
+ GHC already installed, get a GHC source tree and put the
+ following in <literal>mk/build.mk</literal>:</para>
+
+<programlisting>
+SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files
+GhcLibHcOpts = -O
+GhcLibWays =
+SplitObjs = NO
+</programlisting>
+
+ <para>Build GHC as normal, and then <literal>make
+ hc-file-bundle Project=ghc</literal> to creates the tar file
+ containing the hc files.</para>
+ </listitem>
+
+ <listitem>
+ <para>On the target system, 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
<literal>libraries</literal>).</para>
</listitem>
</sect2>
<sect2 id="unregisterised-porting">
- <title>Porting GHC to a new architecture</title>
+ <title>Porting GHC to a new platform</title>
- <para>The first step in porting to a new architecture is to get
- an <firstterm>unregisterised</firstterm> build working. An
+ <para>The first step in porting to a new platform 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>
since unregisterised compilation is usually just a step on the
way to a full registerised port, we don't mind too much.</para>
+ <para>You should go through this process even if your
+ architecture is already has registerised support in GHC, but
+ your OS currently isn't supported. In this case you probably
+ won't need to port any of the architecture-specific parts of the
+ code, and you can proceed straight from the unregisterised build
+ to build a registerised compiler.</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
$ ./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.ac</filename> to recognise the new
+ platform, and re-generate
<filename>configure</filename> with
<literal>autoreconf</literal>.</para>
</listitem>
<listitem>
-<screen>$ cd <replaceable>T</replaceable>/ghc/includes
+<screen>$ cd <replaceable>T</replaceable>/includes
$ make</screen>
</listitem>
</itemizedlist>
SplitObjs = NO
GhcWithNativeCodeGen = NO
GhcWithInterpreter = NO
-GhcStage1HcOpts = -O -fasm
+GhcStage1HcOpts = -O
GhcStage2HcOpts = -O -fvia-C -keep-hc-files
SRC_HC_OPTS += -H32m
-GhcBootLibs = YES</programlisting>
+GhcBootLibs = YES
+GhcWithSMP = NO</programlisting>
</listitem>
<listitem>
<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>
<para>Copy
- <filename><replaceable>T</replaceable>/ghc/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/ghc/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/ghc/includes/GHCConstants.h</filename>
+ <filename><replaceable>T</replaceable>/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/includes/GHCConstants.h</filename>
to
- <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+ <filename><replaceable>H</replaceable>/includes</filename>.
Note that we are building on the host machine, using the
target machine's configuration files. This
is so that the intermediate C files generated here will
<listitem>
<para>Touch the generated configuration files, just to make
sure they don't get replaced during the build:</para>
-<screen>$ touch <filename><replaceable>H</replaceable></filename>/ghc/includes/{ghcautoconf.h,DerivedConstants.h.GHCConstants.h.mkDerivedConstants.c.mkDerivedConstantsHdr.mkDerivedConstants.o,mkGHCConstants,mkGHCConstants.o}
+<screen>$ cd <filename><replaceable>H</replaceable></filename>/includes
+$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
+$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
</listitem>
<listitem>
<para>Now build the compiler:</para>
-<screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
-$ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
- <para>Don't worry if the build falls over in the RTS, we
- don't need the RTS yet.</para>
+<screen>$ cd <replaceable>H</replaceable>/utils/mkdependC && make boot && make
+$ cd <replaceable>H</replaceable>/includes && make boot && make
+$ cd <replaceable>H</replaceable>/compat && make boot && make
+$ cd <replaceable>H</replaceable>/utils && make boot && make
+$ cd <replaceable>H</replaceable>/compiler && make boot && make
+$ cd <replaceable>H</replaceable>/rts && make boot && make</screen>
+ <para>Don't worry if the build falls over in the RTS, we
+ don't need the RTS yet.</para>
</listitem>
<listitem>
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/compiler
+<screen>$ cd <replaceable>H</replaceable>/compiler
$ make boot stage=2 && make stage=2</screen>
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/lib
+<screen>$ cd <replaceable>H</replaceable>/compat
$ make clean
-$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
-$ cd <replaceable>H</replaceable>/ghc/utils
+$ rm .depend
+$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+$ cd <replaceable>H</replaceable>/utils
$ make clean
$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
</listitem>
<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
+ (<filename>$(GHC_TOP)/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>
+ architecture and/or OS will probaly be necessary.</para>
<para>If your system uses a different object file format, then
you have to write a linker — good luck!</para>
<programlisting>export TMPDIR=<dir></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.
+in your <filename>build.mk</filename> file. Then GHC and the other
+tools will use the appropriate directory in all cases.
</para>
</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>
</para>
</sect2>
-<sect2><title>Installing and configuring Cygwin</title>
+<sect2 id="install-cygwin"><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:
+The installation process is straightforward; we install it in
+<filename>c:/cygwin</filename>.</para>
+<para>
+You must install enough Cygwin <emphasis>packages</emphasis> to support
+building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
+<itemizedlist>
+<listitem><para>The direct, but laborious way is to
+select all of the following packages in the installation dialogue:
<command>cvs</command>,
<command>openssh</command>,
<command>autoconf</command>,
<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,
+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>
+</listitem>
+
+<listitem><para>The clever way is to point the Cygwin installer at the
+<command>ghc-depends</command> package, which is kept at <ulink
+url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
+When the Cygwin installer asks you to "Choose a Download Site", choose one of
+the
+offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
+"User URL" box and click "Add"; now two sites are selected. (The Cygwin
+installer remembers this for next time.)
+Click "Next".</para>
+<para>In the "Select Packages" dialogue box that follows, click the "+" sign by
+"Devel", scroll down to the end of the "Devel" packages, and choose
+<command>ghc-depends</command>.
+The package <command>ghc-depends</command> will not actually install anything itself,
+but forces additional packages to be added by the Cygwin installer.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
<para> Now set the following user environment variables:
<itemizedlist>
</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:
+<para>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
See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
which apply to Cygwin too.
</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 at least
+<command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
+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>
+
+<listitem>
+<para>
+By default, cygwin provides the command shell <filename>ash</filename>
+as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
+saw build-system problems that turned 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.
+If this happens to you (which it shouldn't), 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>
</itemizedlist>
</para>
<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><command>ssh</command> comes with both Cygwin and MSYS.
+(Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
+in the Cygwin list of packages; or use the <command>ghc-depends</command>
+package -- see <xref linkend="install-cygwin"/>.)</para>
<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
<itemizedlist>
<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
+"<filename>Program Files</filename>". However, the <literal>make</literal> system 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,
<para><emphasis>On Cygwin, do 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.
+you are likely to get into a mess because their names overlap with Cygwin
+binaries.
+On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
+(and perhaps one or two other things) in your path. The Cygwin ones are fine,
+but you must have them; hence needing the Cygwin binutils package.
</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
+When you are in <filename>$(GHC_TOP)/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>.
+<filename>$(GHC_TOP)/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>$(GHC_TOP)/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>
<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>
<listitem>
<para>
After <command>autoreconf</command> run <command>./configure</command> in
- <filename>fptools/</filename> thus:
+ <filename>$(GHC_TOP)/</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
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'
+<screen>make[4]: Leaving directory `/cygdrive/e/ghc-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
-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[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc'
make: *** [all] Error 1</screen>
Be warned!
</para>
</sect2>
+<sect2><title>A Windows build log using Cygwin</title>
+
+<para>Here is a complete, from-scratch, log of all you need to build GHC using
+Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
+choices, but it gives a single path that works.</para>
+<programlisting>- Install some editor (vim, emacs, whatever)
+
+- Install cygwin (http://www.cygwin.com)
+ ; i used 1.5.16-1, installed in c:\cygwin
+ - run 'setup.exe'
+ Choose a Download Source:
+ select 'download from internet';
+ Select Root Install Directory:
+ root dir: c:\cygwin;
+ install for: all users;
+ default file type: unix
+ Select Local Package Directory
+ choose a spare temporary home
+ Select Your Internet Connection
+ Use IE5 settings
+ Choose a Download Site
+ Choose your preferred main mirror and
+ Add 'http://www.haskell.org/ghc/cygwin'
+ Select Packages
+ In addition to 'Base' (default install),
+ select 'Devel->ghc-depends'
+
+- Install mingw (http://www.mingw.org/)
+ ; i used MinGW-3.1.0-1.exe
+ ; installed in c:\mingw
+ - you probably want to add GLUT
+ ; (http://www.xmission.com/~nate/glut.html)
+ ; i used glut-3.7.3-mingw32.tar
+
+- Get recent binary snapshot of ghc-6.4.1 for mingw
+ ; (http://www.haskell.org/ghc/dist/stable/dist/)
+ - unpack in c:/ghc
+ - add C:\ghc\ghc-6.4.1\bin to %PATH%
+ (Start->Control Panel->System->Advanced->Environment Variables)
+
+- 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:/ghc-build; cd c:/ghc-build
+ ; (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
+ ; for haddock, alex, happy (*)
+ - export PATH=/cygdrive/c/mingw/bin:$PATH
+ ; without, we pick up some cygwin tools at best!
+ - cd c:/ghc-build
+ ; (if you aren't there already)
+ - autoreconf
+ - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
+ ; we use cygwin, but build for windows
+ - cp mk/build.mk.sample mk/build.mk
+ - in mk/build.mk:
+ add line: SplitObjs = NO
+ (MSYS seems slow when there are zillions of object files)
+ uncomment line: BuildFlavour = perf
+ (or BuildFlavour = devel, if you are doing development)
+ add line: BIN_DIST=1
+ - make 2>&1 | tee make.log
+ ; always useful to have a log around
+
+- Package up binary distribution
+ - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
+ ; always useful to have a log around
+ - cd ghc-6.5
+ - chmod +x ../distrib/prep-bin-dist-mingw
+ ; if you're happy with the script's contents (*)
+ - ../distrib/prep-bin-dist-mingw
+ ; then tar up, unpack where wanted, and enjoy</programlisting>
+</sect2>
</sect1>
<index/>
projects / ghc-hetmet.git / blobdiff