<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-<Article id="building-guide">
+<article id="building-guide">
-<ArtHeader>
+<artheader>
-<Title>Building the Glasgow Functional Programming Tools Suite</Title>
-<Author><OtherName>The GHC Team</OtherName></Author>
-<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
-<PubDate>November 2001</PubDate>
+<title>Building the Glasgow Functional Programming Tools Suite</title>
+<author><othername>The GHC Team</othername></author>
+<address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address>
+<pubdate>November 2001</pubdate>
<abstract>
<para>The Glasgow fptools suite is a collection of Functional
installation system.</para>
<para>This guide is intended for people who want to build or
- modify programs from the Glasgow <Literal>fptools</Literal>
+ modify programs from the Glasgow <literal>fptools</literal>
suite (as distinct from those who merely want to
- <Emphasis>run</Emphasis> them). Installation instructions are
+ <emphasis>run</emphasis> them). Installation instructions are
now provided in the user guide.</para>
<para>The bulk of this guide applies to building on Unix
- systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
+ systems; see <xref linkend="winbuild"/> for Windows notes.</para>
</abstract>
- </artheader>
+</artheader>
<sect1 id="sec-getting">
the parser specifications. If you don't want to alter the
parser then this saves you having to find and install
<command>happy</command>. You will still need a working
- version of GHC (preferably version 4.08+) on your machine in
+ version of GHC (version 5.x or later) on your machine in
order to compile (most of) the sources, however.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>The CVS repository.</term>
- <indexterm><primary>CVS repository</primary>
- </indexterm>
+ <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
<listitem>
<para>We make releases infrequently. If you want more
up-to-the minute (but less tested) source code then you need
scratch.</para>
<para>More information about our CVS repository can be found
- in <xref linkend="sec-cvs">.</para>
+ in <xref linkend="sec-cvs"/>.</para>
</listitem>
</varlistentry>
</variablelist>
remember is that most mistakes can be undone, but if there's
anything you're not sure about feel free to bug the local CVS
meister (namely Jeff Lewis
- <email>jlewis@galconn.com</email>). </para>
+ <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>
+ 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>
<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>
-<programlisting>
- $ cvs login
-</programlisting>
+<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
</listitem>
<listitem>
- <para>Now go to <xref linkend="cvs-first">.</para>
+ <para>Now go to <xref linkend="cvs-first"/>.</para>
</listitem>
</orderedlist>
</sect3>
<listitem>
<para>Generate a DSA private-key/public-key pair, thus:</para>
-<screen>
- $ ssh-keygen -d
-</screen>
+<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
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>
+<screen>$ ssh-keygen</screen>
<para>Doing so creates the private and public RSA keys in
<literal>$HOME/.ssh/identity</literal> and
2 <literal>ssh</literal> to use the Version 1 protocol by
creating <literal>$HOME/config</literal> with the
following in it:</para>
-<screen>
- BatchMode Yes
+<programlisting>BatchMode Yes
- Host cvs.haskell.org
- Protocol 1
-</screen>
+Host cvs.haskell.org
+Protocol 1</programlisting>
<para>In both cases, <literal>ssh-keygen</literal> will
ask for a <firstterm>passphrase</firstterm>. The
<para>
- [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
- seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
- they ask for a password). To solve this, start up <filename>cmd.exe</filename>
- and run it as follows:
- <Screen>
- c:\tmp> set CYGWIN32=tty
- c:\tmp> c:/user/local/bin/ssh-keygen1
- </Screen> </para>
+ <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
+ </para>
+
- <para>[Windows users.] To protect your
- <literal>.ssh</literal> from access by anyone else,
- right-click your <literal>.ssh</literal> directory, and
- select <literal>Properties</literal>. If you are not on
- the access control list, add yourself, and give yourself
- full permissions (the second panel). Remove everyone else
- from the access control list. Don't leave them there but
- deny them access, because 'they' may be a list that
- includes you!</para>
- <para>[March 2003] In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
- you to have Unix permissions 600 (read/write for owner only)
- on the <literal>.ssh/identity</literal> file, else it
- bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
- but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
- The solution seems to be to set the CYGWIN environment
- variable to "<literal>ntsec neta</literal>". The CYGWIN environment variable is discussed
- in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
- and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
- </para>
</listitem>
<listitem>
<para>Send a message to to the CVS repository
administrator (currently Jeff Lewis
- <email>jeff@galconn.com</email>), containing:</para>
+ <email>jeff@galois.com</email>), containing:</para>
<itemizedlist>
<listitem>
<para>Your desired user-name.</para>
<listitem>
<para>Set the following environment variables:</para>
- <ItemizedList>
+ <itemizedlist>
<listitem>
<para>
<constant>$HOME</constant>: points to your home directory. This is where CVS
</para>
</listitem>
- </ItemizedList>
+ </itemizedlist>
</listitem>
Put the following in <filename>$HOME/.cvsrc</filename>:
</para>
- <ProgramListing>
- checkout -P
- release -d
- update -P
- diff -u
- </ProgramListing>
+<programlisting>checkout -P
+release -d
+update -P
+diff -u</programlisting>
<para>
These are the default options for the specified CVS commands,
methods above. The Approved Way to check out a source tree
is as follows:</para>
-<screen>
- $ cvs checkout fpconfig
-</screen>
+<screen>$ cvs checkout fpconfig</screen>
<para>At this point you have a new directory called
<literal>fptools</literal> which contains the basic stuff
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>
+<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>
+<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>
+<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>
+<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>
+ <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>
<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>
+<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
you the results.</para>
</listitem>
- <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>
+<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
<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>
+<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
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>
+<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>
+<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
major cause of headaches. </para>
<para>So, to avoid a lot of hassle, follow this recipe for
- updating your tree: </para>
+ updating your tree:</para>
-<screen>
-$ cd fptools
-$ cvs update -Pd 2>&1 | tee log</screen>
+<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). 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>
+ <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>
-<screen>
-$ cd <replaceable>build-tree</replaceable>
-$ lndir <replaceable>source-tree</replaceable>
-</screen>
+ <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>
+<screen>$ find . -xtype l -exec rm '{}' \;</screen>
<para>To be <emphasis>really</emphasis> safe, you should do
</para>
<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>
+<screen>$ cvs co -r ghc-4-06 fpconfig
+$ cd fptools
+$ cvs co -r ghc-4-06 ghc hslibs</screen>
</sect2>
<sect2 id="cvs-hints">
checked-out fptools tree containing just ghc, and you want
to add nofib to it:</para>
-<screen>
-$ cd fptools
-$ cvs checkout nofib
-</screen>
+<screen>$ cd fptools
+$ cvs checkout nofib</screen>
<para>or: </para>
-<screen>
-$ cd fptools
-$ cvs update -d nofib
-</screen>
+<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>
+<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
<variablelist>
<varlistentry>
- <term><literal>ghc</literal></term>
- <indexterm><primary><literal>ghc</literal></primary>
- <secondary>project</secondary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term><literal>glafp-utils</literal></term>
- <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term><literal>green-card</literal></term>
- <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
+ <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/">Green Card</ulink>
+ url="http://www.haskell.org/greencard/">GreenCard</ulink>
system for generating Haskell foreign function
interfaces.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>haggis</literal></term>
- <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>haddock</literal></term>
- <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>happy</literal></term>
- <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term><literal>hdirect</literal></term>
- <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>hood</literal></term>
- <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>hslibs</literal></term>
- <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>libraries</literal></term>
- <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>mhms</literal></term>
- <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <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></term>
- <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term><literal>testsuite</literal></term>
- <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
+ <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>
<orderedlist>
- <listitem>
- <indexterm><primary>Disk space needed</primary></indexterm>
- <para>Disk space needed: from about 100Mb for a basic GHC
+ <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
+ space needed: from about 100Mb for a basic GHC
build, up to probably 500Mb for a GHC build with everything
included (libraries built several different ways,
etc.).</para>
<listitem>
<para>Use an appropriate machine / operating system. <xref
- linkend="sec-port-info"> lists the supported platforms; if
+ 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>
+ <xref linkend="sec-porting-ghc"/>).</para>
</listitem>
<listitem>
<para>Be sure that the “pre-supposed” utilities are
- installed. <Xref LinkEnd="sec-pre-supposed">
+ 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
+ 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
+ available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
site</ulink>.</para>
<indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
<variablelist>
<varlistentry>
- <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
+ <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
</varlistentry>
<varlistentry>
- <term>sparc-sun-sunos4</term>
- <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term>sparc-sun-solaris2</term>
- <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
+ <term>sparc-sun-solaris2
+ <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
+ </term>
<listitem>
- <para>Fully supported (at least for Solaris 2.7),
+ <para>Fully supported (at least for Solaris 2.7 and 2.6),
including native-code generator.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
- <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
- <indexterm><primary>i386-*-linux</primary></indexterm>
+ <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
+ 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
</varlistentry>
<varlistentry>
- <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
- higher)</term>
- <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
- <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>i386-unknown-netbsd (PCs running NetBSD and
- OpenBSD)</term>
- <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term>i386-unknown-mingw32 (PCs running Windows)</term>
- <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>ia64-unknown-linux</term>
- <indexterm><primary>ia64-unknown-linux</primary></indexterm>
+ <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>
</varlistentry>
<varlistentry>
- <term>mips-sgi-irix5</term>
- <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>powerpc-ibm-aix</term>
- <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
+ <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
</varlistentry>
<varlistentry>
- <term>powerpc-apple-darwin</term>
- <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
+ <term>powerpc-apple-darwin
+ <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
+ </term>
<listitem>
- <para>Supported registerised. No native code
- generator.</para>
+ <para>Supported registerised. Native code generator is
+ almost working.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>powerpc-apple-linux</term>
- <indexterm><primary>powerpc-apple-linux</primary></indexterm>
+ <term>powerpc-apple-linux
+ <indexterm><primary>powerpc-apple-linux</primary></indexterm>
+ </term>
<listitem>
<para>Not supported (yet).</para>
</listitem>
<variablelist>
<varlistentry>
- <term>GHC</term>
- <indexterm><primary>pre-supposed: GHC</primary></indexterm>
- <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+ <term>GHC
+ <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+ <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>GHC is required to build many of the tools, including
GHC itself. If you need to port GHC to your platform
because there isn't a binary distribution of GHC available,
- then see <xref linkend="sec-porting-ghc">.</para>
+ 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
</varlistentry>
<varlistentry>
- <term>Perl</term>
- <indexterm><primary>pre-supposed: Perl</primary></indexterm>
- <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+ <term>Perl
+ <indexterm><primary>pre-supposed: Perl</primary></indexterm>
+ <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para><emphasis>You have to have Perl to proceed!</emphasis>
Perl version 5 at least is required. GHC has been known to
</varlistentry>
<varlistentry>
- <term>GNU C (<command>gcc</command>)</term>
- <indexterm><primary>pre-supposed: GCC (GNU C
- compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
- compiler), pre-supposed</primary></indexterm>
+ <term>GNU C (<command>gcc</command>)
+ <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
+ <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>We recommend using GCC version 2.95.2 on all
platforms. Failing that, version 2.7.2 is stable on most
<command>egcs</command>) have varying degrees of stability
depending on the platform.</para>
+ <para>GCC 3.2 is currently known to have problems building
+ GHC on Sparc, but is stable on x86.</para>
+
<para>If your GCC dies with “internal error” on
some GHC source file, please let us know, so we can report
- it and get things improved. (Exception: on iX86
+ it and get things improved. (Exception: on x86
boxes—you may need to fiddle with GHC's
<option>-monly-N-regs</option> option; see the User's
Guide)</para>
</varlistentry>
<varlistentry>
- <term>GNU Make</term>
- <indexterm><primary>make</primary><secondary>GNU</secondary>
- </indexterm>
+ <term>GNU Make
+ <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
+ </term>
<listitem>
<para>The fptools build system makes heavy use of features
specific to GNU <command>make</command>, so you must have
</varlistentry>
<varlistentry>
- <term>Happy</term>
- <indexterm><primary>Happy</primary></indexterm>
+ <term>Happy
+ <indexterm><primary>Happy</primary></indexterm>
+ </term>
<listitem>
<para>Happy is a parser generator tool for Haskell, and is
used to generate GHC's parsers. Happy is written in
(<literal>fptools/happy</literal>). It can be built from
source, but bear in mind that you'll need GHC installed in
order to build it. To avoid the chicken/egg problem,
- install a binary distribtion of either Happy or GHC to get
+ 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>
</varlistentry>
<varlistentry>
- <term>Autoconf</term>
- <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
- <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
+ <term>Alex
+ <indexterm><primary>Alex</primary></indexterm>
+ </term>
<listitem>
- <para>GNU Autoconf is needed if you intend to build from the
+ <para>Alex is a lexical-analyser generator for Haskell,
+ which GHC uses to generate its lexer. Like Happy, Alex is
+ written in Haskell and is a project in the CVS repository.
+ Alex distributions are available from <ulink
+ url="http://www.haskell.org/alex/">Alex's Web
+ Page</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>autoconf
+ <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
+ <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
+ </term>
+ <listitem>
+ <para>GNU autoconf is needed if you intend to build from the
CVS sources, it is <emphasis>not</emphasis> needed if you
just intend to build a standard source distribution.</para>
- <para>Autoconf builds the <command>configure</command>
- script from <filename>configure.in</filename> and
- <filename>aclocal.m4</filename>. If you modify either of
- these files, you'll need <command>autoconf</command> to
- rebuild <filename>configure</filename>.</para>
+ <para>Version 2.52 or later of the autoconf package is required.
+ NB. version 2.13 will no longer work, as of GHC version
+ 6.1.</para>
+
+ <para><command>autoreconf</command> (from the autoconf package)
+ recursively builds <command>configure</command> scripts from
+ the corresponding <filename>configure.ac</filename> and
+ <filename>aclocal.m4</filename> files. If you modify one of
+ the latter files, you'll need <command>autoreconf</command> to
+ rebuild the corresponding <filename>configure</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><command>sed</command></term>
- <indexterm><primary>pre-supposed: sed</primary></indexterm>
- <indexterm><primary>sed, pre-supposed</primary></indexterm>
+ <term><command>sed</command>
+ <indexterm><primary>pre-supposed: sed</primary></indexterm>
+ <indexterm><primary>sed, pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>You need a working <command>sed</command> if you are
going to build from sources. The build-configuration stuff
<variablelist>
<varlistentry>
- <term>PVM version 3:</term>
+ <term>PVM version 3:
<indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
- <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
+ <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>PVM is the Parallel Virtual Machine on which
Parallel Haskell programs run. (You only need this if you
- plan to run Parallel Haskell. Concurent Haskell, which
+ plan to run Parallel Haskell. Concurrent Haskell, which
runs concurrent threads on a uniprocessor doesn't need
it.) Underneath PVM, you can have (for example) a network
of workstations (slow) or a multiprocessor box
</varlistentry>
<varlistentry>
- <term><command>bash</command>:</term>
- <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
+ <term><command>bash</command>:
+ <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
+ </term>
<listitem>
<para>Sadly, the <command>gr2ps</command> script, used to
convert “parallelism profiles” to PostScript,
<variablelist>
<varlistentry>
- <term>Flex</term>
- <indexterm><primary>pre-supposed: flex</primary></indexterm>
- <indexterm><primary>flex, pre-supposed</primary></indexterm>
+ <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
<para>More tools are required if you want to format the documentation
that comes with GHC and other fptools projects. See <xref
- linkend="building-docs">.</para>
+ linkend="building-docs"/>.</para>
</sect2>
</sect1>
want a completely standard build, then the following should
work:</para>
-<screen>$ ./configure
+<screen>$ autoreconf
+$ ./configure
$ make
-$ make install
-</screen>
+$ make install</screen>
<para>For GHC, this will do a 2-stage bootstrap build of the
compiler, with profiling libraries, and install the
</listitem>
<listitem>
- <para><filename>configure.in</filename>,
+ <para><filename>configure.ac</filename>,
<filename>config.sub</filename>,
<filename>config.guess</filename>: these files support the
configuration process.</para>
only one project (<literal>happy</literal>, say), you must have
a source tree whose root directory contains
<filename>Makefile</filename>, <filename>mk/</filename>,
- <filename>configure.in</filename>, and the project(s) you want
+ <filename>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>
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
- LinkEnd="sec-storysofar"> for a typical invocation.</para>
+ <filename>fptools/glafp-utils/lndir</filename>). See <xref
+ linkend="sec-storysofar"/> for a typical invocation.</para>
<para>The build tree does not need to be anywhere near the
source tree in the file system. Indeed, one advantage of
can be placed in a non-backed-up partition, saving your systems
support people from backing up untold megabytes of
easily-regenerated, and rapidly-changing, gubbins. The golden
- rule is that (with a single exception—<XRef
- LinkEnd="sec-build-config">) <emphasis>absolutely everything in
+ rule is that (with a single exception—<xref
+ linkend="sec-build-config"/>) <emphasis>absolutely everything in
the build tree is either a symbolic link to the source tree, or
else is mechanically generated</emphasis>. It should be
perfectly OK for your build tree to vanish overnight; an hour or
<constant>$(FPTOOLS_TOP)</constant> unless
otherwise stated. For example, the file
<filename>ghc/mk/target.mk</filename> is actually
- <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
+ <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
</sect2>
<sect2 id="sec-build-config">
<para>Change directory to
<constant>$(FPTOOLS_TOP)</constant> and
- issue the command
- <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
- (with no arguments). This GNU program converts
- <filename><constant>$(FPTOOLS_TOP)</constant>/configure.in</filename>
+ issue the command</para>
+<programlisting>autoreconf</programlisting>
+ <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>
to a shell script called
- <filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
+ <filename>$(FPTOOLS_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. If there's an
- <constant>$(FPTOOLS_TOP)/<project>/configure.in</constant>,
- then you need to run <command>autoconf</command> in that
- directory too.</para>
-
- <para>Both these steps are completely
- platform-independent; they just mean that the
- human-written file (<filename>configure.in</filename>) can
- be short, although the resulting shell script,
- <command>configure</command>, and
- <filename>mk/config.h.in</filename>, are long.</para>
+ <para>Some projects, including GHC, have their own configure script.
+ <command>autoreconf</command> takes care of that, too, so all you have
+ to do is calling <command>autoreconf</command> in the top-level directory
+ <filename>$(FPTOOLS_TOP)</filename>.</para>
+
+ <para>These steps are completely platform-independent; they just mean
+ that the human-written files (<filename>configure.ac</filename> and
+ <filename>aclocal.m4</filename>) can be short, although the resulting
+ files (the <command>configure</command> shell scripts and the C header
+ template <filename>mk/config.h.in</filename>) are long.</para>
</listitem>
</varlistentry>
<para>Runs the newly-created <command>configure</command>
script, thus:</para>
-<ProgramListing>
-./configure <optional><parameter>args</parameter></optional>
-</ProgramListing>
+<programlisting>./configure <optional><parameter>args</parameter></optional></programlisting>
<para><command>configure</command>'s mission is to scurry
round your computer working out what architecture it has,
what operating system, whether it has the
- <Function>vfork</Function> system call, where
- <command>yacc</command> is kept, whether
+ <function>vfork</function> system call, where
+ <command>tar</command> is kept, whether
<command>gcc</command> is available, where various obscure
<literal>#include</literal> files are, whether it's a
leap year, and what the systems manager had for lunch. It
<variablelist>
<varlistentry>
- <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-ghc</literal></primary>
- </indexterm>
+ <term><literal>--with-ghc=<parameter>path</parameter></literal>
+ <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
+ </term>
<listitem>
<para>Specifies the path to an installed GHC which
you would like to use. This compiler will be used
</varlistentry>
<varlistentry>
- <term><literal>--with-hc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-hc</literal></primary>
- </indexterm>
+ <term><literal>--with-hc=<parameter>path</parameter></literal>
+ <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
+ </term>
<listitem>
<para>Specifies the path to any installed Haskell
compiler. This compiler will be used for compiling
</varlistentry>
<varlistentry>
- <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-gcc</literal></primary>
- </indexterm>
+ <term><literal>--with-gcc=<parameter>path</parameter></literal>
+ <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
+ </term>
<listitem>
<para>Specifies the path to the installed GCC. This
compiler will be used to compile all C files,
</listitem>
</varlistentry>
</variablelist>
-
- <para><command>configure</command> caches the results of
- its run in <filename>config.cache</filename>. Quite often
- you don't want that; you're running
- <command>configure</command> a second time because
- something has changed. In that case, simply delete
- <filename>config.cache</filename>.</para>
</listitem>
</varlistentry>
includes <filename>build.mk</filename> after
<filename>config.mk</filename>.)</para>
+ <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
+ that can serve as a starting point for your <filename>build.mk</filename>.</para>
+
<para>For example, <filename>config.mk.in</filename> contains
the definition:</para>
-<ProgramListing>
-GhcHcOpts=-O -Rghc-timing
-</ProgramListing>
+<programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
<para>The accompanying comment explains that this is the list of
flags passed to GHC when building GHC itself. For doing
<para>or, if you prefer,</para>
-<ProgramListing>
-GhcHcOpts += -DDEBUG
-</ProgramListing>
+<programlisting>GhcHcOpts += -DDEBUG</programlisting>
<para>GNU <command>make</command> allows existing definitions to
have new text appended using the “<literal>+=</literal>”
lot quicker), you can just override
<literal>GhcLibHcOpts</literal> altogether:</para>
-<ProgramListing>
-GhcHcOpts=-DDEBUG -Rghc-timing
-</ProgramListing>
+<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
<para>When reading <filename>config.mk.in</filename>, remember
that anything between “@...@” signs is going to be substituted
you want, but you need to be a bit surer what you are doing.
For example, there's a line that says:</para>
-<ProgramListing>
-YACC = @YaccCmd@
-</ProgramListing>
+<programlisting>TAR = @TarCmd@</programlisting>
- <para>This defines the Make variables <constant>YACC</constant>
- to the pathname for a <command>yacc</command> that
+ <para>This defines the Make variables <constant>TAR</constant>
+ to the pathname for a <command>tar</command> that
<command>configure</command> finds somewhere. If you have your
- own pet <command>yacc</command> you want to use instead, that's
+ own pet <command>tar</command> you want to use instead, that's
fine. Just add this line to <filename>mk/build.mk</filename>:</para>
-<ProgramListing>
-YACC = myyacc
-</ProgramListing>
+<programlisting>TAR = mytar</programlisting>
<para>You do not <emphasis>have</emphasis> to have a
<filename>mk/build.mk</filename> file at all; if you don't,
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>
+ have the essential files (see <xref
+ linkend="sec-source-tree"/>).</para>
</listitem>
<listitem>
<para>(Optional) Use <command>lndir</command> or
<command>mkshadowdir</command> to create a build tree.</para>
-<programlisting>
-$ cd myfptools
-$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
-</programlisting>
+<programlisting>$ cd myfptools
+$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</programlisting>
<para>(N.B. <command>mkshadowdir</command>'s first argument
is taken relative to its second.) You probably want to give
<para>Change directory to the build tree. Everything is
going to happen there now.</para>
-<programlisting>
-$ cd /scratch/joe-bloggs/myfptools-sun4
-</programlisting>
+<programlisting>$ cd /scratch/joe-bloggs/myfptools-sun4</programlisting>
</listitem>
<listitem>
<para>Prepare for system configuration:</para>
-<programlisting>
-$ autoconf
-</programlisting>
+<programlisting>$ autoreconf</programlisting>
<para>(You can skip this step if you are starting from a
source distribution, and you already have
<filename>configure</filename> and
<filename>mk/config.h.in</filename>.)</para>
-
- <para>Some projects, including GHC itself, have their own
- configure scripts, so it is necessary to run autoconf again
- in the appropriate subdirectories. eg:</para>
-
-<programlisting>
-$ (cd ghc; autoconf)
-</programlisting>
</listitem>
<listitem>
<para>Do system configuration:</para>
-<programlisting>
-$ ./configure
-</programlisting>
+<programlisting>$ ./configure</programlisting>
<para>Don't forget to check whether you need to add any
arguments to <literal>configure</literal>; for example, a
adding definitions for your desired configuration
options.</para>
-<programlisting>
-$ emacs mk/build.mk
-</programlisting>
+<programlisting>$ emacs mk/build.mk</programlisting>
</listitem>
</orderedlist>
<listitem>
<para>is only available in the root directory
<constant>$(FPTOOLS_TOP)</constant>; it has
- been discussed in <XRef
- LinkEnd="sec-build-config">.</para>
+ been discussed in <xref
+ linkend="sec-build-config"/>.</para>
</listitem>
</varlistentry>
generated <filename>.depend</filename> file will contain
the dependency:</para>
-<ProgramListing>
-Foo.o : Baz.hi
-</ProgramListing>
+<programlisting>Foo.o : Baz.hi</programlisting>
<para>which says that the object file
<filename>Foo.o</filename> depends on the interface file
<para> Do <emphasis>NOT</emphasis> use
<filename>ghc/compiler/ghc</filename>, or
- <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
+ <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
scripts intended for installation, and contain hard-wired paths
to the installed libraries, rather than the libraries in the
build tree.</para>
<para>Happy can similarly be run from the build tree, using
- <filename>happy/src/happy-inplace</filename>.</para>
+ <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>
-<ProgramListing>
-gmake FAST=YES
-</ProgramListing>
+<programlisting>gmake FAST=YES</programlisting>
<para>This tells the make system to ignore dependencies and just
build what you tell it to. In other words, it's equivalent to
the contents of any make variable in the context of the current
<filename>Makefile</filename>:</para>
-<screen>$ make show VALUE=HS_SRCS</screen>
+<screen>$ make show VALUE=HS_SRCS</screen>
<para>where you can replace <literal>HS_SRCS</literal> with the
name of any variable you wish to see the value of.</para>
<indexterm><primary>Makefile, minimal</primary></indexterm>
-<ProgramListing>
-# Makefile for fptools project "small"
+<programlisting># Makefile for fptools project "small"
TOP = ..
include $(TOP)/mk/boilerplate.mk
SRCS = $(wildcard *.lhs) $(wildcard *.c)
HS_PROG = small
-include $(TOP)/target.mk
-</ProgramListing>
+include $(TOP)/target.mk</programlisting>
<para>this <filename>Makefile</filename> has three
sections:</para>
a file of “boilerplate” code from the level
above (which in this case will be
- <filename><constant>FPTOOLS_TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
+ <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
As its name suggests, <filename>boilerplate.mk</filename>
consists of a large quantity of standard
<filename>Makefile</filename> code. We discuss this
- boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
+ boilerplate in more detail in <xref linkend="sec-boiler"/>.
<indexterm><primary>include, directive in
Makefiles</primary></indexterm> <indexterm><primary>Makefile
inclusion</primary></indexterm></para>
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>
+<programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
<para>Why? Because the <filename>boilerplate.mk</filename>
<literal>include</literal>d sits.) In general,
<emphasis>every file <filename>foo.mk</filename> assumes
that
- <filename><constant>$(TOP)</constant>/mk/foo.mk</filename>
+ <filename>$(TOP)/mk/foo.mk</filename>
refers to itself.</emphasis> It is up to the
<filename>Makefile</filename> doing the
<literal>include</literal> to ensure this is the case.</para>
<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>
+ 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
code, called
<filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
It contains the rules that tell <command>gmake</command> how
- to make the standard targets (<Xref
- LinkEnd="sec-standard-targets">). Why, you ask, can't this
+ to make the standard targets (<xref
+ linkend="sec-standard-targets"/>). Why, you ask, can't this
standard code be part of
<filename>boilerplate.mk</filename>? Good question. We
- discuss the reason later, in <Xref
- LinkEnd="sec-boiler-arch">.</para>
+ discuss the reason later, in <xref
+ linkend="sec-boiler-arch"/>.</para>
<para>You do not <emphasis>have</emphasis> to
<literal>include</literal> the
though, you will find quite a big payoff from using the
canned rules in <filename>target.mk</filename>; the price
tag is that you have to understand what canned rules get
- enabled, and what they do (<Xref
- LinkEnd="sec-targets">).</para>
+ enabled, and what they do (<xref
+ linkend="sec-targets"/>).</para>
</listitem>
</orderedlist>
rare.) To give you the idea, here's part of the directory
structure for the (rather large) GHC project:</para>
-<Screen>
-$(FPTOOLS_TOP)/ghc/
+<screen>$(FPTOOLS_TOP)/ghc/
Makefile
mk/
boilerplate.mk
Makefile
parser/...source files for parser...
renamer/...source files for renamer...
- ...etc...
-</Screen>
+ ...etc...</screen>
<para>The sub-directories <filename>docs</filename>,
<filename>driver</filename>, <filename>compiler</filename>, and
so on, each contains a sub-component of GHC, and each has its
own <filename>Makefile</filename>. There must also be a
<filename>Makefile</filename> in
- <filename><constant>$(FPTOOLS_TOP)</constant>/ghc</filename>.
+ <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
<emphasis>augment</emphasis> them. For example, a
<filename>Makefile</filename> might say:</para>
-<ProgramListing>
-SRC_HC_OPTS += -O
-</ProgramListing>
+<programlisting>SRC_HC_OPTS += -O</programlisting>
<para>thereby adding “<option>-O</option>” to
the end of
<listitem>
<para><filename>target.mk</filename> contains
<command>make</command> rules for the standard targets
- described in <Xref LinkEnd="sec-standard-targets">. These
+ described in <xref linkend="sec-standard-targets"/>. These
rules are selectively included, depending on the setting of
certain <command>make</command> variables. These variables
are usually set in the middle section of the
<para><command>gmake</command> commits target and
dependency lists earlier than it should. For example,
- <FIlename>target.mk</FIlename> has a rule that looks
+ <filename>target.mk</filename> has a rule that looks
like this:</para>
-<ProgramListing>
-$(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@
-</ProgramListing>
+<programlisting>$(HS_PROG) : $(OBJS)
+ $(HC) $(LD_OPTS) $< -o $@</programlisting>
<para>If this rule was in
<filename>boilerplate.mk</filename> then
<indexterm><primary>boilerplate.mk</primary></indexterm>
<para>If you look at
- <filename><constant>$(FPTOOLS_TOP)</constant>/mk/boilerplate.mk</filename>
+ <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
you will find that it consists of the following sections, each
held in a separate file:</para>
<variablelist>
<varlistentry>
- <term><filename>config.mk</filename></term>
- <indexterm><primary>config.mk</primary></indexterm>
+ <term><filename>config.mk</filename>
+ <indexterm><primary>config.mk</primary></indexterm>
+ </term>
<listitem>
<para>is the build configuration file we discussed at
- length in <Xref LinkEnd="sec-build-config">.</para>
+ length in <xref linkend="sec-build-config"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>paths.mk</filename></term>
- <indexterm><primary>paths.mk</primary></indexterm>
+ <term><filename>paths.mk</filename>
+ <indexterm><primary>paths.mk</primary></indexterm>
+ </term>
<listitem>
<para>defines <command>make</command> variables for
pathnames and file lists. This file contains code for
<variablelist>
<varlistentry>
- <term><literal>ALL_DIRS</literal></term>
- <indexterm><primary><literal>ALL_DIRS</literal></primary>
- </indexterm>
+ <term><literal>ALL_DIRS</literal>
+ <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
+ </term>
<listitem>
<para>Set to a list of directories to search in
addition to the current directory for source
</varlistentry>
<varlistentry>
- <term><literal>EXCLUDE_SRCS</literal></term>
- <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
- </indexterm>
+ <term><literal>EXCLUDE_SRCS</literal>
+ <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>Set to a list of source files (relative to the
current directory) to omit from the automatic
</varlistentry>
<varlistentry>
- <term><literal>EXTRA_SRCS</literal></term>
- <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
- </indexterm>
+ <term><literal>EXTRA_SRCS</literal>
+ <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>Set to a list of extra source files (perhaps
in directories not listed in
<variablelist>
<varlistentry>
- <term><literal>SRCS</literal></term>
- <indexterm><primary><literal>SRCS</literal></primary></indexterm>
+ <term><literal>SRCS</literal>
+ <indexterm><primary><literal>SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>All source files found, sorted and without
duplicates, including those which might not exist
</varlistentry>
<varlistentry>
- <term><literal>HS_SRCS</literal></term>
- <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
+ <term><literal>HS_SRCS</literal>
+ <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>all Haskell source files in the current
directory, including those derived from other source
</varlistentry>
<varlistentry>
- <term><literal>HS_OBJS</literal></term>
- <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
+ <term><literal>HS_OBJS</literal>
+ <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
+ </term>
<listitem>
<para>Object files derived from
<literal>HS_SRCS</literal>.</para>
</varlistentry>
<varlistentry>
- <term><literal>HS_IFACES</literal></term>
- <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
+ <term><literal>HS_IFACES</literal>
+ <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
+ </term>
<listitem>
<para>Interface files (<literal>.hi</literal> files)
derived from <literal>HS_SRCS</literal>.</para>
</varlistentry>
<varlistentry>
- <term><literal>C_SRCS</literal></term>
+ <term><literal>C_SRCS</literal>
<indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>All C source files found.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>C_OBJS</literal></term>
+ <term><literal>C_OBJS</literal>
<indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
+ </term>
<listitem>
<para>Object files derived from
<literal>C_SRCS</literal>.</para>
</varlistentry>
<varlistentry>
- <term><literal>SCRIPT_SRCS</literal></term>
+ <term><literal>SCRIPT_SRCS</literal>
<indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>All script source files found
(<literal>.lprl</literal> files).</para>
</varlistentry>
<varlistentry>
- <term><literal>SCRIPT_OBJS</literal></term>
+ <term><literal>SCRIPT_OBJS</literal>
<indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
+ </term>
<listitem>
<para><quote>object</quote> files derived from
<literal>SCRIPT_SRCS</literal>
</varlistentry>
<varlistentry>
- <term><literal>HSC_SRCS</literal></term>
+ <term><literal>HSC_SRCS</literal>
<indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>All <literal>hsc2hs</literal> source files
(<literal>.hsc</literal> files).</para>
</varlistentry>
<varlistentry>
- <term><literal>HAPPY_SRCS</literal></term>
+ <term><literal>HAPPY_SRCS</literal>
<indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
+ </term>
<listitem>
<para>All <literal>happy</literal> source files
(<literal>.y</literal> or <literal>.hy</literal> files).</para>
</varlistentry>
<varlistentry>
- <term><literal>OBJS</literal></term>
+ <term><literal>OBJS</literal>
<indexterm><primary>OBJS</primary></indexterm>
+ </term>
<listitem>
<para>the concatenation of
<literal>$(HS_OBJS)</literal>,
</varlistentry>
<varlistentry>
- <term><filename>opts.mk</filename></term>
- <indexterm><primary>opts.mk</primary></indexterm>
+ <term><filename>opts.mk</filename>
+ <indexterm><primary>opts.mk</primary></indexterm>
+ </term>
<listitem>
<para>defines <command>make</command> variables for option
strings to pass to each program. For example, it defines
<constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
the option strings to pass to the Haskell compiler. See
- <Xref LinkEnd="sec-suffix">.</para>
+ <xref linkend="sec-suffix"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>suffix.mk</filename></term>
- <indexterm><primary>suffix.mk</primary></indexterm>
+ <term><filename>suffix.mk</filename>
+ <indexterm><primary>suffix.mk</primary></indexterm>
+ </term>
<listitem>
- <para>defines standard pattern rules—see <Xref
- LinkEnd="sec-suffix">.</para>
+ <para>defines standard pattern rules—see <xref
+ linkend="sec-suffix"/>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Almost all the rules look something like this:</para>
-<ProgramListing>
-%.o : %.c
+<programlisting>%.o : %.c
$(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@
-</ProgramListing>
+ $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
<para>Here's how to understand the rule. It says that
<emphasis>something</emphasis><filename>.o</filename> (say
defined in <filename>mk/opts.mk</filename>. Almost all of them
are defined like this:</para>
-<ProgramListing>
-CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
-</ProgramListing>
+<programlisting>CC_OPTS = \
+ $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
<para>The four variables from which
<constant>CC_OPTS</constant> is built have the following
<literal>mp</literal>. The variable
<constant>WAY_CC_OPTS</constant> holds
options to pass to the C compiler when compiling the
- standard way. (<Xref LinkEnd="sec-ways"> dicusses
+ standard way. (<xref linkend="sec-ways"/> dicusses
multi-way compilation.)</para>
</listitem>
</varlistentry>
<para>extra options to pass to all C compilations. This
is intended for command line use, thus:</para>
-<ProgramListing>
-gmake libHS.a EXTRA_CC_OPTS="-v"
-</ProgramListing>
+<programlisting>gmake libHS.a EXTRA_CC_OPTS="-v"</programlisting>
</listitem>
</varlistentry>
</variablelist>
<indexterm><primary>target.mk</primary></indexterm>
<para><filename>target.mk</filename> contains canned rules for
- all the standard targets described in <Xref
- LinkEnd="sec-standard-targets">. It is complicated by the fact
+ all the standard targets described in <xref
+ linkend="sec-standard-targets"/>. It is complicated by the fact
that you don't want all of these rules to be active in every
<filename>Makefile</filename>. Rather than have a plethora of
tiny files which you can include selectively, there is a single
<para>All of these rules are “double-colon” rules,
thus</para>
-<ProgramListing>
-install :: $(HS_PROG)
- ...how to install it...
-</ProgramListing>
+<programlisting>install :: $(HS_PROG)
+ ...how to install it...</programlisting>
<para>GNU <command>make</command> treats double-colon rules as
separate entities. If there are several double-colon rules for
<para>When <constant>SUBDIRS</constant> is defined,
<filename>target.mk</filename> includes a rather neat rule for
- the standard targets (<Xref LinkEnd="sec-standard-targets"> that
+ the standard targets (<xref linkend="sec-standard-targets"/> that
simply invokes <command>make</command> recursively in each of
the sub-directories.</para>
<filename>Makefile</filename> to the list of way tags you
want these targets built for. The mechanism here is very
much like the recursive invocation of
- <command>make</command> in sub-directories (<Xref
- LinkEnd="sec-subdirs">). It is up to you to set
+ <command>make</command> in sub-directories (<xref
+ linkend="sec-subdirs"/>). It is up to you to set
<constant>WAYS</constant> in your
<filename>Makefile</filename>; this is how you control what
ways will get built.</para>
file will match</emphasis>. The key pattern rules (in
<filename>suffix.mk</filename>) look like this:
-<ProgramListing>
-%.$(way_)o : %.lhs
- $(HC) $(HC_OPTS) $< -o $@
-</ProgramListing>
+<programlisting>%.$(way_)o : %.lhs
+ $(HC) $(HC_OPTS) $< -o $@</programlisting>
Neat, eh?</para>
</listitem>
to build files related to a particular
<literal>way</literal> in the current directory. eg.
-<screen>
-$ make way=p
-</screen>
+<screen>$ make way=p</screen>
will build files for the profiling way only in the current
directory. </para>
<variablelist>
<varlistentry>
- <term>DocBook</term>
- <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
- <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+ <term>DocBook
+ <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
+ <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>Much of our documentation is written in SGML, using
the DocBook DTD. Instructions on installing and
</varlistentry>
<varlistentry>
- <term>TeX</term>
- <indexterm><primary>pre-supposed: TeX</primary></indexterm>
- <indexterm><primary>TeX, pre-supposed</primary></indexterm>
+ <term>TeX
+ <indexterm><primary>pre-supposed: TeX</primary></indexterm>
+ <indexterm><primary>TeX, pre-supposed</primary></indexterm>
+ </term>
<listitem>
<para>A decent TeX distribution is required if you want to
produce printable documentation. We recomment teTeX,
</varlistentry>
<varlistentry>
- <term>Haddock</term>
- <indexterm><primary>Haddock</primary>
- </indexterm>
+ <term>Haddock
+ <indexterm><primary>Haddock</primary></indexterm>
+ </term>
<listitem>
<para>Haddock is a Haskell documentation tool that we use
for automatically generating documentation from the
<para>If you don't have DocBook tools installed, and you are
using a system that can handle RedHat RPM packages, you can
- probably use the <ULink
- URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
- DocBook tools</ULink>, which is the most shrink-wrapped SGML
+ probably use the <ulink
+ url="http://sourceware.cygnus.com/docbook-tools/">Cygnus
+ DocBook tools</ulink>, which is the most shrink-wrapped SGML
suite that we could find. You need all the RPMs except for
- psgml (i.e. <Filename>docbook</Filename>,
- <Filename>jade</Filename>, <Filename>jadetex</Filename>,
- <Filename>sgmlcommon</Filename> and
- <Filename>stylesheets</Filename>). Note that most of these
+ psgml (i.e. <filename>docbook</filename>,
+ <filename>jade</filename>, <filename>jadetex</filename>,
+ <filename>sgmlcommon</filename> and
+ <filename>stylesheets</filename>). Note that most of these
RPMs are architecture neutral, so are likely to be found in a
- <Filename>noarch</Filename> directory. The SuSE RPMs also
- work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
+ <filename>noarch</filename> directory. The SuSE RPMs also
+ work; the RedHat ones <emphasis>don't</emphasis> in RedHat 6.2
(7.0 and later should be OK), but they are easy to fix: just
make a symlink from
- <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
- to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
+ <filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</filename>
+ to <filename>/usr/lib/sgml/lib/dblib.dsl</filename>. </para>
</sect3>
<sect3>
FreeBSD mirror site).</para>
<para>To use the ports tree, do this:
-<screen>
- $ cd /usr/ports/textproc/docproj
- $ make install
-</screen>
+<screen>$ cd /usr/ports/textproc/docproj
+$ make install</screen>
This installs the FreeBSD documentation project tools, which
includes everything needed to format the GHC
documentation.</para>
<sect3>
<title>Installing from binaries on Windows</title>
- <Para>It's a good idea to use Norman Walsh's <ULink
- URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
- notes</ULink> as a guide. You should get version 3.1 of
- DocBook, and note that his file <Filename>test.sgm</Filename>
+ <para>It's a good idea to use Norman Walsh's <ulink
+ url="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
+ notes</ulink> as a guide. You should get version 3.1 of
+ DocBook, and note that his file <filename>test.sgm</filename>
won't work, as it needs version 3.0. You should unpack Jade
- into <Filename>\Jade</Filename>, along with the entities,
- DocBook into <Filename>\docbook</Filename>, and the DocBook
- stylesheets into <Filename>\docbook\stylesheets</Filename> (so
+ into <filename>\Jade</filename>, along with the entities,
+ DocBook into <filename>\docbook</filename>, and the DocBook
+ stylesheets into <filename>\docbook\stylesheets</filename> (so
they actually end up in
- <Filename>\docbook\stylesheets\docbook</Filename>).</para>
- </Sect3>
+ <filename>\docbook\stylesheets\docbook</filename>).</para>
+ </sect3>
<sect3>
<sect4>
<title>Jade</title>
- <para>Install <ULink
- URL="http://openjade.sourceforge.net/">OpenJade</ULink>
+ <para>Install <ulink
+ url="http://openjade.sourceforge.net/">OpenJade</ulink>
(Windows binaries are available as well as sources). If you
want DVI, PS, or PDF then install JadeTeX from the
- <Filename>dsssl</Filename> subdirectory. (If you get the
+ <filename>dsssl</filename> subdirectory. (If you get the
error:
-<screen>
-! LaTeX Error: Unknown option implicit=false' for package hyperref'.
-</screen>
+<screen>! LaTeX Error: Unknown option implicit=false' for package hyperref'.</screen>
- your version of <Command>hyperref</Command> is out of date;
+ your version of <command>hyperref</command> is out of date;
download it from CTAN
- (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
+ (<filename>macros/latex/contrib/supported/hyperref</filename>),
and make it, ensuring that you have first removed or renamed
your old copy. If you start getting file not found errors
- when making the test for <Command>hyperref</Command>, you
+ when making the test for <command>hyperref</command>, you
can abort at that point and proceed straight to
- <Command>make install</Command>, or enter them as
- <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
+ <command>make install</command>, or enter them as
+ <filename>../</filename><emphasis>filename</emphasis>.)</para>
- <para>Make links from <Filename>virtex</Filename> to
- <Filename>jadetex</Filename> and
- <Filename>pdfvirtex</Filename> to
- <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
+ <para>Make links from <filename>virtex</filename> to
+ <filename>jadetex</filename> and
+ <filename>pdfvirtex</filename> to
+ <filename>pdfjadetex</filename> (otherwise DVI, PostScript
and PDF output will not work). Copy
- <Filename>dsssl/*.{dtd,dsl}</Filename> and
- <Filename>catalog</Filename> to
- <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+ <filename>dsssl/*.{dtd,dsl}</filename> and
+ <filename>catalog</filename> to
+ <filename>/usr/[local/]lib/sgml</filename>.</para>
</sect4>
<sect4>
<title>DocBook and the DocBook stylesheets</title>
- <para>Get a Zip of <ULink
- URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
+ <para>Get a Zip of <ulink
+ url="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ulink>
and install the contents in
- <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
+ <filename>/usr/[local/]/lib/sgml</filename>.</para>
- <para>Get the <ULink
- URL="http://nwalsh.com/docbook/dsssl/">DocBook
- stylesheets</ULink> and install in
- <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
+ <para>Get the <ulink
+ url="http://nwalsh.com/docbook/dsssl/">DocBook
+ stylesheets</ulink> and install in
+ <filename>/usr/[local/]lib/sgml/stylesheets</filename>
(thereby creating a subdirectory docbook). For indexing,
- copy or link <Filename>collateindex.pl</Filename> from the
- DocBook stylesheets archive in <Filename>bin</Filename> into
- a directory on your <Constant>PATH</Constant>.</para>
-
- <para>Download the <ULink
- URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
- entities</ULink> into
- <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+ copy or link <filename>collateindex.pl</filename> from the
+ DocBook stylesheets archive in <filename>bin</filename> into
+ a directory on your <constant>PATH</constant>.</para>
+
+ <para>Download the <ulink
+ url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
+ entities</ulink> into
+ <filename>/usr/[local/]lib/sgml</filename>.</para>
</sect4>
</sect3>
</sect2>
<sect2>
<title>Configuring the DocBook tools</title>
- <Para>Once the DocBook tools are installed, the configure script
+ <para>Once the DocBook tools are installed, the configure script
will detect them and set up the build system accordingly. If you
have a system that isn't supported, let us know, and we'll try
to help.</para>
<para>If you install from source, you'll get a pile of warnings
of the form
-<Screen>DTDDECL catalog entries are not supported</Screen>
+<screen>DTDDECL catalog entries are not supported</screen>
every time you build anything. These can safely be ignored, but
if you find them tedious you can get rid of them by removing all
- the <Constant>DTDDECL</Constant> entries from
- <Filename>docbook.cat</Filename>.</para>
+ the <constant>DTDDECL</constant> entries from
+ <filename>docbook.cat</filename>.</para>
</sect2>
<sect2>
<para>To build documentation in a certain format, you can
say, for example,</para>
-<screen>
-$ make html
-</screen>
+<screen>$ make html</screen>
<para>to build HTML documentation below the current directory.
The available formats are: <literal>dvi</literal>,
to a list of them. For example, in
<filename>build.mk</filename> you might have a line:</para>
-<screen>
-SGMLDocWays = html ps
-</screen>
+<screen>SGMLDocWays = html ps</screen>
<para>This will cause the documentation to be built in the requested
formats as part of the main build (the default is not to build
<para>To install the documentation, use:</para>
-<screen>
-$ make install-docs
-</screen>
+<screen>$ make install-docs</screen>
<para>This will install the documentation into
<literal>$(datadir)</literal> (which defaults to
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>
+ <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>
+ linkend="unregisterised-porting"/>.</para>
</listitem>
</itemizedlist>
target machine, and compiling them using gcc to get a working
GHC.</para>
- <para><emphasis>NOTE: GHC version 5.xx is significantly harder
- to bootstrap from C than previous versions. We recommend
- starting from version 4.08.2 if you need to bootstrap in this
- way.</emphasis></para>
+ <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
+ from C. We recommend using GHC 6.0.1 or
+ later.</emphasis></para>
- <para>HC files are architecture-dependent (but not
- OS-dependent), so you have to get a set that were generated on
- similar hardware. There may be some supplied on the GHC
- download page, otherwise you'll have to compile some up
- yourself, or start from <emphasis>unregisterised</emphasis> HC
- files - see <xref linkend="unregisterised-porting">.</para>
+ <para>HC files are platform-dependent, so you have to get a set
+ that were generated on similar hardware. There may be some
+ supplied on the GHC download page, otherwise you'll have to
+ compile some up yourself, or start from
+ <emphasis>unregisterised</emphasis> HC files - see <xref
+ linkend="unregisterised-porting"/>.</para>
<para>The following steps should result in a working GHC build
with full libraries:</para>
command will execute the whole build process (it won't
install yet):</para>
-<Screen>
-foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
-</Screen>
+<screen>foo% distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
<indexterm><primary>--hc-build</primary></indexterm>
<para>By default, the installation directory is
build process, you can install the resulting system, as
normal, with</para>
-<Screen>
-foo% make install
-</Screen>
+<screen>foo% make install</screen>
</listitem>
</itemizedlist>
</sect2>
since unregisterised compilation is usually just a step on the
way to a full registerised port, we don't mind too much.</para>
- <sect3>
- <title>Building an unregisterised port</title>
-
- <para>The first step is to get some unregisterised HC files.
- Either (a) download them from the GHC site (if there are
- some available for the right version of GHC), or
- (b) build them yourself on any machine with a working
- GHC. If at all possible this should be a machine with the
- same word size as the target.</para>
-
- <para>There is a script available which should automate the
- process of doing the 2-stage bootstrap necessary to get the
- unregisterised HC files - it's available in <ulink
- url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
- in CVS.</para>
-
- <para>Now take these unregisterised HC files to the target
- platform and bootstrap a compiler from them as per the
- instructions in <xref linkend="sec-booting-from-hc">. In
- <filename>build.mk</filename>, you need to tell the build
- system that the compiler you're building is
- (a) unregisterised itself, and (b) builds
- unregisterised binaries. This varies depending on the GHC
- version you're bootstraping:</para>
-
-<programlisting>
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
-</programlisting>
-
-<programlisting>
-# build.mk for GHC 5.xx
-GhcUnregisterised=YES
-</programlisting>
-
- <para>Version 5.xx only: use the option
- <option>--enable-hc-boot-unregisterised</option> instead of
- <option>--enable-hc-boot</option> when running
- <filename>./configure</filename>.</para>
-
- <para>The build may not go through cleanly. We've tried to
- stick to writing portable code in most parts of the compiler,
- so it should compile on any POSIXish system with gcc, but in
- our experience most systems differ from the standards in one
- way or another. Deal with any problems as they arise - if you
- get stuck, ask the experts on
- <email>glasgow-haskell-users@haskell.org</email>.</para>
+ <para>Notes on GHC portability in general: we've tried to stick
+ to writing portable code in most parts of the system, so it
+ should compile on any POSIXish system with gcc, but in our
+ experience most systems differ from the standards in one way or
+ another. Deal with any problems as they arise - if you get
+ stuck, ask the experts on
+ <email>glasgow-haskell-users@haskell.org</email>.</para>
- <para>Once you have the unregisterised compiler up and
- running, you can use it to start a registerised port. The
- following sections describe the various parts of the system
- that will need architecture-specific tweaks in order to get a
- registerised build going.</para>
-
- <para>Lots of useful information about the innards of GHC is
- available in the <ulink
- url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
- Commentary</ulink>, which might be helpful if you run into
- some code which needs tweaking for your system.</para>
+ <para>Lots of useful information about the innards of GHC is
+ available in the <ulink
+ url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+ Commentary</ulink>, which might be helpful if you run into some
+ code which needs tweaking for your system.</para>
+
+ <sect3>
+ <title>Cross-compiling to produce an unregisterised GHC</title>
+
+ <para>In this section, we explain how to bootstrap GHC on a
+ new platform, using unregisterised intermediate C files. We
+ haven't put a great deal of effort into automating this
+ process, for two reasons: it is done very rarely, and the
+ process usually requires human intervention to cope with minor
+ porting issues anyway.</para>
+
+ <para>The following step-by-step instructions should result in
+ a fully working, albeit unregisterised, GHC. Firstly, you
+ need a machine that already has a working GHC (we'll call this
+ the <firstterm>host</firstterm> machine), in order to
+ cross-compile the intermediate C files that we will use to
+ bootstrap the compiler on the <firstterm>target</firstterm>
+ machine.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>On the target machine:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Unpack a source tree (preferably a released
+ version). We will call the path to the root of this
+ tree <replaceable>T</replaceable>.</para>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>T</replaceable>
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
+
+ <para>You might need to update
+ <filename>configure.in</filename> to recognise the new
+ architecture, and re-generate
+ <filename>configure</filename> with
+ <literal>autoreconf</literal>.</para>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>T</replaceable>/ghc/includes
+$ make config.h</screen>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>On the host machine:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Unpack a source tree (same released version). Call
+ this directory <replaceable>H</replaceable>.</para>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>H</replaceable>
+$ ./configure</screen>
+ </listitem>
+
+ <listitem>
+ <para>Create
+ <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
+ with the following contents:</para>
+
+<programlisting>GhcUnregisterised = YES
+GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Edit
+ <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
+ <itemizedlist>
+ <listitem>
+ <para>change <literal>TARGETPLATFORM</literal>
+ appropriately, and set the variables involving
+ <literal>TARGET</literal> to the correct values for
+ the target platform. This step is necessary because
+ currently <literal>configure</literal> doesn't cope
+ with specifying different values for the
+ <literal>--host</literal> and
+ <literal>--target</literal> flags.</para>
+ </listitem>
+ <listitem>
+ <para>copy <literal>LeadingUnderscore</literal>
+ setting from target.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Copy
+ <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
+ to
+ <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+ Note that we are building on the host machine, using the
+ target machine's <literal>config.h</literal> file. This
+ is so that the intermediate C files generated here will
+ be suitable for compiling on the target system.</para>
+
+ </listitem>
+
+ <listitem>
+ <para>Touch <literal>config.h</literal>, just to make
+ sure it doesn't get replaced during the build:</para>
+<screen>$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
+ </listitem>
+
+ <listitem>
+ <para>Now build the compiler:</para>
+<screen>$ cd <replaceable>H</replaceable>/glafp-utils && 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>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>H</replaceable>/libraries
+$ make boot && make</screen>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>H</replaceable>/ghc
+$ make boot stage=2 && make stage=2</screen>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>H</replaceable>/ghc/utils
+$ make clean
+$ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
+ EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
+ </listitem>
+
+ <listitem>
+<screen>$ cd <replaceable>H</replaceable>
+$ make hc-file-bundle Project=Ghc</screen>
+ </listitem>
+
+ <listitem>
+ <para>copy
+ <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
+ to <filename><replaceable>T</replaceable>/..</filename>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>On the target machine:</para>
+
+ <para>At this stage we simply need to bootstrap a compiler
+ from the intermediate C files we generated above. The
+ process of bootstrapping from C files is automated by the
+ script in <literal>distrib/hc-build</literal>, and is
+ described in <xref linkend="sec-booting-from-hc"/>.</para>
+
+<screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
+
+ <para>However, since this is a bootstrap on a new machine,
+ the automated process might not run to completion the
+ first time. For that reason, you might want to treat the
+ <literal>hc-build</literal> script as a list of
+ instructions to follow, rather than as a fully automated
+ script. This way you'll be able to restart the process
+ part-way through if you need to fix anything on the
+ way.</para>
+
+ <para>Don't bother with running
+ <literal>make install</literal> in the newly
+ bootstrapped tree; just use the compiler in that tree to
+ build a fresh compiler from scratch, this time without
+ booting from C files. Before doing this, you might want
+ to check that the bootstrapped compiler is generating
+ working binaries:</para>
+
+<screen>$ cat >hello.hs
+main = putStrLn "Hello World!\n"
+^D
+$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
+$ ./hello
+Hello World!</screen>
+
+ <para>Once you have the unregisterised compiler up and
+ running, you can use it to start a registerised port. The
+ following sections describe the various parts of the
+ system that will need architecture-specific tweaks in
+ order to get a registerised build going.</para>
+
+ </listitem>
+ </itemizedlist>
</sect3>
<sect3>
<variablelist>
<varlistentry>
- <term><filename>ghc/includes/MachRegs.h</filename></term>
- <indexterm><primary><filename>MachRegs.h</filename></primary>
- </indexterm>
+ <term><filename>ghc/includes/MachRegs.h</filename>
+ <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
+ </term>
<listitem>
<para>Defines the STG-register to machine-register
mapping. You need to know your platform's C calling
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>ghc/includes/TailCalls.h</filename></term>
- <indexterm><primary><filename>TailCalls.h</filename></primary>
- </indexterm>
+ <term><filename>ghc/includes/TailCalls.h</filename>
+ <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
+ </term>
<listitem>
<para>Macros that cooperate with the mangler (see <xref
- linkend="sec-mangler">) to make proper tail-calls
+ linkend="sec-mangler"/>) to make proper tail-calls
work.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>ghc/rts/Adjustor.c</filename></term>
- <indexterm><primary><filename>Adjustor.c</filename></primary>
- </indexterm>
+ <term><filename>ghc/rts/Adjustor.c</filename>
+ <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
+ </term>
<listitem>
<para>Support for
<literal>foreign import "wrapper"</literal>
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>ghc/rts/StgCRun.c</filename></term>
- <indexterm><primary><filename>StgCRun.c</filename></primary>
- </indexterm>
+ <term><filename>ghc/rts/StgCRun.c</filename>
+ <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
+ </term>
<listitem>
<para>The little assembly layer between the C world and
the Haskell world. See the comments and code for the
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>ghc/rts/MBlock.h</filename></term>
- <term><filename>ghc/rts/MBlock.c</filename></term>
- <indexterm><primary><filename>MBlock.h</filename></primary>
- </indexterm>
- <indexterm><primary><filename>MBlock.c</filename></primary>
- </indexterm>
+ <term><filename>ghc/rts/MBlock.h</filename>
+ <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
+ </term>
+ <term><filename>ghc/rts/MBlock.c</filename>
+ <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
+ </term>
<listitem>
<para>These files are really OS-specific rather than
architecture-specific. In <filename>MBlock.h</filename>
<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 you probably don't have
- to do anything except fiddle with the
- <literal>#ifdef</literal>s at the top of
- <filename>Linker.c</filename> to tell it about your OS.</para>
+ your platform uses one of these then things will be
+ significantly easier. The majority of Unix platforms use the
+ ELF format these days. Even so, there are some
+ machine-specific parts of the ELF linker: for example, the
+ code for resolving particular relocation types is
+ machine-specific, so some porting of this code to your
+ architecture will probaly be necessary.</para>
<para>If your system uses a different object file format, then
you have to write a linker — good luck!</para>
<para>
-<OrderedList>
+<orderedlist>
<listitem>
<para>
The best way around it is to say
-<ProgramListing>
-export TMPDIR=<dir>
-</ProgramListing>
+<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
Similarly, <command>ar</command>chiving warning messages like the following are not
a problem:
-<Screen>
-ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
+<screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
-...
-</Screen>
+...</screen>
</para>
</itemizedlist>
-and try again: <command>gmake</command>. (see <Xref LinkEnd="sec-suffix"> for information about
+and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
<constant><module>_HC_OPTS</constant>.)
Alternatively, just cut to the chase:
-<Screen>
-% cd ghc/compiler
-% make EXTRA_HC_OPTS=-optCrts-M128M
-</Screen>
+<screen>% cd ghc/compiler
+% make EXTRA_HC_OPTS=-optCrts-M128M</screen>
</para>
You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
-<Screen>
-% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
+<screen>% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
? ranlib $i
? # or, on some machines: ar s $i
-? end
-</Screen>
+? end</screen>
We'd be interested to know if this is still necessary.
like this:
-<ProgramListing>
-SLIT("Hello, world")
-</ProgramListing>
+<programlisting>SLIT("Hello, world")</programlisting>
Some <command>cpp</command>s treat the comma inside the string as separating two macro
arguments, so you get
-<Screen>
-:731: macro `SLIT' used with too many (2) args
-</Screen>
+<screen>:731: macro `SLIT' used with too many (2) args</screen>
Alas, <command>cpp</command> doesn't tell you the offending file!
</para>
</listitem>
-</OrderedList>
+</orderedlist>
</para>
</sect1>
-<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
-
+<sect1 id="platforms"><title>Platforms, scripts, and file names</title>
<para>
-This section summarises how to get the utilities you need on your
-Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
-installing and running GHC may be found in the user guide. In general,
-Win95/Win98 behave the same, and WinNT/Win2k behave the same.
-You should read the GHC installation guide sections on Windows (in the user
-guide) before continuing to read these notes.
+GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
+gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
</para>
+<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
-<sect2><Title>Cygwin and MinGW</Title>
-
-<para> The Windows situation for building GHC is rather confusing. This section
+<para> The build system is built around Unix-y makefiles. Because it's not native,
+the Windows situation for building GHC is particularly confusing. This section
tries to clarify, and to establish terminology.</para>
-<sect3 id="ghc-mingw"><title>GHC-mingw</title>
+<sect3 id="ghc-mingw"><title>MinGW</title>
<para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
is a collection of header
Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
other utilities.
</para>
-<para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
-<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
-GHC compiles Haskell to C (or to
-assembly code), and then invokes these MinGW tools to generate an executable binary.
-The resulting binaries can run on any Win32 system.
+
+<para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
+Posix interface.
</para>
-<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
+
+<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
+or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
+<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
+For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
+and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
+
+<itemizedlist>
+<listitem><para>
+Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
+compile code that has access to all of Posix. The price is that the executables must be
+dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
+that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
+does not change, but the implementation certainly does. Even the interfaces to functions
+it exports seem to change occasionally. </para>
+</listitem>
+
+<listitem><para>
+MSYS is a fork of the Cygwin tree, so they
+are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
+through fewer layers, so MSYS is quite a bit faster too.
+</para>
+
+<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
+compile binaries that run with no DLL support, on any Win32 system.
+However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
+<command>cvs</command>, <command>ssh</command> etc. To get these, you have to download the
+MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
+</para>
+<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
+<command>ssh</command> and so on),
+not by programs compiled under MSYS.
+</para></listitem>
+
+</itemizedlist>
+
+</para>
+</sect3>
+
+<sect3><title>Targeting MinGW</title>
-<para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
-Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
+<para>We want GHC to compile programs that work on any Win32 system. Hence:
+<itemizedlist>
+<listitem><para>
+GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
+invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
+will work on any system, but it also means that the programs GHC compiles do not have access
+to all of Posix. In particular, they cannot import the (Haskell) Posix
library; they have to do
-their input output using standard Haskell I/O libraries, or native Win32 bindings.
+their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</listitem>
+
+<listitem><para>
+To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
+<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
+</para></listitem>
+</itemizedlist>
+So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
+It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
+that targets Cygwin instead. The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
+</para>
+
+<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
+how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
+GHC; both work fine, though MSYS is rather lighter weight.</para>
+
+<para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
+uses the <command>gcc</command> that you specify using the
+<option>--with-gcc</option> flag when you run
+<command>configure</command> (see below).
+The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
+to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
+whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
+and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
+used to glom together .o files into a bigger .o file, or a .a file,
+so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
+Cygwin and MinGW use the same .o file format. So its ok.
</para>
</sect3>
-<sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
+<sect3><title> File names </title>
-<para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
-<ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
-Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
-<command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
-A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
+<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
+However:
+<itemizedlist>
+<listitem><para>
+MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
+<filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
</para>
-<para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
-Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
-A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
-If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
-that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
-Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
-does not change, but the implementation certainly does. Even the interfaces to functions
-it exports seem to change occasionally. So programs compiled by GHC might only run with
-particular versions of Cygwin. All of this seems very undesirable.
+<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
+directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
+arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
+if you invoke
+<programlisting>foogle -B/c/tmp/baz</programlisting>
+the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
+</para></listitem>
+
+<listitem><para>
+Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
</para>
-<para>
-Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
-we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
-that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+</para></listitem>
+</itemizedlist>
</para>
</sect3>
-<sect3><title>HOST_OS vs TARGET_OS</title>
+<sect3><title>Host System vs Target System</title>
<para>
In the source code you'll find various ifdefs looking like:
-<programlisting>
- #ifdef mingw32_HOST_OS
- ...blah blah...
- #endif
-</programlisting>
+<programlisting>#ifdef mingw32_HOST_OS
+ ...blah blah...
+#endif</programlisting>
and
-<programlisting>
- #ifdef mingw32_TARGET_OS
- ...blah blah...
- #endif
-</programlisting>
+<programlisting>#ifdef mingw32_TARGET_OS
+ ...blah blah...
+#endif</programlisting>
These macros are set by the configure script (via the file config.h).
Which is which? The criterion is this. In the ifdefs in GHC's source code:
<itemizedlist>
+ <listitem>
+ <para>The "host" system is the one on which GHC itself will be run.</para>
+ </listitem>
+ <listitem>
+ <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
+ </listitem>
+</itemizedlist>
+For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
+So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+
+</para>
+</sect3>
+
+</sect2>
+
+<sect2><title>Wrapper scripts</title>
+
+<para>
+Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
+For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
+GHC itself as an example:
+<itemizedlist>
<listitem> <para>
- The "host" system is the one on which GHC itself will be run.
+ On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
+ paths to the front of the source file <filename>ghc.sh</filename>,
+ that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
+ where to find its supporting files.
</para> </listitem>
+
<listitem> <para>
- The "target" system is the one for which the program compiled by GHC will be run.
+ On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
+ native Windows shell <command>cmd</command> (e.g. limits on the length
+ of the command line). So instead we invoke the GHC binary directly, with no -B flag.
+ GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
+ and from that figures out where the supporting files are.
</para> </listitem>
</itemizedlist>
-For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
-So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+(You can find the layout of GHC's supporting files in the
+ section "Layout of installed files" of Section 2 of the GHC user guide.)
+</para>
+<para>
+Things work differently for <emphasis>in-place</emphasis> execution, where you want to
+execute a program that has just been built in a build tree. The difference is that the
+layout of the supporting files is different.
+In this case, whether on Windows or Unix, we always use a shell script. This works OK
+on Windows because the script is executed by MSYS or Cygwin, which don't have the
+shortcomings of the native Windows <command>cmd</command> shell.
+</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="winbuild"><title>Instructions for building under Windows</title>
+
+<para>
+This section gives detailed instructions for how to build
+GHC from source on your Windows machine. Similar instructions for
+installing and running GHC may be found in the user guide. In general,
+Win95/Win98 behave the same, and WinNT/Win2k behave the same.
</para>
-</sect3>
+<para>
+Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
+before reading section.
+You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
+but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
-<sect3><title>Summary</title>
-<para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
-how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
-by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
+<sect2 id="msys-install"><title>Installing and configuring MSYS</title>
-<para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
-GHC-cygwin too is beyond our resources. The GHC we distribute
-therefore does not require Cygwin to run, nor do the programs it
-compiles require Cygwin.</para>
+<para>
+MSYS is a lightweight alternative to Cygwin.
+You don't need MSYS to <emphasis>use</emphasis> GHC,
+but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
+Here's how to install MSYS.
+<itemizedlist>
+<listitem><para>
+Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
+download the following (of course, the version numbers will differ):
+<itemizedlist>
+ <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
+ </para></listitem>
+ <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
+ This provides <command>make</command>, <command>autoconf</command>,
+ <command>ssh</command>, <command>cvs</command> and probably more besides.
+ </para></listitem>
+</itemizedlist>
+Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
+</para></listitem>
-<para>The instructions that follow describe how to build GHC-mingw. It is
-possible to build GHC-cygwin, but it's not a supported route, and the build system might
-be flaky.</para>
+<listitem><para>
+Set the following environment variables
+<itemizedlist>
+ <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path. (Of course, the version number may differ.)
+ </para></listitem>
-<para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
-uses the <Command>gcc</Command> that you specify using the
-<option>--with-gcc</option> flag when you run
-<Command>configure</Command> (see below).
-The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
-to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
-whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
-and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
-used to glom together .o files into a bigger .o file, or a .a file,
-so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
-Cygwin and Mingw use the same .o file format. So its ok.
+ <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
+ This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
+ </para></listitem>
+
+ <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
+ </para></listitem>
+
+ <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
+ you are using CVS.
+ </para></listitem>
+
+ <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
+ </para></listitem>
+
+</itemizedlist>
+</para></listitem>
+
+<listitem><para>
+Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
+that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
+causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
+file has too-liberal permissinos.
+</para></listitem>
+
+</itemizedlist>
</para>
-</sect3>
-</sect2>
+<para>Here are some points to bear in mind when using MSYS:
+<itemizedlist>
+<listitem> <para> MSYS does some kind of special magic to binaries stored in
+<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
+to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
+Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
+they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
+which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
+
+<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
+</para></listitem>
-<Sect2><Title>Installing and configuring Cygwin</Title>
+<listitem> <para>
+Win32 has a <command>find</command> command which is not the same as MSYS's find.
+You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
+before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
+environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
+variable. You can always invoke <command>find</command> with an absolute path, or rename it.
+</para></listitem>
-<para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
-but you do need it to <emphasis>build</emphasis> GHC.</para>
+<listitem> <para>
+MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
+will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
+bzip'd dump.</para></listitem>
-<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:
-<command>cvs</command>, <command>openssh</command>,
-<command>autoconf</command>,
-<command>binutils</command> (includes ld and (I think) ar),
-<command>gcc</command>,
-<command>flex</command>,
-<command>make</command>.
+</itemizedlist>
+</para>
+</sect2>
+<sect2><title>Installing and configuring Cygwin</title>
+
+<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
+The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
+During the installation dialogue, make sure that you select all of the following:
+ <command>cvs</command>,
+ <command>openssh</command>,
+ <command>autoconf</command>,
+ <command>binutils</command> (includes ld and (I think) ar),
+ <command>gcc</command>,
+ <command>flex</command>,
+ <command>make</command>.
+If you miss out any of these, strange things will happen to you. To see thse packages,
+click on the "View" button in the "Select Packages"
+stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
+"Category" isn't very helpful, and the "View" button is rather unobtrousive.
</para>
<para> Now set the following user environment variables:
<itemizedlist>
<listitem>
<para>
-Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
+Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
don't do this you get very weird messages when you type
-<Command>make</Command>, such as:
-<Screen>
-/c: /c: No such file or directory
-</Screen>
+<command>make</command>, such as:
+<screen>/c: /c: No such file or directory</screen>
</para>
</listitem>
<listitem><para> Set <constant>SHELL</constant> to
-<Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
+<filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
<constant>SHELL</constant> is what you get.
</para></listitem>
<itemizedlist>
<listitem>
<para>
-Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
-(and similarly for <Command>bash</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.
+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>
-By default, cygwin provides the command shell <filename>ash</filename>
-as <filename>sh.exe</filename>. It has a couple of 'issues' (to do with quoting
-and length of command lines), so
-in your <filename>/bin</filename> directory, make sure that <filename>
-bash.exe</filename> is also provided as <filename>sh.exe</filename>
-(i.e. overwrite the old <filename>sh.exe</filename> with a copy of
-<filename>bash.exe</filename>).
+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></listitem>
<listitem> <para>
-Win32 has a <command>find</command> command which is not the same as Cygwin's find.
-You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
-before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
-environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
-variable. You can always invoke <command>find</command> with an absolute path, or rename it.
+See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
+which apply to Cygwin too.
</para></listitem>
</itemizedlist>
</para>
-</Sect2>
+</sect2>
+
+
+<sect2 id="configure-ssh"><title>Configuring SSH</title>
-<Sect2><Title>Other things you need to install</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>You have to install the following other things to build GHC:
+<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
+<itemizedlist>
+<listitem>
+<para>
+ The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
+ seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
+ they ask for a password). To solve this, start up <filename>cmd.exe</filename>
+ and run it as follows:
+<screen>c:\tmp> set CYGWIN32=tty
+c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
+</listitem>
+
+<listitem><para> (Cygwin-only problem, I think.)
+<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
+To determine your home directory <command>ssh</command> first looks in
+<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
+there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
+the setting of the environment variable $HOME</emphasis>. If the home directory is
+bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
+<programlisting>ssh -v cvs.haskell.org</programlisting>
+which makes <command>ssh</command> print out information about its activity.
+</para>
+<para> You can fix this problem, either by correcting the home-directory field in
+<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
+you do that, <command>ssh</command> uses the $HOME environment variable instead.
+</para>
+
+</listitem>
+
+<listitem>
+ <para>To protect your
+ <literal>.ssh</literal> from access by anyone else,
+ right-click your <literal>.ssh</literal> directory, and
+ select <literal>Properties</literal>. If you are not on
+ the access control list, add yourself, and give yourself
+ full permissions (the second panel). Remove everyone else
+ from the access control list. Don't leave them there but
+ deny them access, because 'they' may be a list that
+ includes you!</para>
+</listitem>
+
+<listitem>
+ <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
+ you to have Unix permissions 600 (read/write for owner only)
+ on the <literal>.ssh/identity</literal> file, else it
+ bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
+ but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
+ The solution seems to be to set the $CYGWIN environment
+ variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
+ in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
+ and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
+ </para>
+</listitem>
+</itemizedlist>
+</para>
+</sect2>
+
+<sect2><title>Other things you need to install</title>
+
+<para>You have to install the following other things to build GHC, listed below.</para>
+
+<para>On Windows you often install executables in directories with spaces, such as
+"<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
+deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
+to put binaries for all tools in places with no spaces in their path.
+On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
+<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
+provided they are in your path.
<itemizedlist>
<listitem>
<para>
<listitem>
<para>
Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
-Happy is a parser generator used to compile the Haskell grammar. Add it in your
+Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
+build it from the source distribution using
+<programlisting>./configure
+make
+make install</programlisting>
+This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
+on MSYS).
+Make sure the installation directory is in your
<constant>PATH</constant>.
</para>
</listitem>
+ <listitem>
+ <para>Install Alex. This can be done by building from the
+ source distribution in the same way as Happy. Sources are
+ available from <ulink
+ url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
+ </listitem>
<listitem>
<para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that. Just pick up a mingw bundle at
+generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
+Just pick up a mingw bundle at
<ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
We install it in <filename>c:/mingw</filename>.
</para>
<para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
They are only going to get used by explicit access (via the --with-gcc flag you
-give to <Command>configure</Command> later). If you do add them to your path
+give to <command>configure</command> later). If you do add them to your path
you are likely to get into a mess because their names overlap with Cygwin binaries.
</para>
</listitem>
<listitem>
+<para>We use <command>emacs</command> a lot, so we install that too.
+When you are in <filename>fptools/ghc/compiler</filename>, you can use
+"<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
+<filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
+The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
+The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
+so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
+</para>
+</listitem>
+
+
+<listitem>
<para> Finally, check out a copy of GHC sources from
-the CVS repository, following the instructions above (<xref linkend="cvs-access">).
+the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
-<Sect2><Title>Building GHC</Title>
+<sect2><title>Building GHC</title>
<para>OK!
-Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
+Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
the bullets below only tell
you about Windows-specific wrinkles.</para>
-<ItemizedList>
+<itemizedlist>
<listitem>
<para>
-Run <Command>autoconf</Command> both in <filename>fptools</filename>
-and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
-get an error when you run <filename>./configure</filename>:
-<Screen>
+If you used <command>autoconf</command> instead of <command>autoreconf</command>,
+you'll get an error when you run <filename>./configure</filename>:
+<screen>
...lots of stuff...
creating mk/config.h
mk/config.h is unchanged
configuring in ghc
running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
./configure: ./configure: No such file or directory
-configure: error: ./configure failed for ghc
-</Screen>
+configure: error: ./configure failed for ghc</screen>
</para>
</listitem>
-<listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
-read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
+<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
+read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
you get
-<screen>
-/usr/bin/autoconf: cannot create configure: permission denied
-</screen>
+<screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
Solution: delete <filename>configure</filename> first.
</para></listitem>
<listitem>
-<para>
-You either need to add <filename>ghc</filename> to your
-<constant>PATH</constant> before you invoke
-<Command>configure</Command>, or use the <Command>configure</Command>
-option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
-</para>
-</listitem>
-
-<listitem><para>
-If you are paranoid, delete <filename>config.cache</filename> if it exists.
-This file occasionally remembers out-of-date configuration information, which
-can be really confusing.
-</para>
-</listitem>
-
-<listitem>
<para>
- After <command>autoconf</command> run <command>./configure</command> in
+ After <command>autoreconf</command> run <command>./configure</command> in
<filename>fptools/</filename> thus:
-<Screen>
- ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
-</Screen>
+<screen>./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
This is the point at which you specify that you are building GHC-mingw
-(see <xref linkend="ghc-mingw">). </para>
+(see <xref linkend="ghc-mingw"/>). </para>
<para> Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
-Furthermore, it's very important that you specify a
-full mingw path for <command>gcc</command>, not a cygwin path, because GHC (which
-uses this path to invoke <command>gcc</command>) is a Mingw program and won't
-understand a cygwin path.. For example, if you
+trouble using the wrong C compiler!</para>
+<para>
+Furthermore, it's <emphasis>very important</emphasis> that you specify a
+full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
+uses this path to invoke <command>gcc</command>) is a MinGW program and won't
+understand a Cygwin path. For example, if you
say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
<filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
-time it tries to invoke it. (Worse, the failure does not come with
-a helpful error message, unfortunately.)
+time it tries to invoke it. Worse, the failure comes with
+no error message whatsoever. GHC simply fails silently when first invoked,
+typically leaving you with this:
+<screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
+../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
+ -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
+ -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
+ -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
+ -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
+ -optc-fomit-frame-pointer -O2 -static
+ -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
+make[2]: *** [Adjustor.o] Error 1
+make[1]: *** [all] Error 1
+make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make: *** [all] Error 1</screen>
+Be warned!
</para>
<para>
-If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
+If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
you'll have to do something more like:
-<Screen>
- ./configure --with-gcc=...the Cygwin gcc...
-</Screen>
+<screen>./configure --with-gcc=...the Cygwin gcc...</screen>
+</para>
+</listitem>
+
+<listitem><para>
+If you are paranoid, delete <filename>config.cache</filename> if it exists.
+This file occasionally remembers out-of-date configuration information, which
+can be really confusing.
+</para>
+</listitem>
+
+<listitem><para> You almost certainly want to set
+<programlisting>SplitObjs = NO</programlisting>
+in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
+This tells the build system not to split each library into a myriad of little object files, one
+for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
+it dramatically increases the time taken to build the libraries in the first place.
</para>
</listitem>
<listitem><para> Do not attempt to build the documentation.
It needs all kinds of wierd Jade stuff that we haven't worked out for
Win32.</para></listitem>
-</ItemizedList>
-</Sect2>
+</itemizedlist>
+</sect2>
</sect1>
-</Article>
+</article>
projects / ghc-hetmet.git / blobdiff