-<VarListEntry>
-<Term>DocBook:</Term>
-<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
-<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
-<ListItem>
-<para>
-All our documentation is written in SGML, using the DocBook DTD.
-Instructions on installing and configuring the DocBook tools are in the
-installation guide (in the GHC user guide).
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>TeX:</Term>
-<IndexTerm><Primary>pre-supposed: TeX</Primary></IndexTerm>
-<IndexTerm><Primary>TeX, pre-supposed</Primary></IndexTerm>
-<ListItem>
-<para>
-A decent TeX distribution is required if you want to produce printable
-documentation. We recomment teTeX, which includes just about
-everything you need.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-</Sect2>
-
-<Sect2 id="pre-supposed-other-tools">
-<Title>Other useful tools
-</Title>
-
-<VariableList>
-<VarListEntry>
-<Term>Flex:</Term>
-<IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm>
-<IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
-<ListItem>
-
-<para>
-This is a quite-a-bit-better-than-Lex lexer. Used to build a couple
-of utilities in <Literal>glafp-utils</Literal>. Depending on your
-operating system, the supplied <Command>lex</Command> may or may not
-work; you should get the GNU version.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="sec-building-from-source">
-<Title>Building from source
-
-<IndexTerm><Primary>Building from source</Primary></IndexTerm>
-<IndexTerm><Primary>Source, building from</Primary></IndexTerm></Title>
-
-<para>
-You've been rash enough to want to build some of
-the Glasgow Functional Programming tools (GHC, Happy,
-nofib, etc.) from source. You've slurped the source,
-from the CVS repository or from a source distribution, and
-now you're sitting looking at a huge mound of bits, wondering
-what to do next.
-</para>
-
-<para>
-Gingerly, you type <Command>make</Command>. Wrong already!
-</para>
-
-<para>
-This rest of this guide is intended for duffers like me, who aren't
-really interested in Makefiles and systems configurations, but who
-need a mental model of the interlocking pieces so that they can make
-them work, extend them consistently when adding new software, and lay
-hands on them gently when they don't work.
-</para>
-
-<Sect2 id="sec-source-tree">
-<Title>Your source tree
-</Title>
-
-<para>
-The source code is held in your <Emphasis>source tree</Emphasis>.
-The root directory of your source tree <Emphasis>must</Emphasis>
-contain the following directories and files:
-</para>
-
-<para>
-
-<ItemizedList>
-<ListItem>
-
-<para>
-<Filename>Makefile</Filename>: the root Makefile.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
-<Filename>mk/</Filename>: the directory that contains the
-main Makefile code, shared by all the
-<Literal>fptools</Literal> software.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- <Filename>configure.in</Filename>, <Filename>config.sub</Filename>, <Filename>config.guess</Filename>:
-these files support the configuration process.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- <Filename>install-sh</Filename>.
-</para>
-</ListItem>
-
-</ItemizedList>
-
-</para>
-
-<para>
-All the other directories are individual <Emphasis>projects</Emphasis> of the
-<Literal>fptools</Literal> system—for example, the Glasgow Haskell Compiler
-(<Literal>ghc</Literal>), the Happy parser generator (<Literal>happy</Literal>), the <Literal>nofib</Literal> benchmark
-suite, and so on. You can have zero or more of these. Needless to
-say, some of them are needed to build others.
-</para>
-
-<para>
-The important thing to remember is that even if you want only one
-project (<Literal>happy</Literal>, say), you must have a source tree whose root
-directory contains <Filename>Makefile</Filename>, <Filename>mk/</Filename>, <Filename>configure.in</Filename>, and the
-project(s) you want (<Filename>happy/</Filename> in this case). You cannot get by with
-just the <Filename>happy/</Filename> directory.
-</para>
-
-</Sect2>
-
-<Sect2>
-<Title>Build trees
-<IndexTerm><Primary>build trees</Primary></IndexTerm>
-<IndexTerm><Primary>link trees, for building</Primary></IndexTerm></Title>
-
-<para>
-While you can build a system in the source tree, we don't recommend it.
-We often want to build multiple versions of our software
-for different architectures, or with different options (e.g. profiling).
-It's very desirable to share a single copy of the source code among
-all these builds.
-</para>
-
-<para>
-So for every source tree we have zero or more <Emphasis>build trees</Emphasis>. Each
-build tree is initially an exact copy of the source tree, except that
-each file is a symbolic link to the source file, rather than being a
-copy of the source file. There are ``standard'' Unix utilities that
-make such copies, so standard that they go by different names:
-<Command>lndir</Command><IndexTerm><Primary>lndir</Primary></IndexTerm>, <Command>mkshadowdir</Command><IndexTerm><Primary>mkshadowdir</Primary></IndexTerm> are two (If you
-don't have either, the source distribution includes sources for the
-X11 <Command>lndir</Command>—check out <Filename>fptools/glafp-utils/lndir</Filename>). See <Xref LinkEnd="sec-storysofar"> for a typical invocation.
-</para>
-
-<para>
-The build tree does not need to be anywhere near the source tree in
-the file system. Indeed, one advantage of separating the build tree
-from the source is that the build tree can be placed in a
-non-backed-up partition, saving your systems support people from
-backing up untold megabytes of easily-regenerated, and
-rapidly-changing, gubbins. The golden rule is that (with a single
-exception—<XRef LinkEnd="sec-build-config">)
-<Emphasis>absolutely everything in the build tree is either a symbolic
-link to the source tree, or else is mechanically generated</Emphasis>.
-It should be perfectly OK for your build tree to vanish overnight; an
-hour or two compiling and you're on the road again.
-</para>
-
-<para>
-You need to be a bit careful, though, that any new files you create
-(if you do any development work) are in the source tree, not a build tree!
-</para>
-
-<para>
-Remember, that the source files in the build tree are <Emphasis>symbolic
-links</Emphasis> to the files in the source tree. (The build tree soon
-accumulates lots of built files like <Filename>Foo.o</Filename>, as well.) You
-can <Emphasis>delete</Emphasis> a source file from the build tree without affecting
-the source tree (though it's an odd thing to do). On the other hand,
-if you <Emphasis>edit</Emphasis> a source file from the build tree, you'll edit the
-source-tree file directly. (You can set up Emacs so that if you edit
-a source file from the build tree, Emacs will silently create an
-edited copy of the source file in the build tree, leaving the source
-file unchanged; but the danger is that you think you've edited the
-source file whereas actually all you've done is edit the build-tree
-copy. More commonly you do want to edit the source file.)
-</para>
-
-<para>
-Like the source tree, the top level of your build tree must be (a
-linked copy of) the root directory of the <Literal>fptools</Literal> suite. Inside
-Makefiles, the root of your build tree is called
-<Constant>$(FPTOOLS_TOP)</Constant><IndexTerm><Primary>FPTOOLS_TOP</Primary></IndexTerm>. In the rest of this document path
-names are relative to <Constant>$(FPTOOLS_TOP)</Constant> unless otherwise stated. For
-example, the file <Filename>ghc/mk/target.mk</Filename> is actually
-<Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc/mk/target.mk</Filename>.
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-build-config">
-<Title>Getting the build you want
-</Title>
-
-<para>
-When you build <Literal>fptools</Literal> you will be compiling code on a particular
-<Emphasis>host platform</Emphasis>, to run on a particular <Emphasis>target platform</Emphasis>
-(usually the same as the host platform)<IndexTerm><Primary>platform</Primary></IndexTerm>. The
-difficulty is that there are minor differences between different
-platforms; minor, but enough that the code needs to be a bit different
-for each. There are some big differences too: for a different
-architecture we need to build GHC with a different native-code
-generator.
-</para>
-
-<para>
-There are also knobs you can turn to control how the <Literal>fptools</Literal>
-software is built. For example, you might want to build GHC optimised
-(so that it runs fast) or unoptimised (so that you can compile it fast
-after you've modified it. Or, you might want to compile it with
-debugging on (so that extra consistency-checking code gets included)
-or off. And so on.
-</para>
-
-<para>
-All of this stuff is called the <Emphasis>configuration</Emphasis> of your build.
-You set the configuration using a three-step process.
-<VariableList>
-
-<VarListEntry>
-<Term>Step 1: get ready for configuration.</Term>
-<ListItem>
- <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>
- to a shell script called
- <Filename><Constant>$(FPTOOLS_TOP)</Constant>/configure</Filename>.
- </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>In case you don't have <Command>autoconf</Command>
- we distribute the results, <Command>configure</Command>,
- and <Filename>mk/config.h.in</Filename>, with the source
- distribution. They aren't kept in the repository,
- though.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Step 2: system configuration.</term>
- <listitem>
- <para>Runs the newly-created
- <Command>configure</Command> script, thus:</para>
-
-<ProgramListing>
-./configure <optional><parameter>args</parameter></optional>
-</ProgramListing>
-
- <para><Command>configure</Command>'s mission is to
- scurry round your computer working out what architecture
- it has, what operating system, whether it has the
- <Function>vfork</Function> system call, where
- <Command>yacc</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 communicates these snippets of
- information in two ways:</para>
-
- <itemizedlist>
- <listitem>
-
- <para>It translates
- <Filename>mk/config.mk.in</Filename><IndexTerm><Primary>config.mk.in</Primary></IndexTerm>
- to
- <Filename>mk/config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm>,
- substituting for things between
- ``<Literal>@</Literal>'' brackets. So,
- ``<Literal>@HaveGcc@</Literal>'' will be replaced by
- ``<Literal>YES</Literal>'' or
- ``<Literal>NO</Literal>'' depending on what
- <Command>configure</Command> finds.
- <Filename>mk/config.mk</Filename> is included by
- every Makefile (directly or indirectly), so the
- configuration information is thereby communicated to
- all Makefiles.</para>
- </ListItem>
-
- <listitem>
- <para> It translates
- <Filename>mk/config.h.in</Filename><IndexTerm><Primary>config.h.in</Primary></IndexTerm>
- to
- <Filename>mk/config.h</Filename><IndexTerm><Primary>config.h</Primary></IndexTerm>.
- The latter is <Literal>#include</Literal>d by
- various C programs, which can thereby make use of
- configuration information.</para>
- </listitem>
- </itemizedlist>
-
- <para><command>configure</command> takes some optional
- arguments. Use <literal>./configure --help</literal> to
- get a list of the available arguments. Here are some of
- the ones you might need:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-ghc</literal></primary>
- </indexterm>
- <listitem>
- <para>Specifies the path to an installed GHC which
- you would like to use. This compiler will be used
- for compiling GHC-specific code (eg. GHC itself).
- This option <emphasis>cannot</emphasis> be
- specified using <filename>build.mk</filename> (see
- later), because <command>configure</command> needs
- to auto-detect the version of GHC you're using.
- The default is to look for a compiler named
- <literal>ghc</literal> in your path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>--with-hc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-hc</literal></primary>
- </indexterm>
- <listitem>
- <para>Specifies the path to any installed Haskell
- compiler. This compiler will be used for
- compiling generic Haskell code. The default is to
- use <literal>ghc</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
- <indexterm><primary><literal>--with-gcc</literal></primary>
- </indexterm>
- <listitem>
- <para>Specifies the path to the installed
- GCC. This compiler will be used to compile all C
- files, <emphasis>except</emphasis> any generated
- by the installed Haskell compiler, which will have
- its own idea of which C compiler (if any) to use.
- The default is to use <literal>gcc</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <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>
-
-<VarListEntry>
-<Term>Step 3: build configuration.</Term>
-<ListItem>
-<para>
-Next, you say how this build of <Literal>fptools</Literal> is to differ from the
-standard defaults by creating a new file <Filename>mk/build.mk</Filename><IndexTerm><Primary>build.mk</Primary></IndexTerm>
-<Emphasis>in the build tree</Emphasis>. This file is the one and only file you edit
-in the build tree, precisely because it says how this build differs
-from the source. (Just in case your build tree does die, you might
-want to keep a private directory of <Filename>build.mk</Filename> files, and use a
-symbolic link in each build tree to point to the appropriate one.) So
-<Filename>mk/build.mk</Filename> never exists in the source tree—you create one in
-each build tree from the template. We'll discuss what to put in it
-shortly.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-And that's it for configuration. Simple, eh?
-</para>
-
- <para>What do you put in your build-specific configuration file
- <filename>mk/build.mk</filename>? <Emphasis>For almost all
- purposes all you will do is put make variable definitions that
- override those in</Emphasis>
- <filename>mk/config.mk.in</filename>. The whole point of
- <filename>mk/config.mk.in</filename>—and its derived
- counterpart <filename>mk/config.mk</filename>—is to define
- the build configuration. It is heavily commented, as you will
- see if you look at it. So generally, what you do is look at
- <filename>mk/config.mk.in</filename>, and add definitions in
- <filename>mk/build.mk</filename> that override any of the
- <filename>config.mk</filename> definitions that you want to
- change. (The override occurs because the main boilerplate file,
- <filename>mk/boilerplate.mk</filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>,
- includes <filename>build.mk</filename> after
- <filename>config.mk</filename>.)</para>
-
- <para>For example, <filename>config.mk.in</filename> contains
- the definition:</para>
-
-<ProgramListing>
-GhcHcOpts=-O -Rghc-timing
-</ProgramListing>
-
- <para>The accompanying comment explains that this is the list of
- flags passed to GHC when building GHC itself. For doing
- development, it is wise to add <literal>-DDEBUG</literal>, to
- enable debugging code. So you would add the following to
- <filename>build.mk</filename>:</para>
-
- <para>or, if you prefer,</para>
-
-<ProgramListing>
-GhcHcOpts += -DDEBUG
-</ProgramListing>
-
- <para>GNU <Command>make</Command> allows existing definitions to
- have new text appended using the ``<Literal>+=</Literal>''
- operator, which is quite a convenient feature.)</para>
-
- <para>If you want to remove the <literal>-O</literal> as well (a
- good idea when developing, because the turn-around cycle gets a
- lot quicker), you can just override
- <literal>GhcLibHcOpts</literal> altogether:</para>
-
-<ProgramListing>
-GhcHcOpts=-DDEBUG -Rghc-timing
-</ProgramListing>
-
- <para>When reading <filename>config.mk.in</filename>, remember
- that anything between ``@...@'' signs is going to be substituted
- by <Command>configure</Command> later. You
- <Emphasis>can</Emphasis> override the resulting definition if
- you want, but you need to be a bit surer what you are doing.
- For example, there's a line that says:</para>
-
-<ProgramListing>
-YACC = @YaccCmd@
-</ProgramListing>
-
- <para>This defines the Make variables <Constant>YACC</Constant>
- to the pathname for a <Command>yacc</Command> that
- <Command>configure</Command> finds somewhere. If you have your
- own pet <Command>yacc</Command> you want to use instead, that's
- fine. Just add this line to <filename>mk/build.mk</filename>:</para>
-
-<ProgramListing>
-YACC = myyacc
-</ProgramListing>
-
- <para>You do not <Emphasis>have</Emphasis> to have a
- <filename>mk/build.mk</filename> file at all; if you don't,
- you'll get all the default settings from
- <filename>mk/config.mk.in</filename>.</para>
-
- <para>You can also use <filename>build.mk</filename> to override
- anything that <Command>configure</Command> got wrong. One place
- where this happens often is with the definition of
- <Constant>FPTOOLS_TOP_ABS</Constant>: this
- variable is supposed to be the canonical path to the top of your
- source tree, but if your system uses an automounter then the
- correct directory is hard to find automatically. If you find
- that <Command>configure</Command> has got it wrong, just put the
- correct definition in <filename>build.mk</filename>.</para>
-
-</Sect2>
-
-<Sect2 id="sec-storysofar">
-<Title>The story so far</Title>