- <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-hhc</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>
- </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>
-
-<para>
-Let's summarise the steps you need to carry to get yourself
-a fully-configured build tree from scratch.
-</para>
-
-<para>
-
-<OrderedList>
-<ListItem>
-
-<para>
- Get your source tree from somewhere (CVS repository or source
-distribution). Say you call the root directory <filename>myfptools</filename> (it
-does not have to be called <filename>fptools</filename>). Make sure that you have
-the essential files (see <XRef LinkEnd="sec-source-tree">).
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Use <Command>lndir</Command> or <Command>mkshadowdir</Command> to create a build tree.
-
-<ProgramListing>
-cd myfptools
-mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
-</ProgramListing>
-
-(N.B. <Command>mkshadowdir</Command>'s first argument is taken relative to its second.) You probably want to give the build tree a name that
-suggests its main defining characteristic (in your mind at least),
-in case you later add others.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Change directory to the build tree. Everything is going
-to happen there now.
-
-<ProgramListing>
-cd /scratch/joe-bloggs/myfptools-sun4
-</ProgramListing>
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Prepare for system configuration:
-
-<ProgramListing>
-autoconf
-</ProgramListing>
-
-(You can skip this step if you are starting from a source distribution,
-and you already have <filename>configure</filename> and <filename>mk/config.h.in</filename>.)
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Do system configuration:
-
-<ProgramListing>
-./configure
-</ProgramListing>
-
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Create the file <filename>mk/build.mk</filename>,
-adding definitions for your desired configuration options.
-
-<ProgramListing>
-emacs mk/build.mk
-</ProgramListing>
-
-</para>
-</ListItem>
-
-</OrderedList>
-
-You can make subsequent changes to <filename>mk/build.mk</filename> as often
-as you like. You do not have to run any further configuration
-programs to make these changes take effect.
-In theory you should, however, say <Command>gmake clean</Command>, <Command>gmake all</Command>,
-because configuration option changes could affect anything—but in practice you are likely to know what's affected.
-</para>
-
-</Sect2>
-
- <Sect2>
- <Title>Making things</Title>
-
- <para>At this point you have made yourself a fully-configured
- build tree, so you are ready to start building real
- things.</para>
-
- <para>The first thing you need to know is that <Emphasis>you
- must use GNU <Command>make</Command>, usually called
- <Command>gmake</Command>, not standard Unix
- <Command>make</Command></Emphasis>. If you use standard Unix
- <Command>make</Command> you will get all sorts of error messages
- (but no damage) because the <Literal>fptools</Literal>
- <Command>Makefiles</Command> use GNU <Command>make</Command>'s
- facilities extensively.</para>
-
- <para>To just build the whole thing, <command>cd</command> to
- the top of your <literal>fptools</literal> tree and type
- <command>gmake</command>. This will prepare the tree and build
- the various projects in the correct order.</para>
-
- </Sect2>
-
- <Sect2 id="sec-standard-targets">
- <Title>Standard Targets</title>
- <IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm>
- <IndexTerm><Primary>makefile targets</Primary></IndexTerm>
-
- <para>In any directory you should be able to make the following:
-
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>boot</Literal>:</Term>
-<ListItem>
-<para>does the one-off preparation required to get ready for the real
-work. Notably, it does <Command>gmake depend</Command> in all
-directories that contain programs. It also builds the necessary tools
-for compilation to proceed.</para>
-
-<para>Invoking the <literal>boot</literal> target explicitly is not
-normally necessary. From the top-level <literal>fptools</literal>
-directory, invoking <literal>gmake</literal> causes <literal>gmake
-boot all</literal> to be invoked in each of the project
-subdirectories, in the order specified by
-<literal>$(AllTargets)</literal> in
-<literal>config.mk</literal>.</para>
-
-<para>If you're working in a subdirectory somewhere and need to update
-the dependencies, <literal>gmake boot</literal> is a good way to do it.</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>all</Literal>:</Term>
-<ListItem>
-<para>
-makes all the final target(s) for this Makefile.
-Depending on which directory you are in a ``final target'' may be an
-executable program, a library archive, a shell script, or a Postscript
-file. Typing <Command>gmake</Command> alone is generally the same as typing <Command>gmake all</Command>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>install</Literal>:</Term>
-<ListItem>
-<para>
-installs the things built by <Literal>all</Literal>. Where does it
-install them? That is specified by
-<filename>mk/config.mk.in</filename>; you can override it in
-<filename>mk/build.mk</filename>, or by running
-<command>configure</command> with command-line arguments like
-<literal>--bindir=/home/simonpj/bin</literal>; see <literal>./configure
---help</literal> for the full details.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>uninstall</Literal>:</Term>
-<ListItem>
-<para>
-reverses the effect of <Literal>install</Literal>.
-</para>
-</ListItem></VarListEntry>
-
-<VarListEntry>
-<Term><Literal>clean</Literal>:</Term>
-<ListItem>
-<para>
-Delete all files from the current directory that are normally created
-by building the program. Don't delete the files that record the
-configuration, or files generated by <Command>gmake boot</Command>.
-Also preserve files that could be made by building, but normally
-aren't because the distribution comes with them.</para>
-</ListItem></VarListEntry>
-
-<varlistentry>
-<term><literal>distclean</literal>:</term>
-<listitem>
-<para>Delete all files from the current directory that are created by
-configuring or building the program. If you have unpacked the source
-and built the program without creating any other files, <literal>make
-distclean</literal> should leave only the files that were in the
-distribution.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><literal>mostlyclean</literal>:</term>
-<listitem>
-<para>Like <literal>clean</literal>, but may refrain from deleting a
-few files that people normally don't want to recompile.</para>
-</listitem>
-</varlistentry>
-
-<VarListEntry>
-<Term><Literal>maintainer-clean</Literal>:</Term>
-<ListItem>
-<para>
-Delete everything from the current directory that can be reconstructed
-with this Makefile. This typically includes everything deleted by
-<literal>distclean</literal>, plus more: C source files produced by
-Bison, tags tables, Info files, and so on.</para>
-
-<para>One exception, however: <literal>make maintainer-clean</literal>
-should not delete <filename>configure</filename> even if
-<filename>configure</filename> can be remade using a rule in the
-<filename>Makefile</filename>. More generally, <literal>make
-maintainer-clean</literal> should not delete anything that needs to
-exist in order to run <filename>configure</filename> and then begin to
-build the program.</para>
-</listitem>
-</varlistentry>
-
-<VarListEntry>
-<Term><Literal>check</Literal>:</Term>
-<ListItem>
-<para>
-run the test suite.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-All of these standard targets automatically recurse into
-sub-directories. Certain other standard targets do not:
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>configure</Literal>:</Term>
-<ListItem>
-<para>
-is only available in the root directory
-<Constant>$(FPTOOLS_TOP)</Constant>; it has been discussed in <XRef LinkEnd="sec-build-config">.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>depend</Literal>:</Term>
-<ListItem>
-<para>
-make a <filename>.depend</filename> file in each directory that needs
-it. This <filename>.depend</filename> file contains mechanically-generated dependency
-information; for example, suppose a directory contains a Haskell
-source module <filename>Foo.lhs</filename> which imports another module <Literal>Baz</Literal>.
-Then the generated <filename>.depend</filename> file will contain the dependency:
-</para>
-
-<para>
-
-<ProgramListing>
-Foo.o : Baz.hi
-</ProgramListing>
-
-</para>
-
-<para>
-which says that the object file <filename>Foo.o</filename> depends on the interface file
-<filename>Baz.hi</filename> generated by compiling module <Literal>Baz</Literal>. The <filename>.depend</filename> file is
-automatically included by every Makefile.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>binary-dist</Literal>:</Term>
-<ListItem>
-<para>
-make a binary distribution. This is the
-target we use to build the binary distributions of GHC and Happy.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>dist</Literal>:</Term>
-<ListItem>
-<para>
-make a source distribution. Note that this target does “make
-distclean” as part of its work; don't use it if you want to keep
-what you've built.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-Most <filename>Makefile</filename>s have targets other than these. You can discover them by looking in the <filename>Makefile</filename> itself.
-</para>
-
-</Sect2>
-
-<sect2>
-<title>Using a project from the build tree</title>
-<para>
-If you want to build GHC (say) and just use it direct from the build
-tree without doing <literal>make install</literal> first, you can run
-the in-place driver script:
-<filename>ghc/compiler/ghc-inplace</filename>.
-</para>
-
-<para> Do <emphasis>NOT</emphasis> use
-<filename>ghc/compiler/ghc</filename>, or
-<filename>ghc/compiler/ghc-5.xx</filename>, as these are the scripts
-intended for installation, and contain hard-wired paths to the
-installed libraries, rather than the libraries in the build tree.
-</para>
-
-<para>
-Happy can similarly be run from the build tree, using
-<filename>happy/src/happy-inplace</filename>.
-</para>
-</sect2>
-
-<Sect2>
-<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm>
-<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
-<IndexTerm><Primary>FAST, makefile
-variable</Primary></IndexTerm></Title>
-
-<para>
-Sometimes the dependencies get in the way: if you've made a small
-change to one file, and you're absolutely sure that it won't affect
-anything else, but you know that <Command>make</Command> is going to rebuild everything
-anyway, the following hack may be useful:
-</para>
-
-<para>
-
-<ProgramListing>
-gmake FAST=YES
-</ProgramListing>
-
-</para>
-
-<para>
-This tells the make system to ignore dependencies and just build what
-you tell it to. In other words, it's equivalent to temporarily
-removing the <filename>.depend</filename> file in the current directory (where
-<Command>mkdependHS</Command> and friends store their dependency information).
-</para>
-
-<para>
-A bit of history: GHC used to come with a <Command>fastmake</Command> script that did
-the above job, but GNU make provides the features we need to do it
-without resorting to a script. Also, we've found that fastmaking is
-less useful since the advent of GHC's recompilation checker (see the
-User's Guide section on "Separate Compilation").
-</para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="sec-makefile-arch">
-<Title>The <filename>Makefile</filename> architecture
-<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
-
-<para>
-<Command>make</Command> is great if everything works—you type <Command>gmake install</Command> and
-lo! the right things get compiled and installed in the right places.
-Our goal is to make this happen often, but somehow it often doesn't;
-instead some weird error message eventually emerges from the bowels of
-a directory you didn't know existed.
-</para>
-
-<para>
-The purpose of this section is to give you a road-map to help you figure
-out what is going right and what is going wrong.
-</para>
-
-<Sect2>
-<Title>A small project</Title>
-
-<para>
-To get started, let us look at the <filename>Makefile</filename> for an imaginary small
-<Literal>fptools</Literal> project, <Literal>small</Literal>. Each project in <Literal>fptools</Literal> has its own
-directory in <Constant>FPTOOLS_TOP</Constant>, so the <Literal>small</Literal> project will have its own
-directory <Constant>FPOOLS_TOP/small/</Constant>. Inside the <filename>small/</filename> directory there
-will be a <filename>Makefile</filename>, looking something like this:
-</para>
-
-<para>
-<IndexTerm><Primary>Makefile, minimal</Primary></IndexTerm>
-
-<ProgramListing>
-# Makefile for fptools project "small"
-
-TOP = ..
-include $(TOP)/mk/boilerplate.mk
-
-SRCS = $(wildcard *.lhs) $(wildcard *.c)
-HS_PROG = small
-
-include $(TOP)/target.mk
-</ProgramListing>
-
-</para>
-
-<para>
-This <filename>Makefile</filename> has three sections:
-</para>
-
-<para>
-
-<OrderedList>
-<ListItem>
-
-<para>
- The first section includes
-<FOOTNOTE>
-
-<para>
-One of the most important
-features of GNU <Command>make</Command> that we use is the ability for a <filename>Makefile</filename> to
-include another named file, very like <Command>cpp</Command>'s <Literal>#include</Literal>
-directive.
-</para>
-
-</FOOTNOTE>
- 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>). 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">.
-<IndexTerm><Primary>include, directive in Makefiles</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile inclusion</Primary></IndexTerm>
-
-Before the <Literal>include</Literal> statement, you must define the <Command>make</Command> variable
-<Constant>TOP</Constant><IndexTerm><Primary>TOP</Primary></IndexTerm> to be the directory containing the <filename>mk</filename> directory in
-which the <filename>boilerplate.mk</filename> file is. It is <Emphasis>not</Emphasis> OK to simply say
-
-
-<ProgramListing>
-include ../mk/boilerplate.mk # NO NO NO
-</ProgramListing>
-
-
-Why? Because the <filename>boilerplate.mk</filename> file needs to know where it is, so
-that it can, in turn, <Literal>include</Literal> other files. (Unfortunately, when an
-<Literal>include</Literal>d file does an <Literal>include</Literal>, the filename is treated relative to
-the directory in which <Command>gmake</Command> is being run, not the directory in
-which the <Literal>include</Literal>d sits.) In general, <Emphasis>every file <filename>foo.mk</filename>
-assumes that <filename><Constant>$(TOP)</Constant>/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.
-
-Files intended for inclusion in other <filename>Makefile</filename>s are written to have
-the following property: <Emphasis>after <filename>foo.mk</filename> is <Literal>include</Literal>d, it leaves
-<Constant>TOP</Constant> containing the same value as it had just before the <Literal>include</Literal>
-statement</Emphasis>. In our example, this invariant guarantees that the
-<Literal>include</Literal> for <filename>target.mk</filename> will look in the same directory as that for
-<filename>boilerplate.mk</filename>.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- The second section defines the following standard <Command>make</Command>
-variables: <Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm> (the source files from which is to be
-built), and <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">.
-
-The definition for <Constant>SRCS</Constant> uses the useful GNU <Command>make</Command> construct
-<Literal>$(wildcard $pat$)</Literal><IndexTerm><Primary>wildcard</Primary></IndexTerm>, which expands to a list of all
-the files matching the pattern <Literal>pat</Literal> in the current directory. In
-this example, <Constant>SRCS</Constant> is set to the list of all the <filename>.lhs</filename> and <filename>.c</filename>
-files in the directory. (Let's suppose there is one of each,
-<filename>Foo.lhs</filename> and <filename>Baz.c</filename>.)
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- The last section includes a second file of standard code,
-called <filename>target.mk</filename><IndexTerm><Primary>target.mk</Primary></IndexTerm>. It contains the rules that tell
-<Command>gmake</Command> how 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">.
-
-You do not <Emphasis>have</Emphasis> to <Literal>include</Literal> the <filename>target.mk</filename> file. Instead, you
-can write rules of your own for all the standard targets. Usually,
-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>
-</ListItem>
-
-</OrderedList>
-
-</para>
-
-<para>
-In our example <filename>Makefile</filename>, most of the work is done by the two
-<Literal>include</Literal>d files. When you say <Command>gmake all</Command>, the following things
-happen:
-</para>
-
-<para>
-
-<ItemizedList>
-<ListItem>
-
-<para>
- <Command>gmake</Command> figures out that the object files are <filename>Foo.o</filename> and
-<filename>Baz.o</filename>.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- It uses a boilerplate pattern rule to compile <filename>Foo.lhs</filename> to
-<filename>Foo.o</filename> using a Haskell compiler. (Which one? That is set in the
-build configuration.)
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- It uses another standard pattern rule to compile <filename>Baz.c</filename> to
-<filename>Baz.o</filename>, using a C compiler. (Ditto.)
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- It links the resulting <filename>.o</filename> files together to make <Literal>small</Literal>,
-using the Haskell compiler to do the link step. (Why not use <Command>ld</Command>?
-Because the Haskell compiler knows what standard libraries to link in.
-How did <Command>gmake</Command> know to use the Haskell compiler to do the link,
-rather than the C compiler? Because we set the variable <Constant>HS_PROG</Constant>
-rather than <Constant>C_PROG</Constant>.)
-
-</para>
-</ListItem>
-
-</ItemizedList>
-
-</para>
-
-<para>
-All <filename>Makefile</filename>s should follow the above three-section format.
-</para>
-
-</Sect2>
-
-<Sect2>
-<Title>A larger project</Title>
-
-<para>
-Larger projects are usually structured into a number of sub-directories,
-each of which has its own <filename>Makefile</filename>. (In very large projects, this
-sub-structure might be iterated recursively, though that is rare.)
-To give you the idea, here's part of the directory structure for
-the (rather large) GHC project:
-</para>
-
-<para>
-
-<Screen>
-$(FPTOOLS_TOP)/ghc/
- Makefile
- mk/
- boilerplate.mk
- rules.mk
- docs/
- Makefile
- ...source files for documentation...
- driver/
- Makefile
- ...source files for driver...
- compiler/
- Makefile
- parser/...source files for parser...
- renamer/...source files for renamer...
- ...etc...
-</Screen>
-
-</para>
-
-<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>. It does most
-of its work by recursively invoking <Command>gmake</Command> on the <filename>Makefile</filename>s in the
-sub-directories. We say that <filename>ghc/Makefile</filename> is a <Emphasis>non-leaf
-<filename>Makefile</filename></Emphasis>, because it does little except organise its children,
-while the <filename>Makefile</filename>s in the sub-directories are all <Emphasis>leaf
-<filename>Makefile</filename>s</Emphasis>. (In principle the sub-directories might themselves
-contain a non-leaf <filename>Makefile</filename> and several sub-sub-directories, but
-that does not happen in GHC.)
-</para>
-
-<para>
-The <filename>Makefile</filename> in <filename>ghc/compiler</filename> is considered a leaf <filename>Makefile</filename> even
-though the <filename>ghc/compiler</filename> has sub-directories, because these sub-directories
-do not themselves have <filename>Makefile</filename>s in them. They are just used to structure
-the collection of modules that make up GHC, but all are managed by the
-single <filename>Makefile</filename> in <filename>ghc/compiler</filename>.
-</para>
-
-<para>
-You will notice that <filename>ghc/</filename> also contains a directory <filename>ghc/mk/</filename>. It
-contains GHC-specific <filename>Makefile</filename> boilerplate code. More precisely:
-</para>
-
-<para>
-
-<ItemizedList>
-<ListItem>
-
-<para>
- <filename>ghc/mk/boilerplate.mk</filename> is included at the top of
-<filename>ghc/Makefile</filename>, and of all the leaf <filename>Makefile</filename>s in the
-sub-directories. It in turn <Literal>include</Literal>s the main boilerplate file
-<filename>mk/boilerplate.mk</filename>.
-
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- <filename>ghc/mk/target.mk</filename> is <Literal>include</Literal>d at the bottom of
-<filename>ghc/Makefile</filename>, and of all the leaf <filename>Makefile</filename>s in the
-sub-directories. It in turn <Literal>include</Literal>s the file <filename>mk/target.mk</filename>.
-
-</para>
-</ListItem>
-
-</ItemizedList>
-
-</para>
-
-<para>
-So these two files are the place to look for GHC-wide customisation
-of the standard boilerplate.
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-boiler-arch">
-<Title>Boilerplate architecture
-<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm>
-</Title>
-
-<para>
-Every <filename>Makefile</filename> includes a <filename>boilerplate.mk</filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> file
-at the top, and <filename>target.mk</filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> file at the bottom. In
-this section we discuss what is in these files, and why there have to
-be two of them. In general:
-</para>
-
-<para>
-
-<ItemizedList>
-<ListItem>
-
-<para>
- <filename>boilerplate.mk</filename> consists of:
-
-<ItemizedList>
-<ListItem>
-
-<para>
- <Emphasis>Definitions of millions of <Command>make</Command> variables</Emphasis> that
-collectively specify the build configuration. Examples:
-<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the options to feed to the Haskell compiler;
-<Constant>NoFibSubDirs</Constant><IndexTerm><Primary>NoFibSubDirs</Primary></IndexTerm>, the sub-directories to enable within the
-<Literal>nofib</Literal> project; <Constant>GhcWithHc</Constant><IndexTerm><Primary>GhcWithHc</Primary></IndexTerm>, the name of the Haskell
-compiler to use when compiling GHC in the <Literal>ghc</Literal> project.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
-<Emphasis>Standard pattern rules</Emphasis> that tell <Command>gmake</Command> how to construct one
-file from another.
-</para>
-</ListItem>
-
-</ItemizedList>
-
-
-<filename>boilerplate.mk</filename> needs to be <Literal>include</Literal>d at the <Emphasis>top</Emphasis>
-of each <filename>Makefile</filename>, so that the user can replace the
-boilerplate definitions or pattern rules by simply giving a new
-definition or pattern rule in the <filename>Makefile</filename>. <Command>gmake</Command>
-simply takes the last definition as the definitive one.
-
-Instead of <Emphasis>replacing</Emphasis> boilerplate definitions, it is also quite
-common to <Emphasis>augment</Emphasis> them. For example, a <filename>Makefile</filename> might say:
-
-
-<ProgramListing>
-SRC_HC_OPTS += -O
-</ProgramListing>
-
-
-thereby adding ``<Option>-O</Option>'' to the end of <Constant>SRC_HC_OPTS</Constant><IndexTerm><Primary>SRC_HC_OPTS</Primary></IndexTerm>.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- <filename>target.mk</filename> contains <Command>make</Command> rules for the standard
-targets 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
-<filename>Makefile</filename> between the two <Literal>include</Literal>s.
-
-<filename>target.mk</filename> must be included at the end (rather than being part of
-<filename>boilerplate.mk</filename>) for several tiresome reasons:
-
-
-<ItemizedList>
-<ListItem>
-
-<para>
- <Command>gmake</Command> commits target and dependency lists earlier than
-it should. For example, <FIlename>target.mk</FIlename> has a rule that looks like
-this:
-
-
-<ProgramListing>
-$(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@
-</ProgramListing>
-
-
-If this rule was in <filename>boilerplate.mk</filename> then <Constant>$(HS_PROG)</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>
-and <Constant>$(OBJS)</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm> would not have their final values at the
-moment <Command>gmake</Command> encountered the rule. Alas, <Command>gmake</Command> takes a snapshot
-of their current values, and wires that snapshot into the rule. (In
-contrast, the commands executed when the rule ``fires'' are only
-substituted at the moment of firing.) So, the rule must follow the
-definitions given in the <filename>Makefile</filename> itself.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Unlike pattern rules, ordinary rules cannot be overriden or
-replaced by subsequent rules for the same target (at least, not without an
-error message). Including ordinary rules in <filename>boilerplate.mk</filename> would
-prevent the user from writing rules for specific targets in specific cases.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- There are a couple of other reasons I've forgotten, but it doesn't
-matter too much.
-</para>
-</ListItem>
-
-</ItemizedList>
-
-</para>
-</ListItem>
-
-</ItemizedList>
-
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-boiler">
-<Title>The main <filename>mk/boilerplate.mk</filename> file
-
-<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title>
-
-<para>
-If you look at <filename><Constant>$(FPTOOLS_TOP)</Constant>/mk/boilerplate.mk</filename> you will find
-that it consists of the following sections, each held in a separate
-file:
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<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>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><filename>paths.mk</filename><IndexTerm><Primary>paths.mk</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-defines <Command>make</Command> variables for
-pathnames and file lists. In particular, it gives definitions for:
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-all source files in the current directory.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-all Haskell source files in the current directory.
-It is derived from <Constant>$(SRCS)</Constant>, so if you override <Constant>SRCS</Constant> with a new value
-<Constant>HS_SRCS</Constant> will follow suit.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-similarly for C source files.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_OBJS</Constant><IndexTerm><Primary>HS_OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-the <filename>.o</filename> files derived from <Constant>$(HS_SRCS)</Constant>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_OBJS</Constant><IndexTerm><Primary>C_OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-similarly for <Constant>$(C_SRCS)</Constant>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>OBJS</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-the concatenation of <Constant>$(HS_OBJS)</Constant> and <Constant>$(C_OBJS)</Constant>.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-Any or all of these definitions can easily be overriden by giving new
-definitions in your <filename>Makefile</filename>. For example, if there are things in
-the current directory that look like source files but aren't, then
-you'll need to set <Constant>SRCS</Constant> manually in your <filename>Makefile</filename>. The other
-definitions will then work from this new definition.
-</para>
-
-<para>
-What, exactly, does <filename>paths.mk</filename> consider a ``source file'' to be? It's
-based on the file's suffix (e.g. <filename>.hs</filename>, <filename>.lhs</filename>, <filename>.c</filename>, <filename>.lc</filename>, etc), but
-this is the kind of detail that changes, so rather than
-enumerate the source suffices here the best thing to do is to look in
-<filename>paths.mk</filename>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<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>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><filename>suffix.mk</filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-defines standard pattern rules—see <Xref LinkEnd="sec-suffix">.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-Any of the variables and pattern rules defined by the boilerplate file
-can easily be overridden in any particular <filename>Makefile</filename>, because the
-boilerplate <Literal>include</Literal> comes first. Definitions after this <Literal>include</Literal>
-directive simply override the default ones in <filename>boilerplate.mk</filename>.
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-suffix">
-<Title>Pattern rules and options
-
-<IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title>
-
-<para>
-The file <filename>suffix.mk</filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm> defines standard <Emphasis>pattern
-rules</Emphasis> that say how to build one kind of file from another, for
-example, how to build a <filename>.o</filename> file from a <filename>.c</filename> file. (GNU <Command>make</Command>'s
-<Emphasis>pattern rules</Emphasis> are more powerful and easier to use than Unix
-<Command>make</Command>'s <Emphasis>suffix rules</Emphasis>.)
-</para>
-
-<para>
-Almost all the rules look something like this:
-</para>
-
-<para>
-
-<ProgramListing>
-%.o : %.c
- $(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@
-</ProgramListing>
-
-</para>
-
-<para>
-Here's how to understand the rule. It says that
-<Emphasis>something</Emphasis><filename>.o</filename> (say <filename>Foo.o</filename>) can be built from
-<Emphasis>something</Emphasis><filename>.c</filename> (<filename>Foo.c</filename>), by invoking the C compiler
-(path name held in <Constant>$(CC)</Constant>), passing to it the options
-<Constant>$(CC_OPTS)</Constant> and the rule's dependent file of the rule
-<Literal>$<</Literal> (<filename>Foo.c</filename> in this case), and putting the result in
-the rule's target <Literal>$@</Literal> (<filename>Foo.o</filename> in this case).
-</para>
-
-<para>
-Every program is held in a <Command>make</Command> variable defined in
-<filename>mk/config.mk</filename>—look in <filename>mk/config.mk</filename> for the
-complete list. One important one is the Haskell compiler, which is
-called <Constant>$(HC)</Constant>.
-</para>
-
-<para>
-Every program's options are are held in a <Command>make</Command> variables called
-<Constant><prog>_OPTS</Constant>. the <Constant><prog>_OPTS</Constant> variables are defined in
-<filename>mk/opts.mk</filename>. Almost all of them are defined like this:
-</para>
-
-<para>
-
-<ProgramListing>
-CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
-</ProgramListing>
-
-</para>
-
-<para>
-The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning:
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>SRC_CC_OPTS</Constant><IndexTerm><Primary>SRC_CC_OPTS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-options passed to all C
-compilations.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>WAY_<way>_CC_OPTS</Constant>:</Term>
-<ListItem>
-<para>
-options passed to C
-compilations for way <Literal><way></Literal>. For example,
-<Constant>WAY_mp_CC_OPTS</Constant> gives options to pass to the C compiler when
-compiling way <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 multi-way
-compilation.)
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant><module>_CC_OPTS</Constant>:</Term>
-<ListItem>
-<para>
-options to
-pass to the C compiler that are specific to module <Literal><module></Literal>. For example, <Constant>SMap_CC_OPTS</Constant> gives the specific options
-to pass to the C compiler when compiling <filename>SMap.c</filename>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>EXTRA_CC_OPTS</Constant><IndexTerm><Primary>EXTRA_CC_OPTS</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-extra options to pass to all
-C compilations. This is intended for command line use, thus:
-</para>
-
-<para>
-
-<ProgramListing>
-gmake libHS.a EXTRA_CC_OPTS="-v"
-</ProgramListing>
-
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-targets">
-<Title>The main <filename>mk/target.mk</filename> file
-
-<IndexTerm><Primary>target.mk</Primary></IndexTerm></Title>
-
-<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 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 file, <filename>target.mk</filename>, which selectively includes rules based on
-whether you have defined certain variables in your <filename>Makefile</filename>. This
-section explains what rules you get, what variables control them, and
-what the rules do. Hopefully, you will also get enough of an idea of
-what is supposed to happen that you can read and understand any weird
-special cases yourself.
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>.</Term>
-<ListItem>
-<para>
-If <Constant>HS_PROG</Constant> is defined, you get
-rules with the following targets:
-<VariableList>
-
-<VarListEntry>
-<Term><filename>HS_PROG</filename><IndexTerm><Primary>HS_PROG</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-itself. This rule links <Constant>$(OBJS)</Constant>
-with the Haskell runtime system to get an executable called
-<Constant>$(HS_PROG)</Constant>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>install</Literal><IndexTerm><Primary>install</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-installs <Constant>$(HS_PROG)</Constant>
-in <Constant>$(bindir)</Constant>.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_PROG</Constant><IndexTerm><Primary>C_PROG</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-is similar to <Constant>HS_PROG</Constant>, except that
-the link step links <Constant>$(C_OBJS)</Constant> with the C runtime system.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIBRARY</Constant><IndexTerm><Primary>LIBRARY</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-is similar to <Constant>HS_PROG</Constant>, except that
-it links <Constant>$(LIB_OBJS)</Constant> to make the library archive <Constant>$(LIBRARY)</Constant>, and
-<Literal>install</Literal> installs it in <Constant>$(libdir)</Constant>.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIB_DATA</Constant><IndexTerm><Primary>LIB_DATA</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-…
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIB_EXEC</Constant><IndexTerm><Primary>LIB_EXEC</Primary></IndexTerm></Term>
-<ListItem>
-<para>
-…
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>, <Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>.</Term>
-<ListItem>
-<para>
-If <Constant>HS_SRCS</Constant>
-is defined and non-empty, a rule for the target <Literal>depend</Literal> is included,
-which generates dependency information for Haskell programs.
-Similarly for <Constant>C_SRCS</Constant>.
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-All of these rules are ``double-colon'' rules, thus
-</para>
-
-<para>
-
-<ProgramListing>
-install :: $(HS_PROG)
- ...how to install it...
-</ProgramListing>
-
-</para>
-
-<para>
-GNU <Command>make</Command> treats double-colon rules as separate entities. If there
-are several double-colon rules for the same target it takes each in
-turn and fires it if its dependencies say to do so. This means that
-you can, for example, define both <Constant>HS_PROG</Constant> and <Constant>LIBRARY</Constant>, which will
-generate two rules for <Literal>install</Literal>. When you type <Command>gmake install</Command> both
-rules will be fired, and both the program and the library will be
-installed, just as you wanted.
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-subdirs">
-<Title>Recursion
-
-<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm></Title>
-
-<para>
-In leaf <filename>Makefile</filename>s the variable <Constant>SUBDIRS</Constant><IndexTerm><Primary>SUBDIRS</Primary></IndexTerm> is undefined.
-In non-leaf <filename>Makefile</filename>s, <Constant>SUBDIRS</Constant> is set to the list of
-sub-directories that contain subordinate <filename>Makefile</filename>s. <Emphasis>It is up to
-you to set <Constant>SUBDIRS</Constant> in the <filename>Makefile</filename>.</Emphasis> There is no automation here—<Constant>SUBDIRS</Constant> is too important to automate.
-</para>
-
-<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 simply invokes
-<Command>make</Command> recursively in each of the sub-directories.
-</para>
-
-<para>
-<Emphasis>These recursive invocations are guaranteed to occur in the order
-in which the list of directories is specified in <Constant>SUBDIRS</Constant>. </Emphasis>This
-guarantee can be important. For example, when you say <Command>gmake boot</Command> it
-can be important that the recursive invocation of <Command>make boot</Command> is done
-in one sub-directory (the include files, say) before another (the
-source files). Generally, put the most independent sub-directory
-first, and the most dependent last.
-</para>
-
-</Sect2>
-
-<Sect2 id="sec-ways">
-<Title>Way management
-
-<IndexTerm><Primary>way management</Primary></IndexTerm></Title>
-
-<para>
-We sometimes want to build essentially the same system in several
-different ``ways''. For example, we want to build GHC's <Literal>Prelude</Literal>
-libraries with and without profiling, with and without concurrency,
-and so on, so that there is an appropriately-built library archive to
-link with when the user compiles his program. It would be possible to
-have a completely separate build tree for each such ``way'', but it
-would be horribly bureaucratic, especially since often only parts of
-the build tree need to be constructed in multiple ways.
-</para>
-
-<para>
-Instead, the <filename>target.mk</filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> contains some clever magic to
-allow you to build several versions of a system; and to control
-locally how many versions are built and how they differ. This section
-explains the magic.
-</para>
-
-<para>
-The files for a particular way are distinguished by munging the
-suffix. The ``normal way'' is always built, and its files have the
-standard suffices <filename>.o</filename>, <filename>.hi</filename>, and so on. In addition, you can build
-one or more extra ways, each distinguished by a <Emphasis>way tag</Emphasis>. The
-object files and interface files for one of these extra ways are
-distinguished by their suffix. For example, way <Literal>mp</Literal> has files
-<filename>.mp_o</filename> and <filename>.mp_hi</filename>. Library archives have their way tag the other
-side of the dot, for boring reasons; thus, <filename>libHS_mp.a</filename>.
-</para>
-
-<para>
-A <Command>make</Command> variable called <Constant>way</Constant> holds the current way tag. <Emphasis><Constant>way</Constant>
-is only ever set on the command line of a recursive invocation of
-<Command>gmake</Command>.</Emphasis> It is never set inside a <filename>Makefile</filename>. So it is a global
-constant for any one invocation of <Command>gmake</Command>. Two other <Command>make</Command>
-variables, <Constant>way_</Constant> and <Constant>_way</Constant> are immediately derived from <Constant>$(way)</Constant> and
-never altered. If <Constant>way</Constant> is not set, then neither are <Constant>way_</Constant> and
-<Constant>_way</Constant>, and the invocation of <Command>make</Command> will build the ``normal way''.
-If <Constant>way</Constant> is set, then the other two variables are set in sympathy.
-For example, if <Constant>$(way)</Constant> is ``<Literal>mp</Literal>'', then <Constant>way_</Constant> is set to ``<Literal>mp_</Literal>''
-and <Constant>_way</Constant> is set to ``<Literal>_mp</Literal>''. These three variables are then used
-when constructing file names.
-</para>
-
-<para>
-So how does <Command>make</Command> ever get recursively invoked with <Constant>way</Constant> set? There
-are two ways in which this happens:
-</para>
-
-<para>
-
-<ItemizedList>
-<ListItem>
-
-<para>
- For some (but not all) of the standard targets, when in a leaf
-sub-directory, <Command>make</Command> is recursively invoked for each way tag in
-<Constant>$(WAYS)</Constant>. You set <Constant>WAYS</Constant> 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 <Constant>WAYS</Constant> in your <filename>Makefile</filename>; this is how you
-control what ways will get built.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- For a useful collection of
-targets (such as <filename>libHS_mp.a</filename>, <filename>Foo.mp_o</filename>) there is a rule which
-recursively invokes <Command>make</Command> to make the specified target, setting the
-<Constant>way</Constant> variable. So if you say <Command>gmake Foo.mp_o</Command> you should see a
-recursive invocation <Command>gmake Foo.mp_o way=mp</Command>, and <Emphasis>in this
-recursive invocation the pattern rule for compiling a Haskell file
-into a <filename>.o</filename> file will match</Emphasis>. The key pattern rules (in <filename>suffix.mk</filename>)
-look like this: