<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>January 2000</PubDate>
-
-<Abstract>
-
-<para>
-This guide is intended for people who want to build or modify
-programs from the Glasgow <Literal>fptools</Literal> suite (as distinct from those
-who merely want to <Emphasis>run</Emphasis> them). Installation instructions are now provided in the user guide.
-</para>
-
-<para>
-The bulk of this guide applies to building on Unix systems; see <XRef LinkEnd="winbuild"> for Windows notes.
-</para>
-
-</Abstract>
-
-</ArtHeader>
-
-
-<Sect1 id="sec-getting">
-<Title>Getting the Glasgow <Literal>fptools</Literal> suite
-</Title>
-
-<para>
-Building the Glasgow tools <Emphasis>can</Emphasis> be complicated, mostly because
-there are so many permutations of what/why/how, e.g., ``Build Happy
-with HBC, everything else with GHC, leave out profiling, and test it
-all on the `real' NoFib programs.'' Yeeps!
-</para>
-
-<para>
-Happily, such complications don't apply to most people. A few common
-``strategies'' serve most purposes. Pick one and proceed
-as suggested:
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term><IndexTerm><Primary>Binary distribution</Primary></IndexTerm>Binary distribution.</Term>
-<ListItem>
-<para>
-If your only purpose is to install some of the <Literal>fptools</Literal> suite then the easiest thing to do is to get a binary distribution. In the
-binary distribution everything is pre-compiled for your particular
-machine architecture and operating system, so all you should have to
-do is install the binaries and libraries in suitable places. The user guide
-describes how to do this.
-</para>
-
-<para>
-A binary distribution may not work for you for two reasons. First, we
-may not have built the suite for the particular architecture/OS
-platform you want. That may be due to lack of time and energy (in
-which case you can get a source distribution and build from it; see
-below). Alternatively, it may be because we haven't yet ported the
-suite to your architecture, in which case you are considerably worse
-off.
-</para>
-
-<para>
-The second reason a binary distribution may not be what you want is
-if you want to read or modify the souce code.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>Source distribution.</Term>
-<ListItem>
-<para>
-You have a supported
-platform, but (a) you like the warm fuzzy feeling of compiling things
-yourself; (b) you want to build something ``extra''—e.g., a set of
-libraries with strictness-analysis turned off; or (c) you want to hack
-on GHC yourself.
-</para>
-
-<para>
-A source distribution contains complete sources for one or more
-projects in the <Literal>fptools</Literal> suite. Not only that, but
-the more awkward machine-independent steps are done for you. For
-example, if you don't have
-<Command>happy</Command><IndexTerm><Primary>happy</Primary></IndexTerm>
-you'll find it convenient that the source distribution contains the
-result of running <Command>happy</Command> on the parser
-specifications. If you don't want to alter the parser then this saves
-you having to find and install <Command>happy</Command>. You will
-still need a working version of GHC (preferably version 4.08+) on your
-machine in order to compile (most of) the sources, however.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>Build GHC from intermediate C <Filename>.hc</Filename> files<IndexTerm><Primary>hc files</Primary></IndexTerm>:</Term>
-<ListItem>
-<para>
-You
-need a working GHC to use a source distribution. What if you don't
-have a working GHC? Then you have no choice but to ``bootstrap'' up
-from the intermediate C (<Filename>.hc</Filename>) files that we provide. Building GHC
-on an unsupported platform falls into this category. Please see
-<Xref LinkEnd="sec-booting-from-C">.
-</para>
-
-<para>
-Once you have built GHC, you can build the other Glasgow tools with
-it.
-</para>
-
-<para>
-In theory, you can (could?) build GHC with another Haskell compiler
-(e.g., HBC). We haven't tried to do this for ages and it almost
-certainly doesn't work any more (for tedious reasons).
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>The CVS repository.</Term>
-<ListItem>
-<para>
-We make releases infrequently. If you want more up-to-the minute (but
-less tested) source code then you need to get access to our CVS
-repository.
-</para>
-
-<para>All the <Literal>fptools</Literal> source code is held in a CVS
-repository. CVS is a pretty good source-code control system, and best
-of all it works over the network.</para>
-
-<para>The repository holds source code only. It holds no mechanically
-generated files at all. So if you check out a source tree from CVS
-you will need to install every utility so that you can build all the
-derived files from scratch.</para>
-
-<para>More information about our CVS repository is available in the
-<ULink URL="http://www.haskell.org/ghc/cvs-cheat-sheet.html">fptools
-CVS Cheat Sheet</ULink>.</para>
-
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>If you are going to do any building from sources (either from a
-source distribution or the CVS repository) then you need to read all
-of this manual in detail.</para>
-
-</Sect1>
-
-<Sect1 id="sec-build-checks">
-<Title>Things to check before you start typing</Title>
-
-<para>
-Here's a list of things to check before you get started.
-
-<OrderedList>
-<ListItem>
-
-<para>
-<IndexTerm><Primary>Disk space needed</Primary></IndexTerm>
-Disk space needed: About 40MB (one tenth of one hamburger's worth) of disk
-space for the most basic binary distribution of GHC; more for some
-platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent Haskell
-libraries) might take you to up to one fifth of a hamburger. You'll need
-over 100MB (say, one fifth a hamburger's worth) if you need to build the
-basic stuff from scratch. All of the above are
-<Emphasis>estimates</Emphasis> of disk-space needs. (Note: our benchmark hamburger is a standard Double Whopper with Cheese, with an RRP of UKP2.99.)
-</para>
-</ListItem>
-<ListItem>
-
-<para>
-Use an appropriate machine, compilers, and things. SPARC boxes, and
-PCs running Linux, BSD (any variant), or Solaris are all fully
-supported. Win32 and HP boxes are in pretty good shape. DEC Alphas
-running OSF/1, Linux or some BSD variant, MIPS and AIX boxes will need
-some minimal porting effort before they work (as of 4.06). <Xref
-LinkEnd="sec-port-info"> gives the full run-down on ports or lack
-thereof.
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- Be sure that the ``pre-supposed'' utilities are installed.
-<Xref LinkEnd="sec-pre-supposed"> elaborates.
-
-</para>
-</ListItem>
-<ListItem>
-
-<para>
- If you have any problem when building or installing the Glasgow
-tools, please check the ``known pitfalls'' (<Xref
-LinkEnd="sec-build-pitfalls">). Also check the FAQ for the version
-you're building, which should be available from the relevant download
-page on the <ULink URL="http://www.haskell.org/ghc/" >GHC web
-site</ULink>.
-
-<IndexTerm><Primary>known bugs</Primary></IndexTerm>
-<IndexTerm><Primary>bugs, known</Primary></IndexTerm>
-
-If you feel there is still some shortcoming in our procedure or
-instructions, please report it.
-
-For GHC, please see the bug-reporting section of the GHC Users' Guide
-(separate document), to maximise the usefulness of your report.
-<IndexTerm><Primary>bugs, reporting</Primary></IndexTerm>
-
-If in doubt, please send a message to
-<Email>glasgow-haskell-bugs@haskell.org</Email>.
-<IndexTerm><Primary>bugs, mailing list</Primary></IndexTerm>
-</para>
-</ListItem>
-
-</OrderedList>
-
-</para>
-
-</Sect1>
-
-<Sect1 id="sec-port-info">
-<Title>What machines the Glasgow tools run on
-</Title>
-
-<para>
-<IndexTerm><Primary>ports, GHC</Primary></IndexTerm>
-<IndexTerm><Primary>GHC ports</Primary></IndexTerm>
-<IndexTerm><Primary>supported platforms</Primary></IndexTerm>
-<IndexTerm><Primary>platforms, supported</Primary></IndexTerm>
-The main question is whether or not the Haskell compiler (GHC) runs on
-your platform.
-</para>
-
-<para>
-A ``platform'' is a architecture/manufacturer/operating-system
-combination, such as <Literal>sparc-sun-solaris2</Literal>. Other common ones are
-<Literal>alpha-dec-osf2</Literal>, <Literal>hppa1.1-hp-hpux9</Literal>, <Literal>i386-unknown-linux</Literal>,
-<Literal>i386-unknown-solaris2</Literal>, <Literal>i386-unknown-freebsd</Literal>,
-<Literal>i386-unknown-cygwin32</Literal>, <Literal>m68k-sun-sunos4</Literal>, <Literal>mips-sgi-irix5</Literal>,
-<Literal>sparc-sun-sunos4</Literal>, <Literal>sparc-sun-solaris2</Literal>, <Literal>powerpc-ibm-aix</Literal>.
-</para>
-
-<para>
-Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not
-work on all machines for which basic Haskell compiling is supported.
-</para>
-
-<para>
-Some libraries may only work on a limited number of platforms; for
-example, a sockets library is of no use unless the operating system
-supports the underlying BSDisms.
-</para>
-
-<Sect2>
-<Title>What platforms the Haskell compiler (GHC) runs on</Title>
-
-<para>
-<IndexTerm><Primary>fully-supported platforms</Primary></IndexTerm>
-<IndexTerm><Primary>native-code generator</Primary></IndexTerm>
-<IndexTerm><Primary>registerised ports</Primary></IndexTerm>
-<IndexTerm><Primary>unregisterised ports</Primary></IndexTerm>
-The GHC hierarchy of Porting Goodness: (a) Best is a native-code
-generator; (b) next best is a ``registerised''
-port; (c) the bare minimum is an ``unregisterised'' port.
-(``Unregisterised'' is so terrible that we won't say more about it).
-</para>
-
-<para>
-We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and
-Linux, so those are the best supported platforms, unsurprisingly.
-</para>
-
-<para>
-Here's everything that's known about GHC ports. We identify platforms
-by their ``canonical'' CPU/Manufacturer/OS triple.
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</Term>
-<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>
-<ListItem>
-
-<para>
-Currently non-working. The last working version (osf[1-3]) is GHC
-3.02. A small amount of porting effort will be required to get Alpha
-support into GHC 4.xx, but we don't have easy access to machines right
-now, and there hasn't been a massive demand for support, so Alphas
-remain unsupported for the time being. Please get in touch if you
-either need Alpha support and/or can provide access to boxes.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>sparc-sun-sunos4:</Term>
-<IndexTerm><Primary>sparc-sun-sunos4</Primary></IndexTerm>
-<ListItem>
-
-<para>
-Probably works with minor tweaks, hasn't been tested for a while.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>sparc-sun-solaris2:</Term>
-<IndexTerm><Primary>sparc-sun-solaris2</Primary></IndexTerm>
-<ListItem>
-
-<para>
-Fully supported, including native-code generator.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term>
-<IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm>
-<ListItem>
-
-<para>
-Works registerised. No native-code generator.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>i386-unknown-linux (PCs running Linux—ELF binary format):</Term>
-<IndexTerm><Primary>i386-*-linux</Primary></IndexTerm>
-<ListItem>
-
-<para>GHC works registerised, has a native code generator. You
-<Emphasis>must</Emphasis> have GCC 2.7.x or later. NOTE about
-<literal>glibc</literal> versions: GHC binaries built on a system
-running <literal>glibc 2.0</literal> won't work on a system running
-<literal>glibc 2.1</literal>, and vice versa. In general, don't
-expect compatibility between <literal>glibc</literal> versions, even
-if the shared library version hasn't changed.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>i386-unknown-{freebsd,netbsd,openbsd) (PCs running FreeBSD 2.2
-or higher, NetBSD, and possibly OpenBSD):</Term>
-<IndexTerm><Primary>i386-unknown-freebsd</Primary></IndexTerm>
-<IndexTerm><Primary>i386-unknown-netbsd</Primary></IndexTerm>
-<IndexTerm><Primary>i386-unknown-openbsd</Primary></IndexTerm>
-<ListItem>
-
-<para>
-GHC works registerised. These systems provide ready-built packages of
-GHC, so if you just need binaries you're better off just installing
-the package.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>i386-unknown-cygwin32:</Term>
-<IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm>
-<ListItem>
-
-<para>
-Fully supported under Win9x/NT, including a native code
-generator. Requires the <Literal>cygwin32</Literal> compatibility
-library and a healthy collection of GNU tools (i.e., gcc, GNU ld, bash
-etc.).
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>mips-sgi-irix5:</Term>
-<IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm>
-<ListItem>
-
-<para>
-Port currently doesn't work, needs some minimal porting effort. As
-usual, we don't have access to machines and there hasn't been an
-overwhelming demand for this port, but feel free to get in touch.
-</para>
-</ListItem></VarListEntry>
-
-<VarListEntry>
-<Term>powerpc-ibm-aix:</Term>
-<ListItem>
-<para>
-<IndexTerm><Primary>powerpc-ibm-aix</Primary></IndexTerm>
-Port currently doesn't work, needs some minimal porting effort. As
-usual, we don't have access to machines and there hasn't been an
-overwhelming demand for this port, but feel free to get in touch.
-</para>
-</ListItem></VarListEntry>
-
-</VariableList>
-</para>
-
-<para>
-Various other systems have had GHC ported to them in the distant past,
-including various Motorola 68k boxes. The 68k support still remains,
-but porting to one of these systems will certainly be a non-trivial
-task.
-</para>
-
-</Sect2>
-
-<Sect2>
-<Title>What machines the other tools run on</Title>
-
-<para>
-Unless you hear otherwise, the other tools work if GHC works.
-</para>
-
-</Sect2>
-
-</Sect1>
-
-
-<Sect1 id="sec-pre-supposed">
-<Title>Installing pre-supposed utilities
-
-<IndexTerm><Primary>pre-supposed utilities</Primary></IndexTerm>
-<IndexTerm><Primary>utilities, pre-supposed</Primary></IndexTerm></Title>
-
-<para>
-Here are the gory details about some utility programs you may need;
-<Command>perl</Command>, <Command>gcc</Command> and
-<command>happy</command> are the only important
-ones. (PVM<IndexTerm><Primary>PVM</Primary></IndexTerm> is important
-if you're going for Parallel Haskell.) The
-<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
-script will tell you if you are missing something.
-</para>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term>Perl:</Term>
-<IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
-<IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
-<ListItem>
-<para>
-<Emphasis>You have to have Perl to proceed!</Emphasis> Perl is a
-language quite good for doing shell-scripty tasks that involve lots of
-text processing. It is pretty easy to install.
-</para>
-
-<para>
-Perl 5 is required. For Win32 platforms, you should use the binary
-supplied in the InstallShield (copy it to <filename>cygwin/bin</filename>).
-The Cygwin-supplied Perl seems not to work (it has problems with line
-endings).
-</para>
-
-<para>
-Perl should be put somewhere so that it can be invoked by the
-<Literal>#!</Literal> script-invoking mechanism. The full
-pathname may need to be less than 32 characters long on some
-systems.
-</para>
-
-</ListItem></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>
-<ListItem>
-
-<para>
-We recommend using GCC version 2.95.2 on all platforms. Failing that,
-version 2.7.2 is stable on most platforms. Earlier versions of GCC
-can be assumed not to work, and versions in between 2.7.2 and 2.95.2
-(including <command>egcs</command>) have varying degrees of stability
-depending on the platform.
-</para>
-
-<para>
-If your GCC dies with ``internal error'' on some GHC source file,
-please let us know, so we can report it and get things improved.
-(Exception: on iX86 boxes—you may need to fiddle with GHC's
-<Option>-monly-N-regs</Option> option; see the User's Guide)
-</para>
-</ListItem></VarListEntry>
-
-<varlistentry>
-<term>Happy:</term>
-<indexterm><primary>Happy</primary></indexterm>
-<listitem>
-<para>Happy is a parser generator tool for Haskell, and is used to
-generate GHC's parsers. Happy is written in Haskell, and is a project
-in the CVS repository (<literal>fptools/happy</literal>). It can be
-built from source, but bear in mind that you'll need GHC installed in
-order to build it. To avoid the chicken/egg problem, install a binary
-distribtion of either Happy or GHC to get started. Happy
-distributions are available from <ulink
-url="http://www.haskell.org/happy/">Happy's Web Page</ulink>.
-</para>
-</listitem>
-</varlistentry>
-
-<VarListEntry>
-<Term>Autoconf:</Term>
-<IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
-<IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
-<ListItem>
-<para>
-GNU Autoconf is needed if you intend to build from the CVS sources, it
-is <Emphasis>not</Emphasis> needed if you just intend to build a
-standard source distribution.
-</para>
-
-<para>
-Autoconf builds the <Command>configure</Command> script from
-<Filename>configure.in</Filename> and <Filename>aclocal.m4</Filename>.
-If you modify either of these files, you'll need
-<command>autoconf</command> to rebuild <Filename>configure</Filename>.
-</para>
-
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Command>sed</Command></Term>
-<IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
-<IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
-<ListItem>
-<para>
-You need a working <Command>sed</Command> if you are going to build
-from sources. The build-configuration stuff needs it. GNU sed
-version 2.0.4 is no good! It has a bug in it that is tickled by the
-build-configuration. 2.0.5 is OK. Others are probably OK too
-(assuming we don't create too elaborate configure scripts.)
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-<para>
-One <Literal>fptools</Literal> project is worth a quick note at this
-point, because it is useful for all the others:
-<Literal>glafp-utils</Literal> contains several utilities which aren't
-particularly Glasgow-ish, but Occasionally Indispensable. Like
-<Command>lndir</Command> for creating symbolic link trees.
-</para>
-
-<Sect2 id="pre-supposed-gph-tools">
-<Title>Tools for building parallel GHC (GPH)
-</Title>
-
-<para>
-<VariableList>
-
-<VarListEntry>
-<Term>PVM version 3:</Term>
-<IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
-<IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
-<ListItem>
-
-<para>
-PVM is the Parallel Virtual Machine on which Parallel Haskell programs
-run. (You only need this if you plan to run Parallel Haskell.
-Concurent Haskell, which runs concurrent threads on a uniprocessor
-doesn't need it.) Underneath PVM, you can have (for example) a
-network of workstations (slow) or a multiprocessor box (faster).
-</para>
-
-<para>
-The current version of PVM is 3.3.11; we use 3.3.7. It is readily
-available on the net; I think I got it from
-<Literal>research.att.com</Literal>, in <Filename>netlib</Filename>.
-</para>
-
-<para>
-A PVM installation is slightly quirky, but easy to do. Just follow
-the <Filename>Readme</Filename> instructions.
-</para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Command>bash</Command>:</Term>
-<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
-<ListItem>
-<para>
-Sadly, the <Command>gr2ps</Command> script, used to convert ``parallelism profiles''
-to PostScript, is written in Bash (GNU's Bourne Again shell).
-This bug will be fixed (someday).
-</para>
-</ListItem></VarListEntry>
-</VariableList>
-</para>
-
-</Sect2>
-
-<Sect2 id="pre-supposed-doc-tools">
-<Title>Tools for building the Documentation
-</Title>
-
-<para>
-The following additional tools are required if you want to format the
-documentation that comes with the <Literal>fptools</Literal> projects:
-</para>
-
-<para>
-<VariableList>
-
-<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-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>
-
+<PubDate>November 2001</PubDate>
+
+ <abstract>
+ <para>The Glasgow fptools suite is a collection of Functional
+ Programming related tools, including the Glasgow Haskell
+ Compiler (GHC). The source code for the whole suite is kept in
+ a single CVS repository and shares a common build and
+ installation system.</para>
+
+ <para>This guide is intended for people who want to build or
+ modify programs from the Glasgow <Literal>fptools</Literal>
+ suite (as distinct from those who merely want to
+ <Emphasis>run</Emphasis> them). Installation instructions are
+ now provided in the user guide.</para>
+
+ <para>The bulk of this guide applies to building on Unix
+ systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
+ </abstract>
+
+ </artheader>
+
+
+ <sect1 id="sec-getting">
+ <title>Getting the sources</title>
+
+ <para>You can get your hands on the <literal>fptools</literal>
+ in two ways:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><indexterm><primary>Source
+ distributions</primary></indexterm>Source distributions</term>
+ <listitem>
+ <para>You have a supported platform, but (a) you like
+ the warm fuzzy feeling of compiling things yourself;
+ (b) you want to build something ``extra”—e.g., a
+ set of libraries with strictness-analysis turned off; or
+ (c) you want to hack on GHC yourself.</para>
+
+ <para>A source distribution contains complete sources for
+ one or more projects in the <literal>fptools</literal>
+ suite. Not only that, but the more awkward
+ machine-independent steps are done for you. For example, if
+ you don't have
+ <command>happy</command><indexterm><primary>happy</primary></indexterm>
+ you'll find it convenient that the source distribution
+ contains the result of running <command>happy</command> on
+ the parser specifications. If you don't want to alter the
+ parser then this saves you having to find and install
+ <command>happy</command>. You will still need a working
+ version of GHC (preferably version 4.08+) on your machine in
+ order to compile (most of) the sources, however.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>The CVS repository.</term>
+ <indexterm><primary>CVS repository</primary>
+ </indexterm>
+ <listitem>
+ <para>We make releases infrequently. If you want more
+ up-to-the minute (but less tested) source code then you need
+ to get access to our CVS repository.</para>
+
+ <para>All the <literal>fptools</literal> source code is held
+ in a CVS repository. CVS is a pretty good source-code
+ control system, and best of all it works over the
+ network.</para>
+
+ <para>The repository holds source code only. It holds no
+ mechanically generated files at all. So if you check out a
+ source tree from CVS you will need to install every utility
+ so that you can build all the derived files from
+ scratch.</para>
+
+ <para>More information about our CVS repository can be found
+ in <xref linkend="sec-cvs">.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>If you are going to do any building from sources (either
+ from a source distribution or the CVS repository) then you need to
+ read all of this manual in detail.</para>
+ </sect1>
+
+ <sect1 id="sec-cvs">
+ <title>Using the CVS repository</title>
+
+ <para>We use <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Version System) to keep track of our
+ sources for various software projects. CVS lets several people
+ work on the same software at the same time, allowing changes to be
+ checked in incrementally. </para>
+
+ <para>This section is a set of guidelines for how to use our CVS
+ repository, and will probably evolve in time. The main thing to
+ remember is that most mistakes can be undone, but if there's
+ anything you're not sure about feel free to bug the local CVS
+ meister (namely Jeff Lewis
+ <email>jlewis@galconn.com</email>). </para>
+
+ <sect2 id="cvs-access">
+ <title>Getting access to the CVS Repository</title>
+
+ <para>You can access the repository in one of two ways:
+ read-only (<xref linkend="cvs-read-only">), or read-write (<xref
+ linkend="cvs-read-write">).</para>
+
+ <sect3 id="cvs-read-only">
+ <title>Remote Read-only CVS Access</title>
+
+ <para>Read-only access is available to anyone - there's no
+ need to ask us first. With read-only CVS access you can do
+ anything except commit changes to the repository. You can
+ make changes to your local tree, and still use CVS's merge
+ facility to keep your tree up to date, and you can generate
+ patches using 'cvs diff' in order to send to us for
+ inclusion. </para>
+
+ <para>To get read-only access to the repository:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Make sure that <application>cvs</application> is
+ installed on your machine.</para>
+ </listitem>
+ <listitem>
+ <para>Set your <literal>$CVSROOT</literal> environment variable to
+ <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+ </listitem>
+ <listitem>
+ <para>Run the command</para>
+<programlisting>
+ $ cvs login
+</programlisting>
+ <para>The password is simply <literal>cvs</literal>. This
+ sets up a file in your home directory called
+ <literal>.cvspass</literal>, which squirrels away the
+ dummy password, so you only need to do this step once.</para>
+ </listitem>
+
+ <listitem>
+ <para>Now go to <xref linkend="cvs-first">.</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+
+ <sect3 id="cvs-read-write">
+ <title>Remote Read-Write CVS Access</title>
+
+ <para>We generally supply read-write access to folk doing
+ serious development on some part of the source tree, when
+ going through us would be a pain. If you're developing some
+ feature, or think you have the time and inclination to fix
+ bugs in our sources, feel free to ask for read-write
+ access. There is a certain amount of responsibility that goes
+ with commit privileges; we are more likely to grant you access
+ if you've demonstrated your competence by sending us patches
+ via mail in the past.</para>
+
+ <para>To get remote read-write CVS access, you need to do the
+ following steps.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Make sure that <literal>cvs</literal> and
+ <literal>ssh</literal> are both installed on your
+ machine.</para>
+ </listitem>
+
+ <listitem>
+ <para>Generate a DSA private-key/public-key pair, thus:</para>
+<screen>
+ $ ssh-keygen -d
+</screen>
+ <para>(<literal>ssh-keygen</literal> comes with
+ <literal>ssh</literal>.) Running <literal>ssh-keygen
+ -d</literal> creates the private and public keys in
+ <literal>$HOME/.ssh/id_dsa</literal> and
+ <literal>$HOME/.ssh/id_dsa.pub</literal> respectively
+ (assuming you accept the standard defaults).</para>
+
+ <para><literal>ssh-keygen -d</literal> will only work if
+ you have Version 2 <literal>ssh</literal> installed; it
+ will fail harmlessly otherwise. If you only have Version
+ 1 you can instead generate an RSA key pair using plain</para>
+<screen>
+ $ ssh-keygen
+</screen>
+
+ <para>Doing so creates the private and public RSA keys in
+ <literal>$HOME/.ssh/identity</literal> and
+ <literal>$HOME/.ssh/identity.pub</literal>
+ respectively.</para>
+
+ <para>[Deprecated.] Incidentally, you can force a Version
+ 2 <literal>ssh</literal> to use the Version 1 protocol by
+ creating <literal>$HOME/config</literal> with the
+ following in it:</para>
+<screen>
+ BatchMode Yes
+
+ Host cvs.haskell.org
+ Protocol 1
+</screen>
+
+ <para>In both cases, <literal>ssh-keygen</literal> will
+ ask for a <firstterm>passphrase</firstterm>. The
+ passphrase is a password that protects your private key.
+ In response to the 'Enter passphrase' question, you can
+ either:</para>
+ <itemizedlist>
+ <listitem>
+ <para>[Recommended.] Enter a passphrase, which you
+ will quote each time you use CVS.
+ <literal>ssh-agent</literal> makes this entirely
+ un-tiresome.</para>
+ </listitem>
+ <listitem>
+ <para>[Deprecated.] Just hit return (i.e. use an empty
+ passphrase); then you won't need to quote the
+ passphrase when using CVS. The downside is that
+ anyone who can see into your <literal>.ssh</literal>
+ directory, and thereby get your private key, can mess
+ up the repository. So you must keep the
+ <literal>.ssh</literal> directory with draconian
+ no-access permissions.</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>
+ <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+ </para>
+
+
+ </listitem>
+
+ <listitem>
+ <para>Send a message to to the CVS repository
+ administrator (currently Jeff Lewis
+ <email>jeff@galconn.com</email>), containing:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Your desired user-name.</para>
+ </listitem>
+ <listitem>
+ <para>Your <literal>.ssh/id_dsa.pub</literal> (or
+ <literal>.ssh/identity.pub</literal>).</para>
+ </listitem>
+ </itemizedlist>
+ <para>He will set up your account.</para>
+ </listitem>
+
+ <listitem>
+ <para>Set the following environment variables:</para>
+ <ItemizedList>
+ <listitem>
+ <para>
+ <constant>$HOME</constant>: points to your home directory. This is where CVS
+ will look for its <filename>.cvsrc</filename> file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <constant>$CVS_RSH</constant> to <filename>ssh</filename>
+ </para>
+ <para>[Windows users.] Setting your <literal>CVS_RSH</literal> to
+ <literal>ssh</literal> assumes that your CVS client
+ understands how to execute shell script
+ ("#!"s,really), which is what
+ <literal>ssh</literal> is. This may not be the case on
+ Win32 platforms, so in that case set <literal>CVS_RSH</literal> to
+ <literal>ssh1</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>$CVSROOT</literal> to
+ <literal>:ext:</literal><replaceable>your-username</replaceable>
+ <literal>@cvs.haskell.org:/home/cvs/root</literal>
+ where <replaceable>your-username</replaceable> is your user name on
+ <literal>cvs.haskell.org</literal>.
+ </para>
+ <para>The <literal>CVSROOT</literal> environment variable will
+ be recorded in the checked-out tree, so you don't need to set
+ this every time. </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ <constant>$CVSEDITOR</constant>: <filename>bin/gnuclient.exe</filename>
+ if you want to use an Emacs buffer for typing in those long commit messages.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <constant>$SHELL</constant>: To use bash as the shell in Emacs, you need to
+ set this to point to <filename>bash.exe</filename>.
+ </para>
+ </listitem>
+
+ </ItemizedList>
+
+
+ </listitem>
+
+ <listitem>
+ <para>
+ Put the following in <filename>$HOME/.cvsrc</filename>:
+ </para>
+
+ <ProgramListing>
+ checkout -P
+ release -d
+ update -P
+ diff -u
+ </ProgramListing>
+
+ <para>
+ These are the default options for the specified CVS commands,
+ and represent better defaults than the usual ones. (Feel
+ free to change them.)
+ </para>
+
+ <para>
+ [Windows users.] Filenames starting with <filename>.</filename> were illegal in
+ the 8.3 DOS filesystem, but that restriction should have
+ been lifted by now (i.e., you're using VFAT or later filesystems.) If
+ you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
+ optional.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>[Experts.] Once your account is set up, you can get
+ access from other machines without bothering Jeff, thus:</para>
+ <orderedlist>
+ <listitem>
+ <para>Generate a public/private key pair on the new
+ machine.</para>
+ </listitem>
+ <listitem>
+ <para>Use ssh to log in to
+ <literal>cvs.haskell.org</literal>, from your old
+ machine.</para>
+ </listitem>
+ <listitem>
+ <para>Add the public key for the new machine to the file
+ <literal>$HOME/ssh/authorized_keys</literal> on
+ <literal>cvs.haskell.org</literal>.
+ (<literal>authorized_keys2</literal>, I think, for Version
+ 2 protocol.)</para>
+ </listitem>
+ <listitem>
+ <para>Make sure that the new version of
+ <literal>authorized_keys</literal> still has 600 file
+ permissions.</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
+
+
+
+ <sect2 id="cvs-first">
+ <title>Checking Out a Source Tree</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Make sure you set your <literal>CVSROOT</literal>
+ environment variable according to either of the remote
+ methods above. The Approved Way to check out a source tree
+ is as follows:</para>
+
+<screen>
+ $ cvs checkout fpconfig
+</screen>
+
+ <para>At this point you have a new directory called
+ <literal>fptools</literal> which contains the basic stuff
+ for the fptools suite, including the configuration files and
+ some other junk. </para>
+
+<para>[Windows users.] The following messages appear to be harmless:
<Screen>
-$(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.
+setsockopt IPTOS_LOWDELAY: Invalid argument
+setsockopt IPTOS_THROUGHPUT: Invalid argument
+</Screen>
</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:
-
+ <para>You can call the fptools directory whatever you like,
+ CVS won't mind: </para>
+
+<screen>
+ $ mv fptools <replaceable>directory</replaceable>
+</screen>
+
+ <para> NB: after you've read the CVS manual you might be
+ tempted to try</para>
+<screen>
+ $ cvs checkout -d <replaceable>directory</replaceable> fpconfig
+</screen>
+
+ <para>instead of checking out <literal>fpconfig</literal>
+ and then renaming it. But this doesn't work, and will
+ result in checking out the entire repository instead of just
+ the <literal>fpconfig</literal> bit.</para>
+<screen>
+ $ cd <replaceable>directory</replaceable>
+ $ cvs checkout ghc hslibs libraries
+</screen>
+
+ <para>The second command here checks out the relevant
+ modules you want to work on. For a GHC build, for instance,
+ you need at least the <literal>ghc</literal>,
+ <literal>hslibs</literal> and <literal>libraries</literal>
+ modules (for a full list of the projects available, see
+ <xref linkend="projects">).</para>
+
+ <para>Remember that if you do not have
+ <literal>happy</literal> installed, you need to check it out
+ as well.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="cvs-committing">
+ <title>Committing Changes</title>
+
+ <para>This is only if you have read-write access to the
+ repository. For anoncvs users, CVS will issue a "read-only
+ repository" error if you try to commit changes.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Build the software, if necessary. Unless you're just
+ working on documentation, you'll probably want to build the
+ software in order to test any changes you make.</para>
+ </listitem>
+
+ <listitem>
+ <para>Make changes. Preferably small ones first.</para>
+ </listitem>
+
+ <listitem>
+ <para>Test them. You can see exactly what changes you've
+ made by using the <literal>cvs diff</literal> command:</para>
+<screen>
+$ cvs diff
+</screen>
+ <para>lists all the changes (using the
+ <literal>diff</literal> command) in and below the current
+ directory. In emacs, <literal>C-c C-v =</literal> runs
+ <literal>cvs diff</literal> on the current buffer and shows
+ you the results.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you changed something in the
+ <literal>fptools/libraries</literal> subdirectories, also run
+ <literal>make html</literal> to check if the documentation can
+ be generated successfully, too.</para>
+ </listitem>
+
+ <listitem>
+ <para>Before checking in a change, you need to update your
+ source tree:</para>
+
+<screen>
+$ cd fptools
+$ cvs update
+</screen>
+ <para>This pulls in any changes that other people have made,
+ and merges them with yours. If there are any conflicts, CVS
+ will tell you, and you'll have to resolve them before you
+ can check your changes in. The documentation describes what
+ to do in the event of a conflict.</para>
+
+ <para>It's not always necessary to do a full cvs update
+ before checking in a change, since CVS will always tell you
+ if you try to check in a file that someone else has changed.
+ However, you should still update at regular intervals to
+ avoid making changes that don't work in conjuction with
+ changes that someone else made. Keeping an eye on what goes
+ by on the mailing list can help here.</para>
+ </listitem>
+
+ <listitem>
+ <para>When you're happy that your change isn't going to
+ break anything, check it in. For a one-file change:</para>
+
+<screen>
+$ cvs commit <replaceable>filename</replaceable>
+</screen>
+
+ <para>CVS will then pop up an editor for you to enter a
+ "commit message", this is just a short description
+ of what your change does, and will be kept in the history of
+ the file.</para>
+
+ <para>If you're using emacs, simply load up the file into a
+ buffer and type <literal>C-x C-q</literal>, and emacs will
+ prompt for a commit message and then check in the file for
+ you.</para>
+
+ <para>For a multiple-file change, things are a bit
+ trickier. There are several ways to do this, but this is the
+ way I find easiest. First type the commit message into a
+ temporary file. Then either</para>
+
+<screen>
+$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>file_1</replaceable> .... <replaceable>file_n</replaceable>
+</screen>
+
+ <para>or, if nothing else has changed in this part of the
+ source tree, </para>
+
+<screen>
+$ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory</replaceable>
+</screen>
+
+ <para>where <replaceable>directory</replaceable> is a common
+ parent directory for all your changes, and
+ <replaceable>commit-message</replaceable> is the name of the
+ file containing the commit message.</para>
+
+ <para>Shortly afterwards, you'll get some mail from the
+ relevant mailing list saying which files changed, and giving
+ the commit message. For a multiple-file change, you should
+ still get only <emphasis>one</emphasis> message.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="cvs-update">
+ <title>Updating Your Source Tree</title>
+
+ <para>It can be tempting to cvs update just part of a source
+ tree to bring in some changes that someone else has made, or
+ before committing your own changes. This is NOT RECOMMENDED!
+ Quite often changes in one part of the tree are dependent on
+ changes in another part of the tree (the
+ <literal>mk/*.mk</literal> files are a good example where
+ problems crop up quite often). Having an inconsistent tree is a
+ major cause of headaches. </para>
+
+ <para>So, to avoid a lot of hassle, follow this recipe for
+ updating your tree:</para>
+
+<screen>
+$ cd fptools
+$ cvs update -P 2>&1 | tee log</screen>
+
+ <para>Look at the log file, and fix any conflicts (denoted by a
+ <quote>C</quote> in the first column). New directories may have
+ appeared in the repository; CVS doesn't check these out by
+ default, so to get new directories you have to explicitly do
+<screen>
+$ cvs update -d</screen>
+ in each project subdirectory. Don't do this at the top level,
+ because then <emphasis>all</emphasis> the projects will be
+ checked out.</para>
+
+ <para>If you're using multiple build trees, then for every build
+ tree you have pointing at this source tree, you need to update
+ the links in case any new files have appeared: </para>
+
+<screen>
+$ cd <replaceable>build-tree</replaceable>
+$ lndir <replaceable>source-tree</replaceable>
+</screen>
+
+ <para>Some files might have been removed, so you need to remove
+ the links pointing to these non-existent files:</para>
+
+<screen>
+$ find . -xtype l -exec rm '{}' \;
+</screen>
+
+ <para>To be <emphasis>really</emphasis> safe, you should do
+ </para>
+
+<screen>$ gmake all</screen>
+
+ <para>from the top-level, to update the dependencies and build
+ any changed files. </para>
+ </sect2>
+
+ <sect2 id="cvs-tags">
+ <title>GHC Tag Policy</title>
+
+ <para>If you want to check out a particular version of GHC,
+ you'll need to know how we tag versions in the repository. The
+ policy (as of 4.04) is:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The tree is branched before every major release. The
+ branch tag is <literal>ghc-x-xx-branch</literal>, where
+ <literal>x-xx</literal> is the version number of the release
+ with the <literal>'.'</literal> replaced by a
+ <literal>'-'</literal>. For example, the 4.04 release lives
+ on <literal>ghc-4-04-branch</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The release itself is tagged with
+ <literal>ghc-x-xx</literal> (on the branch). eg. 4.06 is
+ called <literal>ghc-4-06</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>We didn't always follow these guidelines, so to see
+ what tags there are for previous versions, do <literal>cvs
+ log</literal> on a file that's been around for a while (like
+ <literal>fptools/ghc/README</literal>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>So, to check out a fresh GHC 4.06 tree you would
+ do:</para>
+
+<screen>
+ $ cvs co -r ghc-4-06 fpconfig
+ $ cd fptools
+ $ cvs co -r ghc-4-06 ghc hslibs
+</screen>
+ </sect2>
+
+ <sect2 id="cvs-hints">
+ <title>General Hints</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>As a general rule: commit changes in small units,
+ preferably addressing one issue or implementing a single
+ feature. Provide a descriptive log message so that the
+ repository records exactly which changes were required to
+ implement a given feature/fix a bug. I've found this
+ <emphasis>very</emphasis> useful in the past for finding out
+ when a particular bug was introduced: you can just wind back
+ the CVS tree until the bug disappears.</para>
+ </listitem>
+
+ <listitem>
+ <para>Keep the sources at least *buildable* at any given
+ time. No doubt bugs will creep in, but it's quite easy to
+ ensure that any change made at least leaves the tree in a
+ buildable state. We do nightly builds of GHC to keep an eye
+ on what things work/don't work each day and how we're doing
+ in relation to previous verions. This idea is truely wrecked
+ if the compiler won't build in the first place!</para>
+ </listitem>
+
+ <listitem>
+ <para>To check out extra bits into an already-checked-out
+ tree, use the following procedure. Suppose you have a
+ checked-out fptools tree containing just ghc, and you want
+ to add nofib to it:</para>
+
+<screen>
+$ cd fptools
+$ cvs checkout nofib
+</screen>
+
+ <para>or: </para>
+
+<screen>
+$ cd fptools
+$ cvs update -d nofib
+</screen>
+
+ <para>(the -d flag tells update to create a new
+ directory). If you just want part of the nofib suite, you
+ can do </para>
+
+<screen>
+$ cd fptools
+$ cvs checkout nofib/spectral
+</screen>
+
+ <para>This works because <literal>nofib</literal> is a
+ module in its own right, and spectral is a subdirectory of
+ the nofib module. The path argument to checkout must always
+ start with a module name. There's no equivalent form of this
+ command using <literal>update</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="projects">
+ <title>What projects are there?</title>
+
+ <para>The <literal>fptools</literal> suite consists of several
+ <firstterm>projects</firstterm>, most of which can be downloaded,
+ built and installed individually. Each project corresponds to a
+ subdirectory in the source tree, and if checking out from CVS then
+ each project can be checked out individually by sitting in the top
+ level of your source tree and typing <command>cvs checkout
+ <replaceable>project</replaceable></command>.</para>
+
+ <para>Here is a list of the projects currently available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>ghc</literal></term>
+ <indexterm><primary><literal>ghc</literal></primary>
+ <secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
+ Haskell Compiler</ulink> (minus libraries). Absolutely
+ required for building GHC.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>glafp-utils</literal></term>
+ <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Utility programs, some of which are used by the
+ build/installation system. Required for pretty much
+ everything.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>greencard</literal></term>
+ <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/greencard/">GreenCard</ulink>
+ system for generating Haskell foreign function
+ interfaces.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>haggis</literal></term>
+ <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
+ Haskell GUI framework.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>haddock</literal></term>
+ <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/haddock/">Haddock</ulink>
+ documentation tool.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>happy</literal></term>
+ <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/happy/">Happy</ulink> Parser
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hdirect</literal></term>
+ <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/hdirect/">H/Direct</ulink>
+ Haskell interoperability tool.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hood</literal></term>
+ <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink url="http://www.haskell.org/hood/">Haskell
+ Object Observation Debugger</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hslibs</literal></term>
+ <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Supplemental libraries for GHC
+ (<emphasis>required</emphasis> for building GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>libraries</literal></term>
+ <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>Hierarchical Haskell library suite
+ (<emphasis>required</emphasis> for building GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>mhms</literal></term>
+ <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+ <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>
+ <listitem>
+ <para>The NoFib suite: A collection of Haskell programs used
+ primarily for benchmarking.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>testsuite</literal></term>
+ <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
+ <listitem>
+ <para>A testing framework, including GHC's regression test
+ suite.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>So, to build GHC you need at least the
+ <literal>ghc</literal>, <literal>libraries</literal> and
+ <literal>hslibs</literal> projects (a GHC source distribution will
+ already include the bits you need).</para>
+ </sect1>
+
+ <sect1 id="sec-build-checks">
+ <title>Things to check before you start</title>
+
+ <para>Here's a list of things to check before you get
+ started.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <indexterm><primary>Disk space needed</primary></indexterm>
+ <para>Disk space needed: from about 100Mb for a basic GHC
+ build, up to probably 500Mb for a GHC build with everything
+ included (libraries built several different ways,
+ etc.).</para>
+ </listitem>
+
+ <listitem>
+ <para>Use an appropriate machine / operating system. <xref
+ linkend="sec-port-info"> lists the supported platforms; if
+ yours isn't amongst these then you can try porting GHC (see
+ <xref linkend="sec-porting-ghc">).</para>
+ </listitem>
+
+ <listitem>
+ <para>Be sure that the “pre-supposed” utilities are
+ installed. <Xref LinkEnd="sec-pre-supposed">
+ elaborates.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you have any problem when building or installing the
+ Glasgow tools, please check the “known pitfalls” (<Xref
+ LinkEnd="sec-build-pitfalls">). Also check the FAQ for the
+ version you're building, which is part of the User's Guide and
+ available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
+ site</ulink>.</para>
+
+ <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
+
+ <para>If you feel there is still some shortcoming in our
+ procedure or instructions, please report it.</para>
+
+ <para>For GHC, please see the <ulink
+ url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
+ section of the GHC Users' Guide</ulink>, to maximise the
+ usefulness of your report.</para>
+
+ <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
+ <para>If in doubt, please send a message to
+ <email>glasgow-haskell-bugs@haskell.org</email>.
+ <indexterm><primary>bugs</primary><secondary>mailing
+ list</secondary></indexterm></para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1 id="sec-port-info">
+ <title>What machines the Glasgow tools run on</title>
+
+<indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
+<indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
+<indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
+
+ <para>The main question is whether or not the Haskell compiler
+ (GHC) runs on your platform.</para>
+
+ <para>A “platform” is a
+ architecture/manufacturer/operating-system combination, such as
+ <literal>sparc-sun-solaris2</literal>. Other common ones are
+ <literal>alpha-dec-osf2</literal>,
+ <literal>hppa1.1-hp-hpux9</literal>,
+ <literal>i386-unknown-linux</literal>,
+ <literal>i386-unknown-solaris2</literal>,
+ <literal>i386-unknown-freebsd</literal>,
+ <literal>i386-unknown-cygwin32</literal>,
+ <literal>m68k-sun-sunos4</literal>,
+ <literal>mips-sgi-irix5</literal>,
+ <literal>sparc-sun-sunos4</literal>,
+ <literal>sparc-sun-solaris2</literal>,
+ <literal>powerpc-ibm-aix</literal>.</para>
+
+ <para>Some libraries may only work on a limited number of
+ platforms; for example, a sockets library is of no use unless the
+ operating system supports the underlying BSDisms.</para>
+
+ <sect2>
+ <title>What platforms the Haskell compiler (GHC) runs on</title>
+
+ <indexterm><primary>fully-supported platforms</primary></indexterm>
+ <indexterm><primary>native-code generator</primary></indexterm>
+ <indexterm><primary>registerised ports</primary></indexterm>
+ <indexterm><primary>unregisterised ports</primary></indexterm>
+
+ <para>The GHC hierarchy of Porting Goodness: (a) Best is a
+ native-code generator; (b) next best is a
+ “registerised” port; (c) the bare minimum is an
+ “unregisterised” port.
+ (“Unregisterised” is so terrible that we won't say
+ more about it).</para>
+
+ <para>We use Sparcs running Solaris 2.7 and x86 boxes running
+ FreeBSD and Linux, so those are the best supported platforms,
+ unsurprisingly.</para>
+
+ <para>Here's everything that's known about GHC ports. We
+ identify platforms by their “canonical”
+ CPU/Manufacturer/OS triple.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
+ <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>
+
+ <listitem>
+ <para>The OSF port is currently working (as of GHC version
+ 5.02.1) and well supported. The native code generator is
+ currently non-working. Other operating systems will
+ require some minor porting.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>sparc-sun-sunos4</term>
+ <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
+ <listitem>
+ <para>Probably works with minor tweaks, hasn't been tested
+ for a while.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>sparc-sun-solaris2</term>
+ <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
+ <listitem>
+ <para>Fully supported (at least for Solaris 2.7),
+ including native-code generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
+ <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
+ <listitem>
+ <para>A registerised port is available for version 4.08,
+ but GHC hasn't been built on that platform since (as far
+ as we know). No native-code generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
+ <indexterm><primary>i386-*-linux</primary></indexterm>
+ <listitem>
+ <para>GHC works registerised and has a native code
+ generator. You <Emphasis>must</Emphasis> have GCC 2.7.x
+ or later. NOTE about <literal>glibc</literal> versions:
+ GHC binaries built on a system running <literal>glibc
+ 2.0</literal> won't work on a system running
+ <literal>glibc 2.1</literal>, and vice versa. In general,
+ don't expect compatibility between
+ <literal>glibc</literal> versions, even if the shared
+ library version hasn't changed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
+ higher)</term>
+ <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
+ <listitem>
+ <para>GHC works registerised. Pre-built packages are
+ available in the native package format, so if you just
+ need binaries you're better off just installing the
+ package (it might even be on your installation
+ CD!).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
+ <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
+ <listitem>
+ <para>Supported, with native code generator. Packages are
+ available through the ports system in the native package
+ format.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-netbsd (PCs running NetBSD and
+ OpenBSD)</term>
+ <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+ <listitem>
+ <para>Will require some minor porting effort, but should
+ work registerised.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>i386-unknown-mingw32 (PCs running Windows)</term>
+ <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
+ <listitem>
+ <para>Fully supported under Win9x, WinNT, Win2k, and
+ WinXP. Includes a native code generator. Building from
+ source requires a recent <ulink
+ url="http://www.cygwin.com/">Cygwin</ulink> distribution
+ to be installed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ia64-unknown-linux</term>
+ <indexterm><primary>ia64-unknown-linux</primary></indexterm>
+ <listitem>
+ <para>GHC currently works unregisterised. A registerised
+ port is in progress.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mips-sgi-irix5</term>
+ <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
+ <listitem>
+ <para>Port has worked in the past, but hasn't been tested
+ for some time (and will certainly have rotted in various
+ ways). As usual, we don't have access to machines and
+ there hasn't been an overwhelming demand for this port,
+ but feel free to get in touch.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>powerpc-ibm-aix</term>
+ <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
+ <listitem>
+ <para>Port currently doesn't work, needs some minimal
+ porting effort. As usual, we don't have access to
+ machines and there hasn't been an overwhelming demand for
+ this port, but feel free to get in touch.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>powerpc-apple-darwin</term>
+ <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
+ <listitem>
+ <para>Supported registerised. No native code
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>powerpc-apple-linux</term>
+ <indexterm><primary>powerpc-apple-linux</primary></indexterm>
+ <listitem>
+ <para>Not supported (yet).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Various other systems have had GHC ported to them in the
+ distant past, including various Motorola 68k boxes. The 68k
+ support still remains, but porting to one of these systems will
+ certainly be a non-trivial task.</para>
+ </sect2>
+
+ <sect2>
+ <title>What machines the other tools run on</title>
+
+ <para>Unless you hear otherwise, the other tools work if GHC
+ works.</para>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="sec-pre-supposed">
+ <title>Installing pre-supposed utilities</title>
+
+ <indexterm><primary>pre-supposed utilities</primary></indexterm>
+ <indexterm><primary>utilities, pre-supposed</primary></indexterm>
+
+ <para>Here are the gory details about some utility programs you
+ may need; <command>perl</command>, <command>gcc</command> and
+ <command>happy</command> are the only important
+ ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
+ important if you're going for Parallel Haskell.) The
+ <command>configure</command><indexterm><primary>configure</primary></indexterm>
+ script will tell you if you are missing something.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>GHC</term>
+ <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+ <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>GHC is required to build many of the tools, including
+ GHC itself. If you need to port GHC to your platform
+ because there isn't a binary distribution of GHC available,
+ then see <xref linkend="sec-porting-ghc">.</para>
+
+ <para>Which version of GHC you need will depend on the
+ packages you intend to build. GHC itself will normally
+ build using one of several older versions of itself - check
+ the announcement or release notes for details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Perl</term>
+ <indexterm><primary>pre-supposed: Perl</primary></indexterm>
+ <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+ <listitem>
+ <para><emphasis>You have to have Perl to proceed!</emphasis>
+ Perl version 5 at least is required. GHC has been known to
+ tickle bugs in Perl, so if you find that Perl crashes when
+ running GHC try updating (or downgrading) your Perl
+ installation. Versions of Perl that we use and are known to
+ be fairly stable are 5.005 and 5.6.1.</para>
+
+ <para>For Win32 platforms, you should use the binary
+ supplied in the InstallShield (copy it to
+ <filename>/bin</filename>). The Cygwin-supplied Perl seems
+ not to work.</para>
+
+ <para>Perl should be put somewhere so that it can be invoked
+ by the <literal>#!</literal> script-invoking
+ mechanism. The full pathname may need to be less than 32
+ characters long on some systems.</para>
+ </listitem>
+ </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>
+ <listitem>
+ <para>We recommend using GCC version 2.95.2 on all
+ platforms. Failing that, version 2.7.2 is stable on most
+ platforms. Earlier versions of GCC can be assumed not to
+ work, and versions in between 2.7.2 and 2.95.2 (including
+ <command>egcs</command>) have varying degrees of stability
+ depending on the platform.</para>
+
+ <para>GCC 3.2 is currently known to have problems building
+ GHC on Sparc, but is stable on x86.</para>
+
+ <para>GCC 3.3 currently cannot be used to build GHC, due to
+ some problems with the new C preprocessor.</para>
+
+ <para>If your GCC dies with “internal error” on
+ some GHC source file, please let us know, so we can report
+ it and get things improved. (Exception: on iX86
+ boxes—you may need to fiddle with GHC's
+ <option>-monly-N-regs</option> option; see the User's
+ Guide)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GNU Make</term>
+ <indexterm><primary>make</primary><secondary>GNU</secondary>
+ </indexterm>
+ <listitem>
+ <para>The fptools build system makes heavy use of features
+ specific to GNU <command>make</command>, so you must have
+ this installed in order to build any of the fptools
+ suite.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Happy</term>
+ <indexterm><primary>Happy</primary></indexterm>
+ <listitem>
+ <para>Happy is a parser generator tool for Haskell, and is
+ used to generate GHC's parsers. Happy is written in
+ Haskell, and is a project in the CVS repository
+ (<literal>fptools/happy</literal>). It can be built from
+ source, but bear in mind that you'll need GHC installed in
+ order to build it. To avoid the chicken/egg problem,
+ install a binary distribution of either Happy or GHC to get
+ started. Happy distributions are available from <ulink
+ url="http://www.haskell.org/happy/">Happy's Web
+ Page</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Autoconf</term>
+ <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
+ <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>GNU Autoconf is needed if you intend to build from the
+ CVS sources, it is <emphasis>not</emphasis> needed if you
+ just intend to build a standard source distribution.</para>
+
+ <para>Version 2.52 or later of autoconf is required.
+ NB. vesrion 2.13 will no longer work, as of GHC version
+ 6.1.</para>
+
+ <para>Autoconf builds the <command>configure</command>
+ script from <filename>configure.ac</filename> and
+ <filename>aclocal.m4</filename>. If you modify either of
+ these files, you'll need <command>autoconf</command> to
+ rebuild <filename>configure</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>sed</command></term>
+ <indexterm><primary>pre-supposed: sed</primary></indexterm>
+ <indexterm><primary>sed, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>You need a working <command>sed</command> if you are
+ going to build from sources. The build-configuration stuff
+ needs it. GNU sed version 2.0.4 is no good! It has a bug
+ in it that is tickled by the build-configuration. 2.0.5 is
+ OK. Others are probably OK too (assuming we don't create too
+ elaborate configure scripts.)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>One <literal>fptools</literal> project is worth a quick note
+ at this point, because it is useful for all the others:
+ <literal>glafp-utils</literal> contains several utilities which
+ aren't particularly Glasgow-ish, but Occasionally Indispensable.
+ Like <command>lndir</command> for creating symbolic link
+ trees.</para>
+
+ <sect2 id="pre-supposed-gph-tools">
+ <title>Tools for building parallel GHC (GPH)</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>PVM version 3:</term>
+ <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
+ <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
+ <listitem>
+ <para>PVM is the Parallel Virtual Machine on which
+ Parallel Haskell programs run. (You only need this if you
+ plan to run Parallel Haskell. Concurrent Haskell, which
+ runs concurrent threads on a uniprocessor doesn't need
+ it.) Underneath PVM, you can have (for example) a network
+ of workstations (slow) or a multiprocessor box
+ (faster).</para>
+
+ <para>The current version of PVM is 3.3.11; we use 3.3.7.
+ It is readily available on the net; I think I got it from
+ <literal>research.att.com</literal>, in
+ <filename>netlib</filename>.</para>
+
+ <para>A PVM installation is slightly quirky, but easy to
+ do. Just follow the <filename>Readme</filename>
+ instructions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>bash</command>:</term>
+ <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
+ <listitem>
+ <para>Sadly, the <command>gr2ps</command> script, used to
+ convert “parallelism profiles” to PostScript,
+ is written in Bash (GNU's Bourne Again shell). This bug
+ will be fixed (someday).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </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>
+
+ <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>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec-building-from-source">
+ <title>Building from source</title>
+
+ <indexterm><primary>Building from source</primary></indexterm>
+ <indexterm><primary>Source, building from</primary></indexterm>
+
+ <para>You've been rash enough to want to build some of the Glasgow
+ Functional Programming tools (GHC, Happy, nofib, etc.) from
+ source. You've slurped the source, from the CVS repository or
+ from a source distribution, and now you're sitting looking at a
+ huge mound of bits, wondering what to do next.</para>
+
+ <para>Gingerly, you type <command>make</command>. Wrong
+ already!</para>
+
+ <para>This rest of this guide is intended for duffers like me, who
+ aren't really interested in Makefiles and systems configurations,
+ but who need a mental model of the interlocking pieces so that
+ they can make them work, extend them consistently when adding new
+ software, and lay hands on them gently when they don't
+ work.</para>
+
+ <sect2 id="quick-start">
+ <title>Quick Start</title>
+
+ <para>If you are starting from a source distribution, and just
+ want a completely standard build, then the following should
+ work:</para>
+
+<screen>$ ./configure
+$ make
+$ make install
+</screen>
+
+ <para>For GHC, this will do a 2-stage bootstrap build of the
+ compiler, with profiling libraries, and install the
+ results.</para>
+
+ <para>If you want to do anything at all non-standard, or you
+ want to do some development, read on...</para>
+ </sect2>
+
+ <sect2 id="sec-source-tree">
+ <title>Your source tree</title>
+
+ <para>The source code is held in your <emphasis>source
+ tree</emphasis>. The root directory of your source tree
+ <emphasis>must</emphasis> contain the following directories and
+ files:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>Makefile</filename>: the root
+ Makefile.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>mk/</filename>: the directory that contains
+ the main Makefile code, shared by all the
+ <literal>fptools</literal> software.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>configure.ac</filename>,
+ <filename>config.sub</filename>,
+ <filename>config.guess</filename>: these files support the
+ configuration process.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>install-sh</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>All the other directories are individual
+ <emphasis>projects</emphasis> of the <literal>fptools</literal>
+ system—for example, the Glasgow Haskell Compiler
+ (<literal>ghc</literal>), the Happy parser generator
+ (<literal>happy</literal>), the <literal>nofib</literal>
+ benchmark suite, and so on. You can have zero or more of these.
+ Needless to say, some of them are needed to build others.</para>
+
+ <para>The important thing to remember is that even if you want
+ only one project (<literal>happy</literal>, say), you must have
+ a source tree whose root directory contains
+ <filename>Makefile</filename>, <filename>mk/</filename>,
+ <filename>configure.ac</filename>, and the project(s) you want
+ (<filename>happy/</filename> in this case). You cannot get by
+ with just the <filename>happy/</filename> directory.</para>
+ </sect2>
+
+ <sect2>
+ <title>Build trees</title>
+ <indexterm><primary>build trees</primary></indexterm>
+ <indexterm><primary>link trees, for building</primary></indexterm>
+
+ <para>If you just want to build the software once on a single
+ platform, then your source tree can also be your build tree, and
+ you can skip the rest of this section.</para>
+
+ <para>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.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Step 1: get ready for configuration.</term>
+ <listitem>
+ <para>NOTE: if you're starting from a source distribution,
+ rather than CVS sources, you can skip this step.</para>
+
+ <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.ac</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.ac</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.ac</filename>) can
+ be short, although the resulting shell script,
+ <command>configure</command>, and
+ <filename>mk/config.h.in</filename>, are long.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Step 2: system configuration.</term>
+ <listitem>
+ <para>Runs the newly-created <command>configure</command>
+ script, thus:</para>
<ProgramListing>
-SRC_HC_OPTS += -O
+./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>tar</command> is kept, whether
+ <command>gcc</command> is available, where various obscure
+ <literal>#include</literal> files are, whether it's a
+ leap year, and what the systems manager had for lunch. It
+ 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>
-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:
-
+ <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>And that's it for configuration. Simple, eh?</para>
-<ItemizedList>
-<ListItem>
+ <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>
- <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:
+ <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
+ that can serve as a starting point for your <filename>build.mk</filename>.</para>
+ <para>For example, <filename>config.mk.in</filename> contains
+ the definition:</para>
<ProgramListing>
-$(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@
+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>
-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
+<ProgramListing>
+GhcHcOpts += -DDEBUG
+</ProgramListing>
-<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title>
+ <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 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>If you want to remove the <literal>-O</literal> as well (a
+ good idea when developing, because the turn-around cycle gets a
+ lot quicker), you can just override
+ <literal>GhcLibHcOpts</literal> altogether:</para>
-<para>
-<VariableList>
+<ProgramListing>
+GhcHcOpts=-DDEBUG -Rghc-timing
+</ProgramListing>
-<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>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>
-<para>
-<VariableList>
+<ProgramListing>
+TAR = @TarCmd@
+</ProgramListing>
-<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>This defines the Make variables <constant>TAR</constant>
+ to the pathname for a <command>tar</command> that
+ <command>configure</command> finds somewhere. If you have your
+ own pet <command>tar</command> you want to use instead, that's
+ fine. Just add this line to <filename>mk/build.mk</filename>:</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>
+<ProgramListing>
+TAR = mytar
+</ProgramListing>
-<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>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>
-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>
+ <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>
+
+ <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>
+
+ <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>(Optional) Use <command>lndir</command> or
+ <command>mkshadowdir</command> to create a build tree.</para>
+
+<programlisting>
+$ cd myfptools
+$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4
+</programlisting>
+
+ <para>(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.</para>
+
+<programlisting>
+$ cd /scratch/joe-bloggs/myfptools-sun4
+</programlisting>
+
+ </listitem>
+
+ <listitem>
+ <para>Prepare for system configuration:</para>
+
+<programlisting>
+$ autoconf
+</programlisting>
+
+ <para>(You can skip this step if you are starting from a
+ source distribution, and you already have
+ <filename>configure</filename> and
+ <filename>mk/config.h.in</filename>.)</para>
+
+ <para>Some projects, including GHC itself, have their own
+ configure scripts, so it is necessary to run autoconf again
+ in the appropriate subdirectories. eg:</para>
+
+<programlisting>
+$ (cd ghc; autoconf)
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Do system configuration:</para>
+
+<programlisting>
+$ ./configure
+</programlisting>
+
+ <para>Don't forget to check whether you need to add any
+ arguments to <literal>configure</literal>; for example, a
+ common requirement is to specify which GHC to use with
+ <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Create the file <filename>mk/build.mk</filename>,
+ adding definitions for your desired configuration
+ options.</para>
+
+<programlisting>
+$ emacs mk/build.mk
+</programlisting>
+ </listitem>
+ </orderedlist>
+
+ <para>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>
-<Sect2 id="sec-suffix">
-<Title>Pattern rules and options
+ <para>At this point you have made yourself a fully-configured
+ build tree, so you are ready to start building real
+ things.</para>
-<IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title>
+ <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>
-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>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-bootstrapping">
+ <title>Bootstrapping GHC</title>
+
+ <para>GHC requires a 2-stage bootstrap in order to provide
+ full functionality, including GHCi. By a 2-stage bootstrap, we
+ mean that the compiler is built once using the installed GHC,
+ and then again using the compiler built in the first stage. You
+ can also build a stage 3 compiler, but this normally isn't
+ necessary except to verify that the stage 2 compiler is working
+ properly.</para>
+
+ <para>Note that when doing a bootstrap, the stage 1 compiler
+ must be built, followed by the runtime system and libraries, and
+ then the stage 2 compiler. The correct ordering is implemented
+ by the top-level fptools <filename>Makefile</filename>, so if
+ you want everything to work automatically it's best to start
+ <command>make</command> from the top of the tree. When building
+ GHC, the top-level fptools <filename>Makefile</filename> is set
+ up to do a 2-stage bootstrap by default (when you say
+ <command>make</command>). Some other targets it supports
+ are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>stage1</term>
+ <listitem>
+ <para>Build everything as normal, including the stage 1
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>stage2</term>
+ <listitem>
+ <para>Build the stage 2 compiler only.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>stage3</term>
+ <listitem>
+ <para>Build the stage 3 compiler only.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>bootstrap</term> <term>bootstrap2</term>
+ <listitem>
+ <para>Build stage 1 followed by stage 2.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>bootstrap3</term>
+ <listitem>
+ <para>Build stages 1, 2 and 3.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>install</term>
+ <listitem>
+ <para>Install everything, including the compiler built in
+ stage 2. To override the stage, say <literal>make install
+ stage=<replaceable>n</replaceable></literal> where
+ <replaceable>n</replaceable> is the stage to install.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The top-level <filename>Makefile</filename> also arranges
+ to do the appropriate <literal>make boot</literal> steps (see
+ below) before actually building anything.</para>
+
+ <para>The <literal>stage1</literal>, <literal>stage2</literal>
+ and <literal>stage3</literal> targets also work in the
+ <literal>ghc/compiler</literal> directory, but don't forget that
+ each stage requires its own <literal>make boot</literal> step:
+ for example, you must do</para>
+
+ <screen>$ make boot stage=2</screen>
+
+ <para>before <literal>make stage2</literal> in
+ <literal>ghc/compiler</literal>.</para>
+ </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:</para>
+
+ <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>
+ (except for the documentation). 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>install-docs</literal></term>
+ <listitem>
+ <para>installs the documentation. Otherwise behaves just
+ like <literal>install</literal>.</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>All of these standard targets automatically recurse into
+ sub-directories. Certain other standard targets do not:</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>
-Almost all the rules look something like this:
-</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>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-6.xx</filename>, as these are the
+ scripts intended for installation, and contain hard-wired paths
+ to the installed libraries, rather than the libraries in the
+ build tree.</para>
+
+ <para>Happy can similarly be run from the build tree, using
+ <filename>happy/src/happy-inplace</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Fast Making</title>
+
+ <indexterm><primary>fastmake</primary></indexterm>
+ <indexterm><primary>dependencies, omitting</primary></indexterm>
+ <indexterm><primary>FAST, makefile variable</primary></indexterm>
+
+ <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>
<ProgramListing>
-%.o : %.c
- $(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@
+gmake FAST=YES
</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>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</title>
+ <indexterm><primary>makefile architecture</primary></indexterm>
+
+ <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>Debugging</title>
+
+ <para>Debugging <filename>Makefile</filename>s is something of a
+ black art, but here's a couple of tricks that we find
+ particularly useful. The following command allows you to see
+ the contents of any make variable in the context of the current
+ <filename>Makefile</filename>:</para>
+
+<screen>$ make show VALUE=HS_SRCS</screen>
+
+ <para>where you can replace <literal>HS_SRCS</literal> with the
+ name of any variable you wish to see the value of.</para>
+
+ <para>GNU make has a <option>-d</option> option which generates
+ a dump of the decision procedure used to arrive at a conclusion
+ about which files should be recompiled. Sometimes useful for
+ tracking down problems with superfluous or missing
+ recompilations.</para>
+ </sect2>
+
+ <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>
+
+<indexterm><primary>Makefile, minimal</primary></indexterm>
-<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>
+<ProgramListing>
+# Makefile for fptools project "small"
-<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>
+TOP = ..
+include $(TOP)/mk/boilerplate.mk
-<para>
+SRCS = $(wildcard *.lhs) $(wildcard *.c)
+HS_PROG = small
-<ProgramListing>
-CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
+include $(TOP)/target.mk
</ProgramListing>
-</para>
-
-<para>
-The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning:
-</para>
-
-<para>
-<VariableList>
+ <para>this <filename>Makefile</filename> has three
+ sections:</para>
-<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>
+ <orderedlist>
+ <listitem>
+ <para>The first section includes
+<footnote>
<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:
+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>
-
-<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></para>
+
+ <para>Before the <literal>include</literal> statement, you
+ must define the <command>make</command> variable
+ <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
+ to be the directory containing the <filename>mk</filename>
+ directory in which the <filename>boilerplate.mk</filename>
+ file is. It is <emphasis>not</emphasis> OK to simply say</para>
<ProgramListing>
-gmake libHS.a EXTRA_CC_OPTS="-v"
+include ../mk/boilerplate.mk # NO NO NO
</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>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.</para>
+
+ <para>Files intended for inclusion in other
+ <filename>Makefile</filename>s are written to have the
+ following property: <emphasis>after
+ <filename>foo.mk</filename> is <literal>include</literal>d,
+ it leaves <constant>TOP</constant> containing the same value
+ as it had just before the <literal>include</literal>
+ statement</emphasis>. In our example, this invariant
+ guarantees that the <literal>include</literal> for
+ <filename>target.mk</filename> will look in the same
+ directory as that for <filename>boilerplate.mk</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para> The second section defines the following standard
+ <command>make</command> variables:
+ <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
+ (the source files from which is to be built), and
+ <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
+ (the executable binary to be built). We will discuss in
+ more detail what the “standard variables” are,
+ and how they affect what happens, in <XRef
+ LinkEnd="sec-targets">.</para>
+
+ <para>The definition for <constant>SRCS</constant> uses the
+ useful GNU <command>make</command> construct
+ <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
+ which expands to a list of all the files matching the
+ pattern <literal>pat</literal> in the current directory. In
+ this example, <constant>SRCS</constant> is set to the list
+ of all the <filename>.lhs</filename> and
+ <filename>.c</filename> files in the directory. (Let's
+ suppose there is one of each, <filename>Foo.lhs</filename>
+ and <filename>Baz.c</filename>.)</para>
+ </listitem>
+
+ <listitem>
+ <para>The last section includes a second file of standard
+ code, called
+ <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
+ It contains the rules that tell <command>gmake</command> how
+ 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>
+
+ <para>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>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>
+
+ <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>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>
-<VariableList>
+<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>
-<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>
+ <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>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>ghc/mk/boilerplate.mk</filename> is included
+ at the top of <filename>ghc/Makefile</filename>, and of all
+ the leaf <filename>Makefile</filename>s in the
+ sub-directories. It in turn <literal>include</literal>s the
+ main boilerplate file
+ <filename>mk/boilerplate.mk</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>ghc/mk/target.mk</filename> is
+ <literal>include</literal>d at the bottom of
+ <filename>ghc/Makefile</filename>, and of all the leaf
+ <filename>Makefile</filename>s in the sub-directories. It
+ in turn <literal>include</literal>s the file
+ <filename>mk/target.mk</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>So these two files are the place to look for GHC-wide
+ customisation of the standard boilerplate.</para>
+ </sect2>
+
+ <sect2 id="sec-boiler-arch">
+ <title>Boilerplate architecture</title>
+ <indexterm><primary>boilerplate architecture</primary></indexterm>
+
+ <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>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>boilerplate.mk</filename> consists of:</para>
+
+ <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>
-<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>
+ <listitem>
+ <para><emphasis>Standard pattern rules</emphasis> that
+ tell <command>gmake</command> how to construct one file
+ from another.</para>
+ </listitem>
+ </itemizedlist>
-<para>
-All of these rules are ``double-colon'' rules, thus
-</para>
+ <para><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.</para>
-<para>
+ <para>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:</para>
<ProgramListing>
-install :: $(HS_PROG)
- ...how to install it...
+SRC_HC_OPTS += -O
</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>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.</para>
+
+ <para><filename>target.mk</filename> must be included at the
+ end (rather than being part of
+ <filename>boilerplate.mk</filename>) for several tiresome
+ reasons:</para>
+
+ <itemizedlist>
+ <listitem>
-<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>
+ <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:</para>
-</Sect2>
+<ProgramListing>
+$(HS_PROG) : $(OBJS)
+ $(HC) $(LD_OPTS) $< -o $@
+</ProgramListing>
-<Sect2 id="sec-ways">
-<Title>Way management
+ <para>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>
-<IndexTerm><Primary>way management</Primary></IndexTerm></Title>
+ <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>
-<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>
+ <listitem>
+ <para>There are a couple of other reasons I've
+ forgotten, but it doesn't matter too much.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="sec-boiler">
+ <title>The main <filename>mk/boilerplate.mk</filename> file</title>
+ <indexterm><primary>boilerplate.mk</primary></indexterm>
+
+ <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>
+
+ <variablelist>
+ <varlistentry>
+ <term><filename>config.mk</filename></term>
+ <indexterm><primary>config.mk</primary></indexterm>
+ <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></term>
+ <indexterm><primary>paths.mk</primary></indexterm>
+ <listitem>
+ <para>defines <command>make</command> variables for
+ pathnames and file lists. This file contains code for
+ automatically compiling lists of source files and deriving
+ lists of object files from those. The results can be
+ overriden in the <filename>Makefile</filename>, but in
+ most cases the automatic setup should do the right
+ thing.</para>
+
+ <para>The following variables may be set in the
+ <filename>Makefile</filename> to affect how the automatic
+ source file search is done:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>ALL_DIRS</literal></term>
+ <indexterm><primary><literal>ALL_DIRS</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Set to a list of directories to search in
+ addition to the current directory for source
+ files.</para>
+ </listitem>
+ </varlistentry>
-<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>
+ <varlistentry>
+ <term><literal>EXCLUDE_SRCS</literal></term>
+ <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Set to a list of source files (relative to the
+ current directory) to omit from the automatic
+ search. The source searching machinery is clever
+ enough to know that if you exclude a source file
+ from which other sources are derived, then the
+ derived sources should also be excluded. For
+ example, if you set <literal>EXCLUDED_SRCS</literal>
+ to include <filename>Foo.y</filename>, then
+ <filename>Foo.hs</filename> will also be
+ excluded.</para>
+ </listitem>
+ </varlistentry>
-<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>
+ <varlistentry>
+ <term><literal>EXTRA_SRCS</literal></term>
+ <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Set to a list of extra source files (perhaps
+ in directories not listed in
+ <literal>ALL_DIRS</literal>) that should be
+ considered.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
-<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>The results of the automatic source file search are
+ placed in the following make variables:</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>
+ <variablelist>
+ <varlistentry>
+ <term><literal>SRCS</literal></term>
+ <indexterm><primary><literal>SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>All source files found, sorted and without
+ duplicates, including those which might not exist
+ yet but will be derived from other existing sources.
+ <literal>SRCS</literal> <emphasis>can</emphasis> be
+ overriden if necessary, in which case the variables
+ below will follow suit.</para>
+ </listitem>
+ </varlistentry>
-<para>
+ <varlistentry>
+ <term><literal>HS_SRCS</literal></term>
+ <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>all Haskell source files in the current
+ directory, including those derived from other source
+ files (eg. Happy sources also give rise to Haskell
+ sources).</para>
+ </listitem>
+ </varlistentry>
-<ItemizedList>
-<ListItem>
+ <varlistentry>
+ <term><literal>HS_OBJS</literal></term>
+ <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
+ <listitem>
+ <para>Object files derived from
+ <literal>HS_SRCS</literal>.</para>
+ </listitem>
+ </varlistentry>
-<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>
+ <varlistentry>
+ <term><literal>HS_IFACES</literal></term>
+ <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
+ <listitem>
+ <para>Interface files (<literal>.hi</literal> files)
+ derived from <literal>HS_SRCS</literal>.</para>
+ </listitem>
+ </varlistentry>
-<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:
+ <varlistentry>
+ <term><literal>C_SRCS</literal></term>
+ <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>All C source files found.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>C_OBJS</literal></term>
+ <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
+ <listitem>
+ <para>Object files derived from
+ <literal>C_SRCS</literal>.</para>
+ </listitem>
+ </varlistentry>
-<ProgramListing>
-%.$(way_)o : %.lhs
- $(HC) $(HC_OPTS) $< -o $@
-</ProgramListing>
+ <varlistentry>
+ <term><literal>SCRIPT_SRCS</literal></term>
+ <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>All script source files found
+ (<literal>.lprl</literal> files).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>SCRIPT_OBJS</literal></term>
+ <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
+ <listitem>
+ <para><quote>object</quote> files derived from
+ <literal>SCRIPT_SRCS</literal>
+ (<literal>.prl</literal> files).</para>
+ </listitem>
+ </varlistentry>
-Neat, eh?
-</para>
-</ListItem>
+ <varlistentry>
+ <term><literal>HSC_SRCS</literal></term>
+ <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>All <literal>hsc2hs</literal> source files
+ (<literal>.hsc</literal> files).</para>
+ </listitem>
+ </varlistentry>
-</ItemizedList>
+ <varlistentry>
+ <term><literal>HAPPY_SRCS</literal></term>
+ <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
+ <listitem>
+ <para>All <literal>happy</literal> source files
+ (<literal>.y</literal> or <literal>.hy</literal> files).</para>
+ </listitem>
+ </varlistentry>
-</para>
+ <varlistentry>
+ <term><literal>OBJS</literal></term>
+ <indexterm><primary>OBJS</primary></indexterm>
+ <listitem>
+ <para>the concatenation of
+ <literal>$(HS_OBJS)</literal>,
+ <literal>$(C_OBJS)</literal>, and
+ <literal>$(SCRIPT_OBJS)</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Any or all of these definitions can easily be
+ overriden by giving new definitions in your
+ <filename>Makefile</filename>.</para>
+
+ <para>What, exactly, does <filename>paths.mk</filename>
+ consider a <quote>source file</quote> to be? It's based
+ on the file's suffix (e.g. <filename>.hs</filename>,
+ <filename>.lhs</filename>, <filename>.c</filename>,
+ <filename>.hy</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></term>
+ <indexterm><primary>opts.mk</primary></indexterm>
+ <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></term>
+ <indexterm><primary>suffix.mk</primary></indexterm>
+ <listitem>
+ <para>defines standard pattern rules—see <Xref
+ LinkEnd="sec-suffix">.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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</title>
+ <indexterm><primary>Pattern rules</primary></indexterm>
+
+ <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>
-</Sect2>
+<ProgramListing>
+%.o : %.c
+ $(RM) $@
+ $(CC) $(CC_OPTS) -c $< -o $@
+</ProgramListing>
-<Sect2>
-<Title>When the canned rule isn't right</Title>
+ <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>
-Sometimes the canned rule just doesn't do the right thing. For
-example, in the <Literal>nofib</Literal> suite we want the link step to print out
-timing information. The thing to do here is <Emphasis>not</Emphasis> to define
-<Constant>HS_PROG</Constant> or <Constant>C_PROG</Constant>, and instead define a special purpose rule in
-your own <filename>Makefile</filename>. By using different variable names you will avoid
-the canned rules being included, and conflicting with yours.
-</para>
+<ProgramListing>
+CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
+</ProgramListing>
-</Sect2>
+ <para>The four variables from which
+ <constant>CC_OPTS</constant> is built have the following
+ meaning:</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>
-</Sect1>
+<ProgramListing>
+gmake libHS.a EXTRA_CC_OPTS="-v"
+</ProgramListing>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="sec-targets">
+ <title>The main <filename>mk/target.mk</filename> file</title>
+ <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
+ 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>
+
+ <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:</para>
+
+ <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>
-<Sect1 id="sec-booting-from-C">
-<Title>Booting/porting from C (<filename>.hc</filename>) files
+ <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>
+
+ </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>All of these rules are “double-colon” rules,
+ thus</para>
-<IndexTerm><Primary>building GHC from .hc files</Primary></IndexTerm>
-<IndexTerm><Primary>booting GHC from .hc files</Primary></IndexTerm>
-<IndexTerm><Primary>porting GHC</Primary></IndexTerm></Title>
+<ProgramListing>
+install :: $(HS_PROG)
+ ...how to install it...
+</ProgramListing>
-<para>
-This section is for people trying to get GHC going by using the supplied
-intermediate C (<filename>.hc</filename>) files. This would probably be
-because no binaries have been provided, or because the machine is not ``fully
-supported''.
-</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</title>
+ <indexterm><primary>recursion, in makefiles</primary></indexterm>
+ <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
+
+ <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</title>
+ <indexterm><primary>way management</primary></indexterm>
+
+ <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,
+ 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 <quote>normal way</quote> 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 <command>gmake</command></emphasis> (usually in
+ a recursive invocation of <command>gmake</command> by the
+ system). It is never set inside a
+ <filename>Makefile</filename>. So it is a global constant for
+ any one invocation of <command>gmake</command>. Two other
+ <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 <quote>normal
+ way</quote>. 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>
+
+ <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> in the
+ <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
+ <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:
-<para>
-The intermediate C files are normally made available together with a source
-release, please check the announce message for exact directions of where to
-find them. If we haven't made them available or you can't find them, please
-ask.
-</para>
+<ProgramListing>
+%.$(way_)o : %.lhs
+ $(HC) $(HC_OPTS) $< -o $@
+</ProgramListing>
-<para>
-Assuming you've got them, unpack them on top of a fresh source tree. This
-will place matching <filename>.hc</filename> files next to the corresponding
-Haskell source in the compiler subdirectory <filename>ghc</filename> and in
-the language package of hslibs (i.e., in <filename>hslibs/lang</filename>).
-Then follow the `normal' instructions in <Xref
-LinkEnd="sec-building-from-source"> for setting up a build tree.
-</para>
+ Neat, eh?</para>
+ </listitem>
+
+ <listitem>
+ <para>You can invoke <command>make</command> with a
+ particular <literal>way</literal> setting yourself, in order
+ to build files related to a particular
+ <literal>way</literal> in the current directory. eg.
+
+<screen>
+$ make way=p
+</screen>
+
+ will build files for the profiling way only in the current
+ directory. </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>When the canned rule isn't right</title>
+
+ <para>Sometimes the canned rule just doesn't do the right thing.
+ For example, in the <literal>nofib</literal> suite we want the
+ link step to print out timing information. The thing to do here
+ is <emphasis>not</emphasis> to define
+ <constant>HS_PROG</constant> or
+ <constant>C_PROG</constant>, and instead define a special
+ purpose rule in your own <filename>Makefile</filename>. By
+ using different variable names you will avoid the canned rules
+ being included, and conflicting with yours.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="building-docs">
+ <title>Building the documentation</title>
+
+ <sect2 id="pre-supposed-doc-tools">
+ <title>Tools for building the Documentation</title>
+
+ <para>The following additional tools are required if you want to
+ format the documentation that comes with the
+ <literal>fptools</literal> projects:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>DocBook</term>
+ <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
+ <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>Much of our documentation is written in SGML, using
+ the DocBook DTD. Instructions on installing and
+ configuring the DocBook tools are below.</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>
+
+ <varlistentry>
+ <term>Haddock</term>
+ <indexterm><primary>Haddock</primary>
+ </indexterm>
+ <listitem>
+ <para>Haddock is a Haskell documentation tool that we use
+ for automatically generating documentation from the
+ library source code. It is an <literal>fptools</literal>
+ project in itself. To build documentation for the
+ libraries (<literal>fptools/libraries</literal>) you
+ should check out and build Haddock in
+ <literal>fptools/haddock</literal>. Haddock requires GHC
+ to build.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Installing the DocBook tools</title>
+
+ <sect3>
+ <title>Installing the DocBook tools on Linux</title>
+
+ <para>If you're on a recent RedHat system (7.0+), you probably
+ have working DocBook tools already installed. The configure
+ script should detect your setup and you're away.</para>
+
+ <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
+ 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
+ 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
+ (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>
+ </sect3>
+
+ <sect3>
+ <title>Installing DocBook on FreeBSD</title>
+
+ <para>On FreeBSD systems, the easiest way to get DocBook up
+ and running is to install it from the ports tree or a
+ pre-compiled package (packages are available from your local
+ FreeBSD mirror site).</para>
+
+ <para>To use the ports tree, do this:
+<screen>
+ $ cd /usr/ports/textproc/docproj
+ $ make install
+</screen>
+ This installs the FreeBSD documentation project tools, which
+ includes everything needed to format the GHC
+ documentation.</para>
+ </sect3>
+
+ <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>
+ 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
+ they actually end up in
+ <Filename>\docbook\stylesheets\docbook</Filename>).</para>
+ </Sect3>
+
+
+ <sect3>
+ <title>Installing the DocBook tools from source</title>
+
+ <sect4>
+ <title>Jade</title>
+
+ <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
+ error:
+
+<screen>
+! LaTeX Error: Unknown option implicit=false' for package hyperref'.
+</screen>
+
+ your version of <Command>hyperref</Command> is out of date;
+ download it from CTAN
+ (<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
+ can abort at that point and proceed straight to
+ <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
+ and PDF output will not work). Copy
+ <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>
+ and install the contents in
+ <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>
+ (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>
+ </sect4>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the DocBook tools</title>
+
+ <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>
+ </sect2>
+
+ <sect2>
+ <title>Remaining problems</title>
+
+ <para>If you install from source, you'll get a pile of warnings
+ of the form
+
+<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>
+ </sect2>
+
+ <sect2>
+ <title>Building the documentation</title>
+
+ <para>To build documentation in a certain format, you can
+ say, for example,</para>
+
+<screen>
+$ make html
+</screen>
+
+ <para>to build HTML documentation below the current directory.
+ The available formats are: <literal>dvi</literal>,
+ <literal>ps</literal>, <literal>pdf</literal>,
+ <literal>html</literal>, and <literal>rtf</literal>. Note that
+ not all documentation can be built in all of these formats: HTML
+ documentation is generally supported everywhere, and DocBook
+ documentation might support the other formats (depending on what
+ other tools you have installed).</para>
+
+ <para>All of these targets are recursive; that is, saying
+ <literal>make html</literal> will make HTML docs for all the
+ documents recursively below the current directory.</para>
+
+ <para>Because there are many different formats that the DocBook
+ documentation can be generated in, you have to select which ones
+ you want by setting the <literal>SGMLDocWays</literal> variable
+ to a list of them. For example, in
+ <filename>build.mk</filename> you might have a line:</para>
+
+<screen>
+SGMLDocWays = html ps
+</screen>
+
+ <para>This will cause the documentation to be built in the requested
+ formats as part of the main build (the default is not to build
+ any documentation at all).</para>
+ </sect2>
+
+ <sect2>
+ <title>Installing the documentation</title>
+
+ <para>To install the documentation, use:</para>
+
+<screen>
+$ make install-docs
+</screen>
+
+ <para>This will install the documentation into
+ <literal>$(datadir)</literal> (which defaults to
+ <literal>$(prefix)/share</literal>). The exception is HTML
+ documentation, which goes into
+ <literal>$(datadir)/html</literal>, to keep things tidy.</para>
+
+ <para>Note that unless you set <literal>$(SGMLDocWays)</literal>
+ to a list of formats, the <literal>install-docs</literal> target
+ won't do anything for SGML documentation.</para>
+ </sect2>
+
+ </sect1>
+
+
+ <sect1 id="sec-porting-ghc">
+ <title>Porting GHC</title>
+
+ <para>This section describes how to port GHC to a currenly
+ unsupported platform. There are two distinct
+ possibilities:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The hardware architecture for your system is already
+ supported by GHC, but you're running an OS that isn't
+ supported (or perhaps has been supported in the past, but
+ currently isn't). This is the easiest type of porting job,
+ but it still requires some careful bootstrapping. Proceed to
+ <xref linkend="sec-booting-from-hc">.</para>
+ </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>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 id="sec-booting-from-hc">
+ <title>Booting/porting from C (<filename>.hc</filename>) files</title>
+
+ <indexterm><primary>building GHC from .hc files</primary></indexterm>
+ <indexterm><primary>booting GHC from .hc files</primary></indexterm>
+ <indexterm><primary>porting GHC</primary></indexterm>
+
+ <para>Bootstrapping GHC on a system without GHC already
+ installed is achieved by taking the intermediate C files (known
+ as HC files) from a GHC compilation on a supported system to the
+ target machine, and compiling them using gcc to get a working
+ GHC.</para>
+
+ <para><emphasis>NOTE: GHC versions 5.xx and later are
+ significantly harder to bootstrap from C than earlier versions.
+ We recommend starting from version 4.08.2 if you need to
+ bootstrap in this way.</emphasis></para>
+
+ <para>HC files are architecture-dependent (but not
+ OS-dependent), so you have to get a set that were generated on
+ similar hardware. There may be some supplied on the GHC
+ download page, otherwise you'll have to compile some up
+ yourself, or start from <emphasis>unregisterised</emphasis> HC
+ files - see <xref linkend="unregisterised-porting">.</para>
+
+ <para>The following steps should result in a working GHC build
+ with full libraries:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Unpack the HC files on top of a fresh source tree
+ (make sure the source tree version matches the version of
+ the HC files <emphasis>exactly</emphasis>!). This will
+ place matching <filename>.hc</filename> files next to the
+ corresponding Haskell source (<filename>.hs</filename> or
+ <filename>.lhs</filename>) in the compiler subdirectory
+ <filename>ghc/compiler</filename> and in the libraries
+ (subdirectories of <filename>hslibs</filename> and
+ <literal>libraries</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>The actual build process is fully automated by the
+ <filename>hc-build</filename> script located in the
+ <filename>distrib</filename> directory. If you eventually
+ want to install GHC into the directory
+ <replaceable>dir</replaceable>, the following
+ command will execute the whole build process (it won't
+ install yet):</para>
-<para>
-The actual build process is fully automated by the
-<filename>hc-build</filename> script located in the
-<filename>distrib</filename> directory. If you eventually want to install GHC
-into the directory <filename>INSTALL_DIRECTORY</filename>, the following
-command will execute the whole build process (it won't install yet):
-</para>
<Screen>
-foo% distrib/hc-build --prefix=INSTALL_DIRECTORY
+foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
</Screen>
-<IndexTerm><Primary>--hc-build</Primary></IndexTerm>
-<para>
-By default, the installation directory is <filename>/usr/local</filename>. If
-that is what you want, you may omit the argument to
-<filename>hc-build</filename>. Generally, any option given to
-<filename>hc-build</filename> is passed through to the configuration script
-<filename>configure</filename>. If <filename>hc-build</filename>
-successfully completes the build process, you can install the resulting
-system, as normal, with
-</para>
+<indexterm><primary>--hc-build</primary></indexterm>
+
+ <para>By default, the installation directory is
+ <filename>/usr/local</filename>. If that is what you want,
+ you may omit the argument to <filename>hc-build</filename>.
+ Generally, any option given to <filename>hc-build</filename>
+ is passed through to the configuration script
+ <filename>configure</filename>. If
+ <filename>hc-build</filename> successfully completes the
+ build process, you can install the resulting system, as
+ normal, with</para>
+
<Screen>
foo% make install
</Screen>
-
-<para>
-That's the mechanics of the boot process, but, of course, if you're
-trying to boot on a platform that is not supported and significantly
-`different' from any of the supported ones, this is only the start of
-the adventure…(ToDo: porting tips—stuff to look out for, etc.)
-</para>
-
-</Sect1>
-
-<Sect1 id="sec-build-pitfalls">
-<Title>Known pitfalls in building Glasgow Haskell
-
-<IndexTerm><Primary>problems, building</Primary></IndexTerm>
-<IndexTerm><Primary>pitfalls, in building</Primary></IndexTerm>
-<IndexTerm><Primary>building pitfalls</Primary></IndexTerm></Title>
-
-<para>
-WARNINGS about pitfalls and known ``problems'':
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="unregisterised-porting">
+ <title>Porting GHC to a new architecture</title>
+
+ <para>The first step in porting to a new architecture is to get
+ an <firstterm>unregisterised</firstterm> build working. An
+ unregisterised build is one that compiles via vanilla C only.
+ By contrast, a registerised build uses the following
+ architecture-specific hacks for speed:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Global register variables: certain abstract machine
+ <quote>registers</quote> are mapped to real machine
+ registers, depending on how many machine registers are
+ available (see
+ <filename>ghc/includes/MachRegs.h</filename>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Assembly-mangling: when compiling via C, we feed the
+ assembly generated by gcc though a Perl script known as the
+ <firstterm>mangler</firstterm> (see
+ <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
+ mangler rearranges the assembly to support tail-calls and
+ various other optimisations.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In an unregisterised build, neither of these hacks are
+ used — the idea is that the C code generated by the
+ compiler should compile using gcc only. The lack of these
+ optimisations costs about a factor of two in performance, but
+ since unregisterised compilation is usually just a step on the
+ way to a full registerised port, we don't mind too much.</para>
+
+ <sect3>
+ <title>Building an unregisterised port</title>
+
+ <para>The first step is to get some unregisterised HC files.
+ Either (a) download them from the GHC site (if there are
+ some available for the right version of GHC), or
+ (b) build them yourself on any machine with a working
+ GHC. If at all possible this should be a machine with the
+ same word size as the target.</para>
+
+ <para>There is a script available which should automate the
+ process of doing the 2-stage bootstrap necessary to get the
+ unregisterised HC files - it's available in <ulink
+ url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
+ in CVS.</para>
+
+ <para>Now take these unregisterised HC files to the target
+ platform and bootstrap a compiler from them as per the
+ instructions in <xref linkend="sec-booting-from-hc">. In
+ <filename>build.mk</filename>, you need to tell the build
+ system that the compiler you're building is
+ (a) unregisterised itself, and (b) builds
+ unregisterised binaries. This varies depending on the GHC
+ version you're bootstraping:</para>
+
+<programlisting>
+# build.mk for GHC 4.08.x
+GhcWithRegisterised=NO
+</programlisting>
+
+<programlisting>
+# build.mk for GHC 5.xx and 6.x
+GhcUnregisterised=YES
+</programlisting>
+
+ <para>Versions 5.xx and 6.x only: use the option
+ <option>--enable-hc-boot-unregisterised</option> instead of
+ <option>--enable-hc-boot</option> when running
+ <filename>./configure</filename>.</para>
+
+ <para>The build may not go through cleanly. We've tried to
+ stick to writing portable code in most parts of the compiler,
+ so it should compile on any POSIXish system with gcc, but in
+ our experience most systems differ from the standards in one
+ way or another. Deal with any problems as they arise - if you
+ get stuck, ask the experts on
+ <email>glasgow-haskell-users@haskell.org</email>.</para>
+
+ <para>Once you have the unregisterised compiler up and
+ running, you can use it to start a registerised port. The
+ following sections describe the various parts of the system
+ that will need architecture-specific tweaks in order to get a
+ registerised build going.</para>
+
+ <para>Lots of useful information about the innards of GHC is
+ available in the <ulink
+ url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+ Commentary</ulink>, which might be helpful if you run into
+ some code which needs tweaking for your system.</para>
+ </sect3>
+
+ <sect3>
+ <title>Porting the RTS</title>
+
+ <para>The following files need architecture-specific code for a
+ registerised build:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><filename>ghc/includes/MachRegs.h</filename></term>
+ <indexterm><primary><filename>MachRegs.h</filename></primary>
+ </indexterm>
+ <listitem>
+ <para>Defines the STG-register to machine-register
+ mapping. You need to know your platform's C calling
+ convention, and which registers are generally available
+ for mapping to global register variables. There are
+ plenty of useful comments in this file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>ghc/includes/TailCalls.h</filename></term>
+ <indexterm><primary><filename>TailCalls.h</filename></primary>
+ </indexterm>
+ <listitem>
+ <para>Macros that cooperate with the mangler (see <xref
+ 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>
+ <listitem>
+ <para>Support for
+ <literal>foreign import "wrapper"</literal>
+ (aka
+ <literal>foreign export dynamic</literal>).
+ Not essential for getting GHC bootstrapped, so this file
+ can be deferred until later if necessary.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>ghc/rts/StgCRun.c</filename></term>
+ <indexterm><primary><filename>StgCRun.c</filename></primary>
+ </indexterm>
+ <listitem>
+ <para>The little assembly layer between the C world and
+ the Haskell world. See the comments and code for the
+ other architectures in this file for pointers.</para>
+ </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>
+ <listitem>
+ <para>These files are really OS-specific rather than
+ architecture-specific. In <filename>MBlock.h</filename>
+ is specified the absolute location at which the RTS
+ should try to allocate memory on your platform (try to
+ find an area which doesn't conflict with code or dynamic
+ libraries). In <filename>Mblock.c</filename> you might
+ need to tweak the call to <literal>mmap()</literal> for
+ your OS.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
+ <sect3 id="sec-mangler">
+ <title>The mangler</title>
+
+ <para>The mangler is an evil Perl-script that rearranges the
+ assembly code output from gcc to do two main things:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Remove function prologues and epilogues, and all
+ movement of the C stack pointer. This is to support
+ tail-calls: every code block in Haskell code ends in an
+ explicit jump, so we don't want the C-stack overflowing
+ while we're jumping around between code blocks.</para>
+ </listitem>
+ <listitem>
+ <para>Move the <firstterm>info table</firstterm> for a
+ closure next to the entry code for that closure. In
+ unregisterised code, info tables contain a pointer to the
+ entry code, but in registerised compilation we arrange
+ that the info table is shoved right up against the entry
+ code, and addressed backwards from the entry code pointer
+ (this saves a word in the info table and an extra
+ indirection when jumping to the closure entry
+ code).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The mangler is abstracted to a certain extent over some
+ architecture-specific things such as the particular assembler
+ directives used to herald symbols. Take a look at the
+ definitions for other architectures and use these as a
+ starting point.</para>
+ </sect3>
+
+ <sect3>
+ <title>The native code generator</title>
+
+ <para>The native code generator isn't essential to getting a
+ registerised build going, but it's a desirable thing to have
+ because it can cut compilation times in half. The native code
+ generator is described in some detail in the <ulink
+ url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+ commentary</ulink>.</para>
+ </sect3>
+
+ <sect3>
+ <title>GHCi</title>
+
+ <para>To support GHCi, you need to port the dynamic linker
+ (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
+ currently supports the ELF and PEi386 object file formats - if
+ your platform uses one of these then you probably don't have
+ to do anything except fiddle with the
+ <literal>#ifdef</literal>s at the top of
+ <filename>Linker.c</filename> to tell it about your OS.</para>
+
+ <para>If your system uses a different object file format, then
+ you have to write a linker — good luck!</para>
+ </sect3>
+ </sect2>
+
+ </sect1>
+
+<sect1 id="sec-build-pitfalls">
+<title>Known pitfalls in building Glasgow Haskell
+
+<indexterm><primary>problems, building</primary></indexterm>
+<indexterm><primary>pitfalls, in building</primary></indexterm>
+<indexterm><primary>building pitfalls</primary></indexterm></title>
+
+<para>
+WARNINGS about pitfalls and known “problems”:
</para>
<para>
<OrderedList>
-<ListItem>
+<listitem>
<para>
One difficulty that comes up from time to time is running out of space
in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
compensate for the vagaries of different sysadmin approaches to temp
space.)
-<IndexTerm><Primary>tmp, running out of space in</Primary></IndexTerm>
+<indexterm><primary>tmp, running out of space in</primary></indexterm>
-The quickest way around it is <Command>setenv TMPDIR /usr/tmp</Command><IndexTerm><Primary>TMPDIR</Primary></IndexTerm> or
-even <Command>setenv TMPDIR .</Command> (or the equivalent incantation with your shell
+The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
+even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
of choice).
The best way around it is to say
</ProgramListing>
in your <filename>build.mk</filename> file.
-Then GHC and the other <Literal>fptools</Literal> programs will use the appropriate directory
+Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
in all cases.
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
are OK.
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
-When compiling via C, you'll sometimes get ``warning: assignment from
-incompatible pointer type'' out of GCC. Harmless.
+When compiling via C, you'll sometimes get “warning: assignment from
+incompatible pointer type” out of GCC. Harmless.
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
-Similarly, <Command>ar</Command>chiving warning messages like the following are not
+Similarly, <command>ar</command>chiving warning messages like the following are not
a problem:
<Screen>
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
- In compiling the compiler proper (in <filename>compiler/</filename>), you <Emphasis>may</Emphasis>
-get an ``Out of heap space'' error message. These can vary with the
+ In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
+get an “Out of heap space” error message. These can vary with the
vagaries of different systems, it seems. The solution is simple:
-<ItemizedList>
-<ListItem>
+<itemizedlist>
+<listitem>
<para>
If you're compiling with GHC 4.00 or later, then the
-<Emphasis>maximum</Emphasis> heap size must have been reached. This
+<emphasis>maximum</emphasis> heap size must have been reached. This
is somewhat unlikely, since the maximum is set to 64M by default.
Anyway, you can raise it with the
-<Option>-optCrts-M<size></Option> flag (add this flag to
-<Constant><module>_HC_OPTS</Constant>
-<Command>make</Command> variable in the appropriate
+<option>-optCrts-M<size></option> flag (add this flag to
+<constant><module>_HC_OPTS</constant>
+<command>make</command> variable in the appropriate
<filename>Makefile</filename>).
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
- For GHC < 4.00, add a suitable <Option>-H</Option> flag to the <filename>Makefile</filename>, as
+ For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
above.
</para>
-</ListItem>
+</listitem>
-</ItemizedList>
+</itemizedlist>
-and try again: <Command>gmake</Command>. (see <Xref LinkEnd="sec-suffix"> for information about
-<Constant><module>_HC_OPTS</Constant>.)
+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:
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
If you try to compile some Haskell, and you get errors from GCC about
lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
-mis-installed. <Command>fixincludes</Command> wasn't run when it should've been.
+mis-installed. <command>fixincludes</command> wasn't run when it should've been.
-As <Command>fixincludes</Command> is now automagically run as part of GCC installation,
+As <command>fixincludes</command> is now automagically run as part of GCC installation,
this bug also suggests that you have an old GCC.
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
-You <Emphasis>may</Emphasis> need to re-<Command>ranlib</Command><IndexTerm><Primary>ranlib</Primary></IndexTerm> your libraries (on Sun4s).
+You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
<Screen>
</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
<para>
-GHC's sources go through <Command>cpp</Command> before being compiled, and <Command>cpp</Command> varies
+GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
a bit from one Unix to another. One particular gotcha is macro calls
like this:
</ProgramListing>
-Some <Command>cpp</Command>s treat the comma inside the string as separating two macro
+Some <command>cpp</command>s treat the comma inside the string as separating two macro
arguments, so you get
</Screen>
-Alas, <Command>cpp</Command> doesn't tell you the offending file!
+Alas, <command>cpp</command> doesn't tell you the offending file!
-Workaround: don't put weird things in string args to <Command>cpp</Command> macros.
+Workaround: don't put weird things in string args to <command>cpp</command> macros.
</para>
-</ListItem>
+</listitem>
</OrderedList>
</para>
-</Sect1>
+</sect1>
<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
guide) before continuing to read these notes.
</para>
-<para>
-Before you start, make sure you've installed the Cygwin packages
-<filename>openssh</filename>, <filename>openssl</filename>,
-<filename>cvs</filename>, <filename>gdbm</filename> (needed by cvs), <filename>m4</filename> and
-<filename>autoconf</filename>. Do not install the <filename>cygwin</filename>
-package; the bits of it you need are supplied with GHC. You also need to make sure that the
-user environment variable <Constant>MAKE_MODE</Constant> is set to <Literal>UNIX</Literal>. If you don't do
-this you get very weird messages when you type <Command>make</Command>, such as:
-</para><Screen>
-/c: /c: No such file or directory</Screen>
-
-<Sect2><Title>Configuring ssh</Title>
-<ItemizedList>
+<sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
-<ListItem>
-<para>
-Generate a key, by running <filename>c:/user/local/bin/ssh-keygen1</filename>.
- This generates a public key in <filename>.ssh/identity.pub</filename>, and a
- private key in <filename>.ssh/identity</filename>
-</para>
+<para> The Windows situation for building GHC is rather confusing. This section
+tries to clarify, and to establish terminology.</para>
+
+<sect3 id="ghc-mingw"><title>GHC-mingw</title>
+
+<para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
+is a collection of header
+files and import libraries that allow one to use <command>gcc</command> and produce
+native Win32 programs that do not rely on any third-party DLLs. The
+current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
+Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
+other utilities.
+</para>
+<para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
+<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
+GHC compiles Haskell to C (or to
+assembly code), and then invokes these MinGW tools to generate an executable binary.
+The resulting binaries can run on any Win32 system.
+</para>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+
+<para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
+Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
+library; they have to do
+their input output using standard Haskell I/O libraries, or native Win32 bindings.
+</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
+
+<para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
+<ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
+Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
+<command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
+A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
+</para>
+<para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
+Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
+A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
+If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
+that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
+Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
+does not change, but the implementation certainly does. Even the interfaces to functions
+it exports seem to change occasionally. So programs compiled by GHC might only run with
+particular versions of Cygwin. All of this seems very undesirable.
+</para>
+<para>
+Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
+we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+</para>
+</sect3>
+
+<sect3><title>HOST_OS vs TARGET_OS</title>
+
+<para>
+In the source code you'll find various ifdefs looking like:
+<programlisting>
+ #ifdef mingw32_HOST_OS
+ ...blah blah...
+ #endif
+</programlisting>
+and
+<programlisting>
+ #ifdef mingw32_TARGET_OS
+ ...blah blah...
+ #endif
+</programlisting>
+These macros are set by the configure script (via the file config.h).
+Which is which? The criterion is this. In the ifdefs in GHC's source code:
+<itemizedlist>
+ <listitem> <para>
+ The "host" system is the one on which GHC itself will be run.
+ </para> </listitem>
+ <listitem> <para>
+ The "target" system is the one for which the program compiled by GHC will be run.
+ </para> </listitem>
+</itemizedlist>
+For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
+So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+
+</para>
+</sect3>
+
+<sect3><title>Summary</title>
+
+<para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
+how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
+by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
+
+<para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
+GHC-cygwin too is beyond our resources. The GHC we distribute
+therefore does not require Cygwin to run, nor do the programs it
+compiles require Cygwin.</para>
+
+<para>The instructions that follow describe how to build GHC-mingw. It is
+possible to build GHC-cygwin, but it's not a supported route, and the build system might
+be flaky.</para>
+
+<para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>. It
+uses the <Command>gcc</Command> that you specify using the
+<option>--with-gcc</option> flag when you run
+<Command>configure</Command> (see below).
+The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
+to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
+whatever one happens to be in your path. However, the makefiles do use whatever <Command>ld</Command>
+and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
+used to glom together .o files into a bigger .o file, or a .a file,
+so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
+Cygwin and Mingw use the same .o file format. So its ok.
+</para>
+</sect3>
+</sect2>
-<para>
- In response to the 'Enter passphrase' question, just hit
- return (i.e. use an empty passphrase). The passphrase is
- a password that protects your private key. But it's a pain
- to type this passphrase everytime you use <Command>ssh</Command>, so the best
- thing to do is simply to protect your <filename>.ssh</filename> directory, and
- <filename>.ssh/identity</filename> from access by anyone else. To do this
- right-click your <filename>.ssh</filename> directory, and select Properties.
- If you are not on the access control list, add yourself, and
- give yourself full permissions (the second panel).
- Remove everyone else from the access control list. (Don't
- leave them there but deny them access, because 'they' may be
- a list that includes you!)
-</para>
+<Sect2><Title>Installing and configuring Cygwin</Title>
-<para>
- If you have problems running <Command>ssh-keygen1</Command>
- from within <Command>bash</Command>, start up <filename>cmd.exe</filename> and run it as follows:
-</para>
+<para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
+but you do need it to <emphasis>build</emphasis> GHC.</para>
-<Screen>
-c:\tmp> set CYGWIN32=tty
-c:\tmp> c:/user/local/bin/ssh-keygen1
-</Screen>
-</ListItem>
+<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
+The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
+During the installation dialogue, make sure that you select:
+<command>cvs</command>, <command>openssh</command>,
+<command>autoconf</command>,
+<command>binutils</command> (includes ld and (I think) ar),
+<command>gcc</command>,
+<command>flex</command>,
+<command>make</command>.
-<ListItem>
-<para>
-If you don't have an account on <Literal>cvs.haskell.org</Literal>, send
- your <filename>.ssh/identity.pub</filename> to the CVS repository administrator
- (currently Jeff Lewis <Email>jlewis@cse.ogi.edu</Email>). He will set up
- your account.
</para>
+<para> Now set the following user environment variables:
+<itemizedlist>
+
+<listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
+<constant>PATH</constant></para></listitem>
+<listitem>
<para>
- If you do have an account on <Literal>cvs.haskell.org</Literal>, use TeraTerm
- to logon to it. Once in, copy the
- key that <Command>ssh-keygen1</Command> deposited in <filename>/.ssh/identity.pub</filename> into
- your <filename>~/.ssh/authorized_keys</filename>. Make sure that the new version
- of <filename>authorized_keys</filename> still has 600 file permission.
+Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
+don't do this you get very weird messages when you type
+<Command>make</Command>, such as:
+<Screen>
+/c: /c: No such file or directory
+</Screen>
</para>
-</ListItem>
-
-</ItemizedList>
-
-</Sect2>
-
-
-<Sect2><Title>Configuring CVS</Title>
+</listitem>
-<ItemizedList>
+<listitem><para> Set <constant>SHELL</constant> to
+<Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
+<constant>SHELL</constant> is what you get.
+</para></listitem>
-<ListItem>
-<para>
-From the System control panel,
-set the following <Emphasis>user</Emphasis> environment variables (see the GHC user guide)
+<listitem><para> Set <constant>HOME</constant> to point to your
+home directory. This is where, for example,
+<command>bash</command> will look for your <filename>.bashrc</filename>
+file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
+</para></listitem>
+</itemizedlist>
</para>
-<ItemizedList>
-<ListItem>
<para>
-<Constant>HOME</Constant>: points to your home directory. This is where CVS
-will look for its <filename>.cvsrc</filename> file.
-</para>
-</ListItem>
-
-<ListItem>
+There are a few other things to do:
+<itemizedlist>
+<listitem>
<para>
-<Constant>CVS_RSH</Constant>: <filename>c:/path_to_Cygwin/bin/ssh</filename>
+By default, cygwin provides the command shell <filename>ash</filename>
+as <filename>sh.exe</filename>. We have often seen build-system problems that
+turn out to be due to bugs in <filename>ash</filename>
+(to do with quoting
+and length of command lines). On the other hand <filename>bash</filename> seems
+to be rock solid.
+So, in <filename>cygwin/bin</filename>
+remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
+and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
+You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
+you can't rename a running program!
</para>
-</ListItem>
+</listitem>
-<ListItem>
+<listitem>
<para>
-<Constant>CVSROOT</Constant>: <Literal>:ext:username@cvs.haskell.org:/home/cvs/root</Literal>,
-where <Literal>username</Literal> is your userid
+Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
+(and similarly for <Command>sh</Command>). Notice the hardwired path!
+So you need to ensure that your <Filename>/bin</Filename> directory has the following
+binaries in it:
+<itemizedlist>
+<listitem> <para><Command>sh</Command></para></listitem>
+<listitem> <para><Command>perl</Command></para></listitem>
+<listitem> <para><Command>cat</Command></para></listitem>
+</itemizedlist>
+All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
+installed as <Filename>c:/cygwin/bin</Filename>. By default Cygwin mounts "<Filename>/</Filename>" as
+<Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
+(You can discover where your Cygwin
+root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
+Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
+directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
+directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
</para>
-</ListItem>
-
-<ListItem>
-<para>
-<Constant>CVSEDITOR</Constant>: <filename>bin/gnuclient.exe</filename> if you want to use an Emacs buffer for typing in those long commit messages.
+</listitem>
+</itemizedlist>
+</para>
+
+<para>Finally, here are some things to be aware of when using Cygwin:
+<itemizedlist>
+<listitem> <para>Cygwin doesn't deal well with filenames that include
+spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
+common gotchas.
+</para></listitem>
+
+<listitem> <para> Cygwin implements a symbolic link as a text file with some
+magical text in it. So other programs that don't use Cygwin's
+I/O libraries won't recognise such files as symlinks.
+In particular, programs compiled by GHC are meant to be runnable
+without having Cygwin, so they don't use the Cygwin library, so
+they don't recognise symlinks.
+</para></listitem>
+
+<listitem> <para>
+Win32 has a <command>find</command> command which is not the same as Cygwin's find.
+You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
+before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
+environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
+variable. You can always invoke <command>find</command> with an absolute path, or rename it.
+</para></listitem>
+</itemizedlist>
</para>
-</ListItem>
-</ItemizedList>
-</ListItem>
-<ListItem>
-<para>
-Put the following in <filename>$HOME/.cvsrc</filename>:
-</para>
+</Sect2>
-<ProgramListing>
-checkout -P
-release -d
-update -P
-diff -u
-</ProgramListing>
+<Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
-<para>
-These are the default options for the specified CVS commands,
-and represent better defaults than the usual ones. (Feel
-free to change them.)
-</para>
+<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
+you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
+(not ssh) in the Cygwin list of applications!</para>
+<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
+<itemizedlist>
+<listitem>
<para>
-Filenames starting with <filename>.</filename> were illegal in
-the 8.3 DOS filesystem, but that restriction should have
-been lifted by now (i.e., you're using VFAT or later filesystems.) If
-you're still having problems creating it, don't worry; <filename>.cvsrc</filename> is entirely
-optional.
+ The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
+ seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
+ they ask for a password). To solve this, start up <filename>cmd.exe</filename>
+ and run it as follows:
+ <Screen>
+ c:\tmp> set CYGWIN32=tty
+ c:\tmp> c:/user/local/bin/ssh-keygen1
+ </Screen> </para>
+</listitem>
+
+<listitem><para>
+<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
+To determine your home directory <command>ssh</command> first looks in
+<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
+there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
+the setting of the environment variable $HOME</emphasis>. If the home directory is
+bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
+<programlisting>
+ ssh -v cvs.haskell.org
+</programlisting>
+which makes <command>ssh</command> print out information about its activity.
+</para>
+<para> You can fix this problem, either by correcting the home-directory field in
+<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
+you do that, <command>ssh</command> uses the $HOME environment variable instead.
</para>
-</ListItem>
-<ListItem>
-<para>
-Try doing <Command>cvs co fpconfig</Command>. All being well, bytes should
-start to trickle through, leaving a directory <filename>fptools</filename>
-in your current directory. (You can <Command>rm</Command> it if you don't want to keep it.) The following messages appear to be harmless:
+</listitem>
+
+<listitem>
+ <para>To protect your
+ <literal>.ssh</literal> from access by anyone else,
+ right-click your <literal>.ssh</literal> directory, and
+ select <literal>Properties</literal>. If you are not on
+ the access control list, add yourself, and give yourself
+ full permissions (the second panel). Remove everyone else
+ from the access control list. Don't leave them there but
+ deny them access, because 'they' may be a list that
+ includes you!</para>
+</listitem>
+
+<listitem>
+ <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
+ you to have Unix permissions 600 (read/write for owner only)
+ on the <literal>.ssh/identity</literal> file, else it
+ bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
+ but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
+ The solution seems to be to set the $CYGWIN environment
+ variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
+ in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
+ and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
+ </para>
+</listitem>
+</itemizedlist>
</para>
+</sect2>
-<Screen>
-setsockopt IPTOS_LOWDELAY: Invalid argument
-setsockopt IPTOS_THROUGHPUT: Invalid argument
-</Screen>
+<Sect2><Title>Other things you need to install</Title>
+<para>You have to install the following other things to build GHC:
+<itemizedlist>
+<listitem>
<para>
-At this point I found that CVS tried to invoke a little dialogue with
-me (along the lines of `do you want to talk to this host'), but
-somehow bombed out. This was from a bash shell running in emacs.
-I solved this by invoking a Cygnus shell, and running CVS from there.
-Once things are dialogue free, it seems to work OK from within emacs.
+Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
+This is what you will use to compile GHC. Add it in your
+<constant>PATH</constant>: the installer tells you the path element
+you need to add upon completion.
</para>
-</ListItem>
+</listitem>
-<ListItem>
+<listitem>
<para>
-If you want to check out part of large tree, proceed as follows:
+Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
+Happy is a parser generator used to compile the Haskell grammar. Add it in your
+<constant>PATH</constant>.
</para>
+</listitem>
-<ProgramListing>
-cvs -f checkout -l papers
-cd papers
-cvs update cpr
-</ProgramListing>
-<para>
-This sequence checks out the <Literal>papers</Literal> module, but none
-of its sub-directories.
-The "<Option>-l</Option>" flag says not to check out sub-directories.
-The "<Option>-f</Option>" flag says not to read the <filename>.cvsrc</filename> file
-whose <Option>-P</Option> default (don't check out empty directories) is
-in this case bogus.
+<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">).
+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>
-The <Command>cvs update</Command> command sucks in a named sub-directory.
+<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
+you are likely to get into a mess because their names overlap with Cygwin binaries.
</para>
-</ListItem>
+</listitem>
-</ItemizedList>
-<para>
-There is a very nice graphical front-end to CVS for Win32 platforms,
-with a UI that people will be familiar with, at
-<ULink URL="http://www.wincvs.org/">wincvs.org</ULink>.
-I have not tried it yet.
+<listitem>
+<para>We use <command>emacs</command> a lot, so we install that too.
+When you are in <filename>fptools/ghc/compiler</filename>, you can use
+"<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
+<filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
+The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
+The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
+so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
</para>
+</listitem>
-</Sect2>
+<listitem>
+<para> Finally, check out a copy of GHC sources from
+the CVS repository, following the instructions above (<xref linkend="cvs-access">).
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</sect2>
<Sect2><Title>Building GHC</Title>
+<para>OK!
+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>
-
-<ListItem>
-<para>
-In the <filename>./configure</filename> output, ignore
-"<Literal>
-checking whether #! works in shell scripts...
-./configure: ./conftest: No such file or directory</Literal>",
-and "<Literal>not updating unwritable cache ./config.cache</Literal>".
-Nobody knows why these happen, but they seem to be harmless.
-</para>
-</ListItem>
-
-<ListItem>
+<listitem>
<para>
-You have to run <Command>autoconf</Command> both in <filename>fptools</filename>
+Run <Command>autoconf</Command> both in <filename>fptools</filename>
and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
get an error when you run <filename>./configure</filename>:
-</para>
-
<Screen>
...lots of stuff...
creating mk/config.h
./configure: ./configure: No such file or directory
configure: error: ./configure failed for ghc
</Screen>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
+<listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
+read-only. So if you need to run autoconf again (which I sometimes do for safety's sake),
+you get
+<screen>
+/usr/bin/autoconf: cannot create configure: permission denied
+</screen>
+Solution: delete <filename>configure</filename> first.
+</para></listitem>
+
+<listitem>
<para>
-You need <filename>ghc</filename> to be in your <Constant>PATH</Constant> before you run
-<Command>configure</Command>. The default GHC InstallShield creates only
-<filename>ghc-4.08</filename>, so you may need to duplicate this file as <filename>ghc</filename>
-in the same directory, in order that <Command>configure</Command> will see it (or
-just rename <filename>ghc-4.08</filename> to <filename>ghc</filename>.
-And make sure that the directory is in your path.
+You either need to add <filename>ghc</filename> to your
+<constant>PATH</constant> before you invoke
+<Command>configure</Command>, or use the <Command>configure</Command>
+option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
</para>
-</ListItem>
+</listitem>
-</ItemizedList>
+<listitem><para>
+If you are paranoid, delete <filename>config.cache</filename> if it exists.
+This file occasionally remembers out-of-date configuration information, which
+can be really confusing.
+</para>
+</listitem>
+
+<listitem>
+ <para>
+ After <command>autoconf</command> run <command>./configure</command> in
+ <filename>fptools/</filename> thus:
+
+<Screen>
+ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
+</Screen>
+This is the point at which you specify that you are building GHC-mingw
+(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>
+<para>
+Furthermore, it's <emphasis>very important</emphasis> that you specify a
+full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
+uses this path to invoke <command>gcc</command>) is a MinGW program and won't
+understand a Cygwin path. For example, if you
+say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
+<filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
+time it tries to invoke it. Worse, the failure comes with
+no error message whatsoever. GHC simply fails silently when first invoked,
+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-Wmissing-declarations -optc-Winline -optc-Waggregate-return
+ -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
+ -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
+ -optc-fomit-frame-pointer -O2 -static
+ -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
+make[2]: *** [Adjustor.o] Error 1
+make[1]: *** [all] Error 1
+make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make: *** [all] Error 1
+</programlisting>
+Be warned!
+</para>
+
+<para>
+If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
+you'll have to do something more like:
+<Screen>
+ ./configure --with-gcc=...the Cygwin gcc...
+</Screen>
+</para>
+</listitem>
+
+<listitem><para> You almost certainly want to set
+<programlisting>
+ SplitObjs = NO
+</programlisting>
+in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
+This tells the build system not to split each library into a myriad of little object files, one
+for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
+it dramatically increases the time taken to build the libraries in the first place.
+</para>
+</listitem>
+<listitem><para> Do not attempt to build the documentation.
+It needs all kinds of wierd Jade stuff that we haven't worked out for
+Win32.</para></listitem>
+</ItemizedList>
</Sect2>
-</Sect1>
+
+</sect1>
</Article>
projects / ghc-hetmet.git / blobdiff