diff options
| author | panne <unknown> | 2004-06-02 08:53:54 +0000 |
|---|---|---|
| committer | panne <unknown> | 2004-06-02 08:53:54 +0000 |
| commit | bd08f5336fd6a0982e058c2cc58ff9693db28de3 (patch) | |
| tree | 6e3bc6ac92b93d5ca1e9451356c2d491b2f5f846 /docs/building | |
| parent | 729a6eb1de3041883bd82c46864e1b5f50855b59 (diff) | |
| download | haskell-bd08f5336fd6a0982e058c2cc58ff9693db28de3.tar.gz | |
[project @ 2004-06-02 08:53:54 by panne]
Make the Building Guide almost valid DocBook XML V4.2 (to get the real thing,
simply add an XML prolog and change "artheader" to "articleinfo"). Things that
had to be changed:
* XML tags are case-sensitive, so lowercase must be used for tags/attributes
* Make "xref" an empty element.
* "constant" is not allowed within "filename"
* Move "indexterm" to a valid place.
* Change some "&" to "&"
* The "_" character in titles makes some trouble in the TeX backend => avoid it
Diffstat (limited to 'docs/building')
| -rw-r--r-- | docs/building/building.sgml | 917 |
1 files changed, 492 insertions, 425 deletions
diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 0e2b2544f2..ecac3764ad 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -1,13 +1,13 @@ <!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 @@ -17,16 +17,16 @@ 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"> @@ -64,9 +64,7 @@ </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 @@ -84,7 +82,7 @@ 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> @@ -113,8 +111,8 @@ <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> @@ -156,7 +154,7 @@ </listitem> <listitem> - <para>Now go to <xref linkend="cvs-first">.</para> + <para>Now go to <xref linkend="cvs-first"/>.</para> </listitem> </orderedlist> </sect3> @@ -246,7 +244,7 @@ <para> - <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis> + <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis> </para> @@ -270,7 +268,7 @@ <listitem> <para>Set the following environment variables:</para> - <ItemizedList> + <itemizedlist> <listitem> <para> <constant>$HOME</constant>: points to your home directory. This is where CVS @@ -318,7 +316,7 @@ </para> </listitem> - </ItemizedList> + </itemizedlist> </listitem> @@ -328,12 +326,12 @@ Put the following in <filename>$HOME/.cvsrc</filename>: </para> - <ProgramListing> + <programlisting> checkout -P release -d update -P diff -u - </ProgramListing> + </programlisting> <para> These are the default options for the specified CVS commands, @@ -403,10 +401,10 @@ some other junk. </para> <para>[Windows users.] The following messages appear to be harmless: -<Screen> +<screen> setsockopt IPTOS_LOWDELAY: Invalid argument setsockopt IPTOS_THROUGHPUT: Invalid argument -</Screen> +</screen> </para> @@ -437,7 +435,7 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument 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> @@ -726,9 +724,10 @@ $ cvs checkout nofib/spectral <variablelist> <varlistentry> - <term><literal>alex</literal></term> - <indexterm><primary><literal>alex</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 @@ -737,9 +736,11 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term><literal>ghc</literal></term> - <indexterm><primary><literal>ghc</literal></primary> - <secondary>project</secondary></indexterm> + <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 @@ -748,8 +749,10 @@ $ cvs checkout nofib/spectral </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 @@ -758,8 +761,10 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term><literal>greencard</literal></term> - <indexterm><primary><literal>greencard</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/">GreenCard</ulink> @@ -769,8 +774,10 @@ $ cvs checkout nofib/spectral </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> @@ -779,8 +786,10 @@ $ cvs checkout nofib/spectral </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> @@ -789,8 +798,10 @@ $ cvs checkout nofib/spectral </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 @@ -799,8 +810,10 @@ $ cvs checkout nofib/spectral </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> @@ -809,8 +822,10 @@ $ cvs checkout nofib/spectral </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> @@ -818,8 +833,10 @@ $ cvs checkout nofib/spectral </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> @@ -827,8 +844,10 @@ $ cvs checkout nofib/spectral </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> @@ -836,16 +855,20 @@ $ cvs checkout nofib/spectral </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> @@ -853,8 +876,10 @@ $ cvs checkout nofib/spectral </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> @@ -876,9 +901,8 @@ $ cvs checkout nofib/spectral <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> @@ -886,23 +910,23 @@ $ cvs checkout nofib/spectral <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> @@ -978,13 +1002,13 @@ $ cvs checkout nofib/spectral <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 @@ -994,8 +1018,9 @@ $ cvs checkout nofib/spectral </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> @@ -1003,8 +1028,9 @@ $ cvs checkout nofib/spectral </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 and 2.6), including native-code generator.</para> @@ -1012,8 +1038,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>sparc-unknown-openbsd</term> - <indexterm><primary>sparc-unknown-openbsd</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> @@ -1021,8 +1048,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term> - <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm> + <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 @@ -1031,11 +1059,12 @@ $ cvs checkout nofib/spectral </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 @@ -1047,9 +1076,9 @@ $ cvs checkout nofib/spectral </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 @@ -1060,8 +1089,9 @@ $ cvs checkout nofib/spectral </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 @@ -1070,8 +1100,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>i386-unknown-netbsd (PCs running NetBSD)</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> @@ -1079,8 +1110,9 @@ $ cvs checkout nofib/spectral </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 @@ -1091,8 +1123,9 @@ $ cvs checkout nofib/spectral </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> @@ -1100,8 +1133,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>x86_64-unknown-linux</term> - <indexterm><primary>x86_64-unknown-linux</primary></indexterm> + <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> @@ -1109,8 +1143,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>amd64-unknown-openbsd</term> - <indexterm><primary>amd64-unknown-linux</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 @@ -1119,8 +1154,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>mips-sgi-irix5</term> - <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm> + <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 @@ -1131,16 +1167,18 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>mips64-sgi-irix6</term> - <indexterm><primary>mips-sgi-irix6</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</term> - <indexterm><primary>powerpc-ibm-aix</primary></indexterm> + <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 @@ -1150,8 +1188,9 @@ $ cvs checkout nofib/spectral </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. Native code generator is almost working.</para> @@ -1159,8 +1198,9 @@ $ cvs checkout nofib/spectral </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> @@ -1199,14 +1239,15 @@ $ cvs checkout nofib/spectral <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 @@ -1216,9 +1257,10 @@ $ cvs checkout nofib/spectral </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 @@ -1240,10 +1282,10 @@ $ cvs checkout nofib/spectral </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 @@ -1265,9 +1307,9 @@ $ cvs checkout nofib/spectral </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 @@ -1277,8 +1319,9 @@ $ cvs checkout nofib/spectral </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 @@ -1294,8 +1337,9 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>Alex</term> - <indexterm><primary>Alex</primary></indexterm> + <term>Alex + <indexterm><primary>Alex</primary></indexterm> + </term> <listitem> <para>Alex is a lexical-analyser generator for Haskell, which GHC uses to generate its lexer. Like Happy, Alex is @@ -1307,9 +1351,10 @@ $ cvs checkout nofib/spectral </varlistentry> <varlistentry> - <term>autoconf</term> - <indexterm><primary>pre-supposed: autoconf</primary></indexterm> - <indexterm><primary>autoconf, pre-supposed</primary></indexterm> + <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 @@ -1329,9 +1374,10 @@ $ cvs checkout nofib/spectral </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 @@ -1355,9 +1401,10 @@ $ cvs checkout nofib/spectral <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 @@ -1379,8 +1426,9 @@ $ cvs checkout nofib/spectral </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, @@ -1396,9 +1444,10 @@ $ cvs checkout nofib/spectral <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 @@ -1411,7 +1460,7 @@ $ cvs checkout nofib/spectral <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> @@ -1533,8 +1582,8 @@ $ make install 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 @@ -1542,8 +1591,8 @@ $ make install 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 @@ -1578,7 +1627,7 @@ $ make install <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"> @@ -1617,15 +1666,15 @@ $ make install <para>Change directory to <constant>$(FPTOOLS_TOP)</constant> and issue the command</para> -<ProgramListing> +<programlisting> autoreconf -</ProgramListing> +</programlisting> <indexterm><primary>autoreconf</primary></indexterm> <para>(with no arguments). This GNU program (recursively) converts - <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename> and - <filename><constant>$(FPTOOLS_TOP)</constant>/aclocal.m4</filename> + <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 @@ -1635,7 +1684,7 @@ autoreconf <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 - <constant>$(FPTOOLS_TOP)</constant>.</para> + <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 @@ -1651,14 +1700,14 @@ autoreconf <para>Runs the newly-created <command>configure</command> script, thus:</para> -<ProgramListing> +<programlisting> ./configure <optional><parameter>args</parameter></optional> -</ProgramListing> +</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 + <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 @@ -1703,9 +1752,9 @@ autoreconf <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 @@ -1720,9 +1769,9 @@ autoreconf </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 @@ -1732,9 +1781,9 @@ autoreconf </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, @@ -1795,9 +1844,9 @@ autoreconf <para>For example, <filename>config.mk.in</filename> contains the definition:</para> -<ProgramListing> +<programlisting> GhcHcOpts=-O -Rghc-timing -</ProgramListing> +</programlisting> <para>The accompanying comment explains that this is the list of flags passed to GHC when building GHC itself. For doing @@ -1807,9 +1856,9 @@ GhcHcOpts=-O -Rghc-timing <para>or, if you prefer,</para> -<ProgramListing> +<programlisting> GhcHcOpts += -DDEBUG -</ProgramListing> +</programlisting> <para>GNU <command>make</command> allows existing definitions to have new text appended using the “<literal>+=</literal>” @@ -1820,9 +1869,9 @@ GhcHcOpts += -DDEBUG lot quicker), you can just override <literal>GhcLibHcOpts</literal> altogether:</para> -<ProgramListing> +<programlisting> GhcHcOpts=-DDEBUG -Rghc-timing -</ProgramListing> +</programlisting> <para>When reading <filename>config.mk.in</filename>, remember that anything between “@...@” signs is going to be substituted @@ -1831,9 +1880,9 @@ GhcHcOpts=-DDEBUG -Rghc-timing you want, but you need to be a bit surer what you are doing. For example, there's a line that says:</para> -<ProgramListing> +<programlisting> TAR = @TarCmd@ -</ProgramListing> +</programlisting> <para>This defines the Make variables <constant>TAR</constant> to the pathname for a <command>tar</command> that @@ -1841,9 +1890,9 @@ TAR = @TarCmd@ 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> +<programlisting> TAR = mytar -</ProgramListing> +</programlisting> <para>You do not <emphasis>have</emphasis> to have a <filename>mk/build.mk</filename> file at all; if you don't, @@ -1874,8 +1923,8 @@ TAR = mytar 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> @@ -2207,8 +2256,8 @@ $ emacs mk/build.mk <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> @@ -2224,9 +2273,9 @@ $ emacs mk/build.mk generated <filename>.depend</filename> file will contain the dependency:</para> -<ProgramListing> +<programlisting> Foo.o : Baz.hi -</ProgramListing> +</programlisting> <para>which says that the object file <filename>Foo.o</filename> depends on the interface file @@ -2293,9 +2342,9 @@ Foo.o : Baz.hi <command>make</command> is going to rebuild everything anyway, the following hack may be useful:</para> -<ProgramListing> +<programlisting> gmake FAST=YES -</ProgramListing> +</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 @@ -2364,7 +2413,7 @@ gmake FAST=YES <indexterm><primary>Makefile, minimal</primary></indexterm> -<ProgramListing> +<programlisting> # Makefile for fptools project "small" TOP = .. @@ -2374,7 +2423,7 @@ SRCS = $(wildcard *.lhs) $(wildcard *.c) HS_PROG = small include $(TOP)/target.mk -</ProgramListing> +</programlisting> <para>this <filename>Makefile</filename> has three sections:</para> @@ -2393,11 +2442,11 @@ directive. 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> @@ -2409,9 +2458,9 @@ directive. directory in which the <filename>boilerplate.mk</filename> file is. It is <emphasis>not</emphasis> OK to simply say</para> -<ProgramListing> +<programlisting> include ../mk/boilerplate.mk # NO NO NO -</ProgramListing> +</programlisting> <para>Why? Because the <filename>boilerplate.mk</filename> @@ -2424,7 +2473,7 @@ include ../mk/boilerplate.mk # NO NO NO <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> @@ -2449,8 +2498,8 @@ include ../mk/boilerplate.mk # NO NO NO <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 @@ -2469,12 +2518,12 @@ include ../mk/boilerplate.mk # NO NO NO 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 @@ -2483,8 +2532,8 @@ include ../mk/boilerplate.mk # NO NO NO 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> @@ -2540,7 +2589,7 @@ include ../mk/boilerplate.mk # NO NO NO rare.) To give you the idea, here's part of the directory structure for the (rather large) GHC project:</para> -<Screen> +<screen> $(FPTOOLS_TOP)/ghc/ Makefile mk/ @@ -2557,14 +2606,14 @@ $(FPTOOLS_TOP)/ghc/ parser/...source files for parser... renamer/...source files for renamer... ...etc... -</Screen> +</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 @@ -2666,9 +2715,9 @@ $(FPTOOLS_TOP)/ghc/ <emphasis>augment</emphasis> them. For example, a <filename>Makefile</filename> might say:</para> -<ProgramListing> +<programlisting> SRC_HC_OPTS += -O -</ProgramListing> +</programlisting> <para>thereby adding “<option>-O</option>” to the end of @@ -2678,7 +2727,7 @@ SRC_HC_OPTS += -O <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 @@ -2695,13 +2744,13 @@ SRC_HC_OPTS += -O <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> +<programlisting> $(HS_PROG) : $(OBJS) $(HC) $(LD_OPTS) $< -o $@ -</ProgramListing> +</programlisting> <para>If this rule was in <filename>boilerplate.mk</filename> then @@ -2742,23 +2791,25 @@ $(HS_PROG) : $(OBJS) <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 @@ -2774,9 +2825,9 @@ $(HS_PROG) : $(OBJS) <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 @@ -2785,9 +2836,9 @@ $(HS_PROG) : $(OBJS) </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 @@ -2803,9 +2854,9 @@ $(HS_PROG) : $(OBJS) </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 @@ -2820,8 +2871,9 @@ $(HS_PROG) : $(OBJS) <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 @@ -2833,8 +2885,9 @@ $(HS_PROG) : $(OBJS) </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 @@ -2844,8 +2897,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2853,8 +2907,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2862,16 +2917,18 @@ $(HS_PROG) : $(OBJS) </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> @@ -2879,8 +2936,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2888,8 +2946,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2898,8 +2957,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2907,8 +2967,9 @@ $(HS_PROG) : $(OBJS) </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> @@ -2916,8 +2977,9 @@ $(HS_PROG) : $(OBJS) </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>, @@ -2943,23 +3005,25 @@ $(HS_PROG) : $(OBJS) </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> @@ -2988,11 +3052,11 @@ $(HS_PROG) : $(OBJS) <para>Almost all the rules look something like this:</para> -<ProgramListing> +<programlisting> %.o : %.c $(RM) $@ $(CC) $(CC_OPTS) -c $< -o $@ -</ProgramListing> +</programlisting> <para>Here's how to understand the rule. It says that <emphasis>something</emphasis><filename>.o</filename> (say @@ -3020,9 +3084,10 @@ $(HS_PROG) : $(OBJS) 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 @@ -3046,7 +3111,7 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) <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> @@ -3068,9 +3133,9 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) <para>extra options to pass to all C compilations. This is intended for command line use, thus:</para> -<ProgramListing> +<programlisting> gmake libHS.a EXTRA_CC_OPTS="-v" -</ProgramListing> +</programlisting> </listitem> </varlistentry> </variablelist> @@ -3081,8 +3146,8 @@ gmake libHS.a EXTRA_CC_OPTS="-v" <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 @@ -3176,10 +3241,10 @@ gmake libHS.a EXTRA_CC_OPTS="-v" <para>All of these rules are “double-colon” rules, thus</para> -<ProgramListing> +<programlisting> install :: $(HS_PROG) ...how to install it... -</ProgramListing> +</programlisting> <para>GNU <command>make</command> treats double-colon rules as separate entities. If there are several double-colon rules for @@ -3210,7 +3275,7 @@ install :: $(HS_PROG) <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> @@ -3299,8 +3364,8 @@ install :: $(HS_PROG) <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> @@ -3320,10 +3385,10 @@ install :: $(HS_PROG) file will match</emphasis>. The key pattern rules (in <filename>suffix.mk</filename>) look like this: -<ProgramListing> +<programlisting> %.$(way_)o : %.lhs $(HC) $(HC_OPTS) $< -o $@ -</ProgramListing> +</programlisting> Neat, eh?</para> </listitem> @@ -3371,9 +3436,10 @@ $ make way=p <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 @@ -3382,9 +3448,10 @@ $ make way=p </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, @@ -3393,9 +3460,9 @@ $ make way=p </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 @@ -3422,21 +3489,21 @@ $ make way=p <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> @@ -3460,17 +3527,17 @@ $ make way=p <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> @@ -3479,58 +3546,58 @@ $ make way=p <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> - 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> @@ -3538,7 +3605,7 @@ $ make way=p <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> @@ -3550,12 +3617,12 @@ $ make way=p <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> @@ -3633,14 +3700,14 @@ $ make install-docs 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> @@ -3666,7 +3733,7 @@ $ make install-docs 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> + linkend="unregisterised-porting"/>.</para> <para>The following steps should result in a working GHC build with full libraries:</para> @@ -3693,9 +3760,9 @@ $ make install-docs command will execute the whole build process (it won't install yet):</para> -<Screen> +<screen> foo% distrib/hc-build --prefix=<replaceable>dir</replaceable> -</Screen> +</screen> <indexterm><primary>--hc-build</primary></indexterm> <para>By default, the installation directory is @@ -3708,9 +3775,9 @@ foo% distrib/hc-build --prefix=<replaceable>dir</replaceable> build process, you can install the resulting system, as normal, with</para> -<Screen> +<screen> foo% make install -</Screen> +</screen> </listitem> </itemizedlist> </sect2> @@ -3891,8 +3958,8 @@ $ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen> <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 +$ 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> @@ -3901,14 +3968,14 @@ $ cd <replaceable>H</replaceable>/ghc && make boot && make <listitem> <screen> $ cd <replaceable>H</replaceable>/libraries -$& make boot && make +$ make boot && make </screen> </listitem> <listitem> <screen> $ cd <replaceable>H</replaceable>/ghc -$ make boot stage=2 && make stage=2 +$ make boot stage=2 && make stage=2 </screen> </listitem> @@ -3943,7 +4010,7 @@ $ make hc-file-bundle Project=Ghc 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> + described in <xref linkend="sec-booting-from-hc"/>.</para> <screen> $ ./distrib/hc-build --enable-hc-boot-unregisterised @@ -3993,9 +4060,9 @@ Hello World! <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 @@ -4005,19 +4072,19 @@ Hello World! </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> @@ -4028,9 +4095,9 @@ Hello World! </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 @@ -4038,12 +4105,12 @@ Hello World! </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> @@ -4137,7 +4204,7 @@ WARNINGS about pitfalls and known “problems”: <para> -<OrderedList> +<orderedlist> <listitem> <para> @@ -4153,9 +4220,9 @@ of choice). The best way around it is to say -<ProgramListing> +<programlisting> export TMPDIR=<dir> -</ProgramListing> +</programlisting> in your <filename>build.mk</filename> file. Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory @@ -4187,11 +4254,11 @@ incompatible pointer type” out of GCC. Harmless. Similarly, <command>ar</command>chiving warning messages like the following are not a problem: -<Screen> +<screen> ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ ... -</Screen> +</screen> </para> @@ -4231,15 +4298,15 @@ above. </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> +<screen> % cd ghc/compiler % make EXTRA_HC_OPTS=-optCrts-M128M -</Screen> +</screen> </para> @@ -4263,13 +4330,13 @@ this bug also suggests that you have an old GCC. You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s). -<Screen> +<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> +</screen> We'd be interested to know if this is still necessary. @@ -4285,18 +4352,18 @@ a bit from one Unix to another. One particular gotcha is macro calls like this: -<ProgramListing> +<programlisting> SLIT("Hello, world") -</ProgramListing> +</programlisting> Some <command>cpp</command>s treat the comma inside the string as separating two macro arguments, so you get -<Screen> +<screen> :731: macro `SLIT' used with too many (2) args -</Screen> +</screen> Alas, <command>cpp</command> doesn't tell you the offending file! @@ -4305,20 +4372,20 @@ Workaround: don't put weird things in string args to <command>cpp</command> macr </para> </listitem> -</OrderedList> +</orderedlist> </para> </sect1> -<Sect1 id="platforms"><Title>Platforms, scripts, and file names</Title> +<sect1 id="platforms"><title>Platforms, scripts, and file names</title> <para> GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter. </para> -<sect2 id="cygwin-and-mingw"><Title>Windows platforms: Cygwin, MSYS, and MinGW</Title> +<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title> <para> The build system is built around Unix-y makefiles. Because it's not native, the Windows situation for building GHC is particularly confusing. This section @@ -4410,14 +4477,14 @@ that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix libr 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 +<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 +<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. @@ -4452,7 +4519,7 @@ Cygwin programs have a more complicated mount table, and map the lettered drives </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: @@ -4470,12 +4537,12 @@ and 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> + <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. @@ -4523,7 +4590,7 @@ shortcomings of the native Windows <command>cmd</command> shell. </sect1> -<Sect1 id="winbuild"><Title>Instructions for building under Windows</Title> +<sect1 id="winbuild"><title>Instructions for building under Windows</title> <para> This section gives detailed instructions for how to build @@ -4532,13 +4599,13 @@ installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. </para> <para> -Make sure you read the preceding section on platforms (<xref linkend="platforms">) +Make sure you read the preceding section on platforms (<xref linkend="platforms"/>) before reading section. You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC, but you do need one or the other to <emphasis>build</emphasis> GHC.</para> -<Sect2 id=msys-install><Title>Installing and configuring MSYS</Title> +<sect2 id="msys-install"><title>Installing and configuring MSYS</title> <para> MSYS is a lightweight alternative to Cygwin. @@ -4621,10 +4688,10 @@ bzip'd dump.</para></listitem> </para> </sect2> -<Sect2><Title>Installing and configuring Cygwin</Title> +<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>. +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>, @@ -4646,17 +4713,17 @@ stage of Cygwin's installation dialogue, until the view says "Full". The defaul <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> +<command>make</command>, such as: +<screen> /c: /c: No such file or directory -</Screen> +</screen> </para> </listitem> <listitem><para> Set <constant>SHELL</constant> to -<Filename>c:/cygwin/bin/bash</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> @@ -4689,21 +4756,21 @@ you can't rename a running program! <listitem> <para> -Some script files used in the make system start with "<Command>#!/bin/perl</Command>", -(and similarly for <Command>sh</Command>). Notice the hardwired path! -So you need to ensure that your <Filename>/bin</Filename> directory has the following +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> +<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. +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> +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> @@ -4727,16 +4794,16 @@ they don't recognise symlinks. </para></listitem> <listitem> <para> -See the notes in <xref linkend="msys-install"> about <command>find</command> and <command>bzip</command>, +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 id="configure-ssh"><title>Configuring SSH</title> <para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command> @@ -4750,10 +4817,10 @@ you install Cygwin. (If not, the installer lets you update easily.) Look for < 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> + <screen> c:\tmp> set CYGWIN32=tty c:\tmp> c:/user/local/bin/ssh-keygen1 - </Screen> </para> + </screen> </para> </listitem> <listitem><para> (Cygwin-only problem, I think.) @@ -4803,7 +4870,7 @@ you do that, <command>ssh</command> uses the $HOME environment variable instead. </para> </sect2> -<Sect2><Title>Other things you need to install</Title> +<sect2><title>Other things you need to install</title> <para>You have to install the following other things to build GHC, listed below.</para> @@ -4850,14 +4917,14 @@ Make sure the installation directory is in your <listitem> <para>GHC uses the <emphasis>mingw</emphasis> C compiler to -generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">). +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> @@ -4877,25 +4944,25 @@ so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</li <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> -If you used <Command>autoconf</Command> instead of <Command>autoreconf</Command>, +If you used <command>autoconf</command> instead of <command>autoreconf</command>, you'll get an error when you run <filename>./configure</filename>: -<Screen> +<screen> ...lots of stuff... creating mk/config.h mk/config.h is unchanged @@ -4903,7 +4970,7 @@ 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> +</screen> </para> </listitem> @@ -4921,11 +4988,11 @@ Solution: delete <filename>configure</filename> first. After <command>autoreconf</command> run <command>./configure</command> in <filename>fptools/</filename> thus: -<Screen> +<screen> ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc -</Screen> +</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!</para> @@ -4942,7 +5009,7 @@ typically leaving you with this: <programlisting> 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-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 @@ -4957,11 +5024,11 @@ 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> +<screen> ./configure --with-gcc=...the Cygwin gcc... -</Screen> +</screen> </para> </listitem> @@ -4976,7 +5043,7 @@ can be really confusing. <programlisting> SplitObjs = NO </programlisting> -in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">). +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. @@ -4986,10 +5053,10 @@ it dramatically increases the time taken to build the libraries in the first pla <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> |