+++ /dev/null
-<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-
-<Article id="building-guide">
-
-<ArtHeader>
-
-<Title>Building the Glasgow Functional Programming Tools Suite</Title>
-<Author><OtherName>The GHC Team</OtherName></Author>
-<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
-<PubDate>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>flex</Command><IndexTerm><Primary>flex</Primary></IndexTerm> you'll find it convenient that the source
-distribution contains the result of running <Command>flex</Command> on the lexical
-analyser specification. If you don't want to alter the lexical
-analyser then this saves you having to find and install <Command>flex</Command>. You
-will still need a working version of GHC on your machine in order to
-compile (most of) the sources, however.
-</Para>
-
-<Para>
-We make source distributions more frequently than binary
-distributions; a release that comes with pre-compiled binaries
-is considered a major release, i.e., a release that we have some
-confidence will work well by having tested it (more) thoroughly.
-</Para>
-
-<Para>
-Source-only distributions are either bugfix releases or snapshots of
-current state of development. The release has undergone some testing.
-Source releases of GHC 4.xx can be compiled up using GHC 2.10 or
-later.
-</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 source distributions slightly more often than binary
-distributions; but still 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, FreeBSD, NetBSD, 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>
-The native code generator is currently non-functional (as of GHC
-version 4.06), but we're actively working on getting it going again.
-</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. 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 version. 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, we strongly suggest you
-pick up a port of Perl 5 for <Literal>cygwin32</Literal>, as the
-common Hip/ActiveWare port of Perl is Not Cool Enough for our
-purposes.
-</Para>
-
-<Para>
-Perl should be put somewhere so that it can be invoked by the
-<Literal>#!</Literal> script-invoking mechanism. (I believe
-<Filename>/usr/bin/perl</Filename> is preferred; we use
-<Filename>/usr/local/bin/perl</Filename> at Glasgow.) The full
-pathname should 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 Autoconf 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:
-
-<ProgramListing>
-./configure
-</ProgramListing>
-
-<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>
-
-<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>
-
-<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>
-
-<Para>
-
-<ProgramListing>
-ProjectsToBuild = glafp-utils ghc hslibs
-</ProgramListing>
-
-</Para>
-
-<Para>
-The accompanying comment explains that this is the list of enabled
-projects; that is, if (after configuring) you type <Command>gmake all</Command> in
-<Constant>FPTOOLS_TOP</Constant> three specified projects will be made. If you want to
-add <Command>green-card</Command>, you can add this line to <Filename>build.mk</Filename>:
-</Para>
-
-<Para>
-
-<ProgramListing>
-ProjectsToBuild += green-card
-</ProgramListing>
-
-</Para>
-
-<Para>
-or, if you prefer,
-</Para>
-
-<Para>
-
-<ProgramListing>
-ProjectsToBuild = glafp-utils ghc green-card
-</ProgramListing>
-
-</Para>
-
-<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>
-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>
-
-<ProgramListing>
-YACC = @YaccCmd@
-</ProgramListing>
-
-</Para>
-
-<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>
-
-<Para>
-
-<ProgramListing>
-YACC = myyacc
-</ProgramListing>
-
-</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>
-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>
-
-</Sect2>
-
-<Sect2 id="sec-standard-targets">
-<Title>Standard Targets
-
-<IndexTerm><Primary>targets, standard makefile</Primary></IndexTerm>
-<IndexTerm><Primary>makefile targets</Primary></IndexTerm></Title>
-
-<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>
-You should say <Command>gmake boot</Command> right after configuring your build tree,
-but note that this is a one-off, i.e., there's no need to re-do
-<Command>gmake boot</Command> if you should re-configure your build tree at a later
-stage (no harm caused if you do though). Notably, you should say
-<Command>gmake boot</Command> before you say <Command>gmake clean</Command>.
-</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. You must be in a
-linked build tree to make this target.
-</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/driver/ghc-inplace</filename>.
-</para>
-
-<para> Do <emphasis>NOT</emphasis> use
-<filename>ghc/driver/ghc</filename>, or
-<filename>ghc/driver/ghc-4.xx</filename>, as these are the scripts
-intended for installation, and contain hard-wired paths to the
-installed libraries, rather than the libraries in the build tree.
-</para>
-
-<para>
-Happy can similarly be run from the build tree, using
-<filename>happy/src/happy-inplace</filename>.
-</para>
-</sect2>
-
-<Sect2>
-<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm>
-<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
-<IndexTerm><Primary>FAST, makefile
-variable</Primary></IndexTerm></Title>
-
-<Para>
-Sometimes the dependencies get in the way: if you've made a small
-change to one file, and you're absolutely sure that it won't affect
-anything else, but you know that <Command>make</Command> is going to rebuild everything
-anyway, the following hack may be useful:
-</Para>
-
-<Para>
-
-<ProgramListing>
-gmake FAST=YES
-</ProgramListing>
-
-</Para>
-
-<Para>
-This tells the make system to ignore dependencies and just build what
-you tell it to. In other words, it's equivalent to temporarily
-removing the <Filename>.depend</Filename> file in the current directory (where
-<Command>mkdependHS</Command> and friends store their dependency information).
-</Para>
-
-<Para>
-A bit of history: GHC used to come with a <Command>fastmake</Command> script that did
-the above job, but GNU make provides the features we need to do it
-without resorting to a script. Also, we've found that fastmaking is
-less useful since the advent of GHC's recompilation checker (see the
-User's Guide section on "Separate Compilation").
-</Para>
-
-</Sect2>
-
-</Sect1>
-
-<Sect1 id="sec-makefile-arch">
-<Title>The <Filename>Makefile</Filename> architecture
-<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
-
-<Para>
-<Command>make</Command> is great if everything works—you type <Command>gmake install</Command> and
-lo! the right things get compiled and installed in the right places.
-Our goal is to make this happen often, but somehow it often doesn't;
-instead some weird error message eventually emerges from the bowels of
-a directory you didn't know existed.
-</Para>
-
-<Para>
-The purpose of this section is to give you a road-map to help you figure
-out what is going right and what is going wrong.
-</Para>
-
-<Sect2>
-<Title>A small project</Title>
-
-<Para>
-To get started, let us look at the <Filename>Makefile</Filename> for an imaginary small
-<Literal>fptools</Literal> project, <Literal>small</Literal>. Each project in <Literal>fptools</Literal> has its own
-directory in <Constant>FPTOOLS_TOP</Constant>, so the <Literal>small</Literal> project will have its own
-directory <Constant>FPOOLS_TOP/small/</Constant>. Inside the <Filename>small/</Filename> directory there
-will be a <Filename>Makefile</Filename>, looking something like this:
-</Para>
-
-<Para>
-<IndexTerm><Primary>Makefile, minimal</Primary></IndexTerm>
-
-<ProgramListing>
-# Makefile for fptools project "small"
-
-TOP = ..
-include $(TOP)/mk/boilerplate.mk
-
-SRCS = $(wildcard *.lhs) $(wildcard *.c)
-HS_PROG = small
-
-include $(TOP)/target.mk
-</ProgramListing>
-
-</Para>
-
-<Para>
-This <Filename>Makefile</Filename> has three sections:
-</Para>
-
-<Para>
-
-<OrderedList>
-<ListItem>
-
-<Para>
- The first section includes
-<FOOTNOTE>
-
-<Para>
-One of the most important
-features of GNU <Command>make</Command> that we use is the ability for a <Filename>Makefile</Filename> to
-include another named file, very like <Command>cpp</Command>'s <Literal>#include</Literal>
-directive.
-</Para>
-
-</FOOTNOTE>
- a file of ``boilerplate'' code from the level
-above (which in this case will be
-<Filename><Constant>FPTOOLS_TOP</Constant>/mk/boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm>). As its name
-suggests, <Filename>boilerplate.mk</Filename> consists of a large quantity of standard
-<Filename>Makefile</Filename> code. We discuss this boilerplate in more detail in
-<XRef LinkEnd="sec-boiler">.
-<IndexTerm><Primary>include, directive in Makefiles</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile inclusion</Primary></IndexTerm>
-
-Before the <Literal>include</Literal> statement, you must define the <Command>make</Command> variable
-<Constant>TOP</Constant><IndexTerm><Primary>TOP</Primary></IndexTerm> to be the directory containing the <Filename>mk</Filename> directory in
-which the <Filename>boilerplate.mk</Filename> file is. It is <Emphasis>not</Emphasis> OK to simply say
-
-
-<ProgramListing>
-include ../mk/boilerplate.mk # NO NO NO
-</ProgramListing>
-
-
-Why? Because the <Filename>boilerplate.mk</Filename> file needs to know where it is, so
-that it can, in turn, <Literal>include</Literal> other files. (Unfortunately, when an
-<Literal>include</Literal>d file does an <Literal>include</Literal>, the filename is treated relative to
-the directory in which <Command>gmake</Command> is being run, not the directory in
-which the <Literal>include</Literal>d sits.) In general, <Emphasis>every file <Filename>foo.mk</Filename>
-assumes that <Filename><Constant>$(TOP)</Constant>/mk/foo.mk</Filename> refers to itself.</Emphasis> It is up to the
-<Filename>Makefile</Filename> doing the <Literal>include</Literal> to ensure this is the case.
-
-Files intended for inclusion in other <Filename>Makefile</Filename>s are written to have
-the following property: <Emphasis>after <Filename>foo.mk</Filename> is <Literal>include</Literal>d, it leaves
-<Constant>TOP</Constant> containing the same value as it had just before the <Literal>include</Literal>
-statement</Emphasis>. In our example, this invariant guarantees that the
-<Literal>include</Literal> for <Filename>target.mk</Filename> will look in the same directory as that for
-<Filename>boilerplate.mk</Filename>.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- The second section defines the following standard <Command>make</Command>
-variables: <Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm> (the source files from which is to be
-built), and <Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm> (the executable binary to be
-built). We will discuss in more detail what the ``standard
-variables'' are, and how they affect what happens, in <XRef LinkEnd="sec-targets">.
-
-The definition for <Constant>SRCS</Constant> uses the useful GNU <Command>make</Command> construct
-<Literal>$(wildcard $pat$)</Literal><IndexTerm><Primary>wildcard</Primary></IndexTerm>, which expands to a list of all
-the files matching the pattern <Literal>pat</Literal> in the current directory. In
-this example, <Constant>SRCS</Constant> is set to the list of all the <Filename>.lhs</Filename> and <Filename>.c</Filename>
-files in the directory. (Let's suppose there is one of each,
-<Filename>Foo.lhs</Filename> and <Filename>Baz.c</Filename>.)
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- The last section includes a second file of standard code,
-called <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm>. It contains the rules that tell
-<Command>gmake</Command> how to make the standard targets (<Xref LinkEnd="sec-standard-targets">). Why, you ask,
-can't this standard code be part of <Filename>boilerplate.mk</Filename>? Good question.
-We discuss the reason later, in <Xref LinkEnd="sec-boiler-arch">.
-
-You do not <Emphasis>have</Emphasis> to <Literal>include</Literal> the <Filename>target.mk</Filename> file. Instead, you
-can write rules of your own for all the standard targets. Usually,
-though, you will find quite a big payoff from using the canned rules
-in <Filename>target.mk</Filename>; the price tag is that you have to understand what
-canned rules get enabled, and what they do (<Xref LinkEnd="sec-targets">).
-
-</Para>
-</ListItem>
-
-</OrderedList>
-
-</Para>
-
-<Para>
-In our example <Filename>Makefile</Filename>, most of the work is done by the two
-<Literal>include</Literal>d files. When you say <Command>gmake all</Command>, the following things
-happen:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- <Command>gmake</Command> figures out that the object files are <Filename>Foo.o</Filename> and
-<Filename>Baz.o</Filename>.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- It uses a boilerplate pattern rule to compile <Filename>Foo.lhs</Filename> to
-<Filename>Foo.o</Filename> using a Haskell compiler. (Which one? That is set in the
-build configuration.)
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- It uses another standard pattern rule to compile <Filename>Baz.c</Filename> to
-<Filename>Baz.o</Filename>, using a C compiler. (Ditto.)
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- It links the resulting <Filename>.o</Filename> files together to make <Literal>small</Literal>,
-using the Haskell compiler to do the link step. (Why not use <Command>ld</Command>?
-Because the Haskell compiler knows what standard libraries to link in.
-How did <Command>gmake</Command> know to use the Haskell compiler to do the link,
-rather than the C compiler? Because we set the variable <Constant>HS_PROG</Constant>
-rather than <Constant>C_PROG</Constant>.)
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-All <Filename>Makefile</Filename>s should follow the above three-section format.
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>A larger project</Title>
-
-<Para>
-Larger projects are usually structured into a number of sub-directories,
-each of which has its own <Filename>Makefile</Filename>. (In very large projects, this
-sub-structure might be iterated recursively, though that is rare.)
-To give you the idea, here's part of the directory structure for
-the (rather large) GHC project:
-</Para>
-
-<Para>
-
-<Screen>
-$(FPTOOLS_TOP)/ghc/
- Makefile
- mk/
- boilerplate.mk
- rules.mk
- docs/
- Makefile
- ...source files for documentation...
- driver/
- Makefile
- ...source files for driver...
- compiler/
- Makefile
- parser/...source files for parser...
- renamer/...source files for renamer...
- ...etc...
-</Screen>
-
-</Para>
-
-<Para>
-The sub-directories <Filename>docs</Filename>, <Filename>driver</Filename>, <Filename>compiler</Filename>, and so on, each
-contains a sub-component of GHC, and each has its own <Filename>Makefile</Filename>.
-There must also be a <Filename>Makefile</Filename> in <Filename><Constant>$(FPTOOLS_TOP)</Constant>/ghc</Filename>. It does most
-of its work by recursively invoking <Command>gmake</Command> on the <Filename>Makefile</Filename>s in the
-sub-directories. We say that <Filename>ghc/Makefile</Filename> is a <Emphasis>non-leaf
-<Filename>Makefile</Filename></Emphasis>, because it does little except organise its children,
-while the <Filename>Makefile</Filename>s in the sub-directories are all <Emphasis>leaf
-<Filename>Makefile</Filename>s</Emphasis>. (In principle the sub-directories might themselves
-contain a non-leaf <Filename>Makefile</Filename> and several sub-sub-directories, but
-that does not happen in GHC.)
-</Para>
-
-<Para>
-The <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename> is considered a leaf <Filename>Makefile</Filename> even
-though the <Filename>ghc/compiler</Filename> has sub-directories, because these sub-directories
-do not themselves have <Filename>Makefile</Filename>s in them. They are just used to structure
-the collection of modules that make up GHC, but all are managed by the
-single <Filename>Makefile</Filename> in <Filename>ghc/compiler</Filename>.
-</Para>
-
-<Para>
-You will notice that <Filename>ghc/</Filename> also contains a directory <Filename>ghc/mk/</Filename>. It
-contains GHC-specific <Filename>Makefile</Filename> boilerplate code. More precisely:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- <Filename>ghc/mk/boilerplate.mk</Filename> is included at the top of
-<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
-sub-directories. It in turn <Literal>include</Literal>s the main boilerplate file
-<Filename>mk/boilerplate.mk</Filename>.
-
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- <Filename>ghc/mk/target.mk</Filename> is <Literal>include</Literal>d at the bottom of
-<Filename>ghc/Makefile</Filename>, and of all the leaf <Filename>Makefile</Filename>s in the
-sub-directories. It in turn <Literal>include</Literal>s the file <Filename>mk/target.mk</Filename>.
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-So these two files are the place to look for GHC-wide customisation
-of the standard boilerplate.
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-boiler-arch">
-<Title>Boilerplate architecture
-<IndexTerm><Primary>boilerplate architecture</Primary></IndexTerm>
-</Title>
-
-<Para>
-Every <Filename>Makefile</Filename> includes a <Filename>boilerplate.mk</Filename><IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm> file
-at the top, and <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> file at the bottom. In
-this section we discuss what is in these files, and why there have to
-be two of them. In general:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- <Filename>boilerplate.mk</Filename> consists of:
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- <Emphasis>Definitions of millions of <Command>make</Command> variables</Emphasis> that
-collectively specify the build configuration. Examples:
-<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the options to feed to the Haskell compiler;
-<Constant>NoFibSubDirs</Constant><IndexTerm><Primary>NoFibSubDirs</Primary></IndexTerm>, the sub-directories to enable within the
-<Literal>nofib</Literal> project; <Constant>GhcWithHc</Constant><IndexTerm><Primary>GhcWithHc</Primary></IndexTerm>, the name of the Haskell
-compiler to use when compiling GHC in the <Literal>ghc</Literal> project.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Emphasis>Standard pattern rules</Emphasis> that tell <Command>gmake</Command> how to construct one
-file from another.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-
-<Filename>boilerplate.mk</Filename> needs to be <Literal>include</Literal>d at the <Emphasis>top</Emphasis>
-of each <Filename>Makefile</Filename>, so that the user can replace the
-boilerplate definitions or pattern rules by simply giving a new
-definition or pattern rule in the <Filename>Makefile</Filename>. <Command>gmake</Command>
-simply takes the last definition as the definitive one.
-
-Instead of <Emphasis>replacing</Emphasis> boilerplate definitions, it is also quite
-common to <Emphasis>augment</Emphasis> them. For example, a <Filename>Makefile</Filename> might say:
-
-
-<ProgramListing>
-SRC_HC_OPTS += -O
-</ProgramListing>
-
-
-thereby adding ``<Option>-O</Option>'' to the end of <Constant>SRC_HC_OPTS</Constant><IndexTerm><Primary>SRC_HC_OPTS</Primary></IndexTerm>.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- <Filename>target.mk</Filename> contains <Command>make</Command> rules for the standard
-targets described in <Xref LinkEnd="sec-standard-targets">. These rules are selectively included,
-depending on the setting of certain <Command>make</Command> variables. These
-variables are usually set in the middle section of the
-<Filename>Makefile</Filename> between the two <Literal>include</Literal>s.
-
-<Filename>target.mk</Filename> must be included at the end (rather than being part of
-<Filename>boilerplate.mk</Filename>) for several tiresome reasons:
-
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- <Command>gmake</Command> commits target and dependency lists earlier than
-it should. For example, <FIlename>target.mk</FIlename> has a rule that looks like
-this:
-
-
-<ProgramListing>
-$(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@
-</ProgramListing>
-
-
-If this rule was in <Filename>boilerplate.mk</Filename> then <Constant>$(HS_PROG)</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>
-and <Constant>$(OBJS)</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm> would not have their final values at the
-moment <Command>gmake</Command> encountered the rule. Alas, <Command>gmake</Command> takes a snapshot
-of their current values, and wires that snapshot into the rule. (In
-contrast, the commands executed when the rule ``fires'' are only
-substituted at the moment of firing.) So, the rule must follow the
-definitions given in the <Filename>Makefile</Filename> itself.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- Unlike pattern rules, ordinary rules cannot be overriden or
-replaced by subsequent rules for the same target (at least, not without an
-error message). Including ordinary rules in <Filename>boilerplate.mk</Filename> would
-prevent the user from writing rules for specific targets in specific cases.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- There are a couple of other reasons I've forgotten, but it doesn't
-matter too much.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-boiler">
-<Title>The main <Filename>mk/boilerplate.mk</Filename> file
-
-<IndexTerm><Primary>boilerplate.mk</Primary></IndexTerm></Title>
-
-<Para>
-If you look at <Filename><Constant>$(FPTOOLS_TOP)</Constant>/mk/boilerplate.mk</Filename> you will find
-that it consists of the following sections, each held in a separate
-file:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Filename>config.mk</Filename><IndexTerm><Primary>config.mk</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-is the build configuration file we
-discussed at length in <Xref LinkEnd="sec-build-config">.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Filename>paths.mk</Filename><IndexTerm><Primary>paths.mk</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-defines <Command>make</Command> variables for
-pathnames and file lists. In particular, it gives definitions for:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>SRCS</Constant><IndexTerm><Primary>SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-all source files in the current directory.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-all Haskell source files in the current directory.
-It is derived from <Constant>$(SRCS)</Constant>, so if you override <Constant>SRCS</Constant> with a new value
-<Constant>HS_SRCS</Constant> will follow suit.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-similarly for C source files.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_OBJS</Constant><IndexTerm><Primary>HS_OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-the <Filename>.o</Filename> files derived from <Constant>$(HS_SRCS)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_OBJS</Constant><IndexTerm><Primary>C_OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-similarly for <Constant>$(C_SRCS)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>OBJS</Constant><IndexTerm><Primary>OBJS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-the concatenation of <Constant>$(HS_OBJS)</Constant> and <Constant>$(C_OBJS)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-Any or all of these definitions can easily be overriden by giving new
-definitions in your <Filename>Makefile</Filename>. For example, if there are things in
-the current directory that look like source files but aren't, then
-you'll need to set <Constant>SRCS</Constant> manually in your <Filename>Makefile</Filename>. The other
-definitions will then work from this new definition.
-</Para>
-
-<Para>
-What, exactly, does <Filename>paths.mk</Filename> consider a ``source file'' to be? It's
-based on the file's suffix (e.g. <Filename>.hs</Filename>, <Filename>.lhs</Filename>, <Filename>.c</Filename>, <Filename>.lc</Filename>, etc), but
-this is the kind of detail that changes, so rather than
-enumerate the source suffices here the best thing to do is to look in
-<Filename>paths.mk</Filename>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Filename>opts.mk</Filename><IndexTerm><Primary>opts.mk</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-defines <Command>make</Command> variables for option
-strings to pass to each program. For example, it defines
-<Constant>HC_OPTS</Constant><IndexTerm><Primary>HC_OPTS</Primary></IndexTerm>, the option strings to pass to the Haskell
-compiler. See <Xref LinkEnd="sec-suffix">.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-defines standard pattern rules—see <Xref LinkEnd="sec-suffix">.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-Any of the variables and pattern rules defined by the boilerplate file
-can easily be overridden in any particular <Filename>Makefile</Filename>, because the
-boilerplate <Literal>include</Literal> comes first. Definitions after this <Literal>include</Literal>
-directive simply override the default ones in <Filename>boilerplate.mk</Filename>.
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-suffix">
-<Title>Pattern rules and options
-
-<IndexTerm><Primary>Pattern rules</Primary></IndexTerm></Title>
-
-<Para>
-The file <Filename>suffix.mk</Filename><IndexTerm><Primary>suffix.mk</Primary></IndexTerm> defines standard <Emphasis>pattern
-rules</Emphasis> that say how to build one kind of file from another, for
-example, how to build a <Filename>.o</Filename> file from a <Filename>.c</Filename> file. (GNU <Command>make</Command>'s
-<Emphasis>pattern rules</Emphasis> are more powerful and easier to use than Unix
-<Command>make</Command>'s <Emphasis>suffix rules</Emphasis>.)
-</Para>
-
-<Para>
-Almost all the rules look something like this:
-</Para>
-
-<Para>
-
-<ProgramListing>
-%.o : %.c
- $(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@
-</ProgramListing>
-
-</Para>
-
-<Para>
-Here's how to understand the rule. It says that
-<Emphasis>something</Emphasis><Filename>.o</Filename> (say <Filename>Foo.o</Filename>) can be built from
-<Emphasis>something</Emphasis><Filename>.c</Filename> (<Filename>Foo.c</Filename>), by invoking the C compiler
-(path name held in <Constant>$(CC)</Constant>), passing to it the options
-<Constant>$(CC_OPTS)</Constant> and the rule's dependent file of the rule
-<Literal>$<</Literal> (<Filename>Foo.c</Filename> in this case), and putting the result in
-the rule's target <Literal>$@</Literal> (<Filename>Foo.o</Filename> in this case).
-</Para>
-
-<Para>
-Every program is held in a <Command>make</Command> variable defined in
-<Filename>mk/config.mk</Filename>—look in <Filename>mk/config.mk</Filename> for the
-complete list. One important one is the Haskell compiler, which is
-called <Constant>$(HC)</Constant>.
-</Para>
-
-<Para>
-Every program's options are are held in a <Command>make</Command> variables called
-<Constant><prog>_OPTS</Constant>. the <Constant><prog>_OPTS</Constant> variables are defined in
-<Filename>mk/opts.mk</Filename>. Almost all of them are defined like this:
-</Para>
-
-<Para>
-
-<ProgramListing>
-CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
-</ProgramListing>
-
-</Para>
-
-<Para>
-The four variables from which <Constant>CC_OPTS</Constant> is built have the following meaning:
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>SRC_CC_OPTS</Constant><IndexTerm><Primary>SRC_CC_OPTS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-options passed to all C
-compilations.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>WAY_<way>_CC_OPTS</Constant>:</Term>
-<ListItem>
-<Para>
-options passed to C
-compilations for way <Literal><way></Literal>. For example,
-<Constant>WAY_mp_CC_OPTS</Constant> gives options to pass to the C compiler when
-compiling way <Literal>mp</Literal>. The variable <Constant>WAY_CC_OPTS</Constant> holds
-options to pass to the C compiler when compiling the standard way.
-(<Xref LinkEnd="sec-ways"> dicusses multi-way
-compilation.)
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant><module>_CC_OPTS</Constant>:</Term>
-<ListItem>
-<Para>
-options to
-pass to the C compiler that are specific to module <Literal><module></Literal>. For example, <Constant>SMap_CC_OPTS</Constant> gives the specific options
-to pass to the C compiler when compiling <Filename>SMap.c</Filename>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>EXTRA_CC_OPTS</Constant><IndexTerm><Primary>EXTRA_CC_OPTS</Primary></IndexTerm>:</Term>
-<ListItem>
-<Para>
-extra options to pass to all
-C compilations. This is intended for command line use, thus:
-</Para>
-
-<Para>
-
-<ProgramListing>
-gmake libHS.a EXTRA_CC_OPTS="-v"
-</ProgramListing>
-
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-targets">
-<Title>The main <Filename>mk/target.mk</Filename> file
-
-<IndexTerm><Primary>target.mk</Primary></IndexTerm></Title>
-
-<Para>
-<Filename>target.mk</Filename> contains canned rules for all the standard targets
-described in <Xref LinkEnd="sec-standard-targets">. It is complicated by the fact that you don't want all of
-these rules to be active in every <Filename>Makefile</Filename>. Rather than have a
-plethora of tiny files which you can include selectively, there is a
-single file, <Filename>target.mk</Filename>, which selectively includes rules based on
-whether you have defined certain variables in your <Filename>Makefile</Filename>. This
-section explains what rules you get, what variables control them, and
-what the rules do. Hopefully, you will also get enough of an idea of
-what is supposed to happen that you can read and understand any weird
-special cases yourself.
-</Para>
-
-<Para>
-<VariableList>
-
-<VarListEntry>
-<Term><Constant>HS_PROG</Constant><IndexTerm><Primary>HS_PROG</Primary></IndexTerm>.</Term>
-<ListItem>
-<Para>
-If <Constant>HS_PROG</Constant> is defined, you get
-rules with the following targets:
-<VariableList>
-
-<VarListEntry>
-<Term><Filename>HS_PROG</Filename><IndexTerm><Primary>HS_PROG</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-itself. This rule links <Constant>$(OBJS)</Constant>
-with the Haskell runtime system to get an executable called
-<Constant>$(HS_PROG)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>install</Literal><IndexTerm><Primary>install</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-installs <Constant>$(HS_PROG)</Constant>
-in <Constant>$(bindir)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>C_PROG</Constant><IndexTerm><Primary>C_PROG</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-is similar to <Constant>HS_PROG</Constant>, except that
-the link step links <Constant>$(C_OBJS)</Constant> with the C runtime system.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIBRARY</Constant><IndexTerm><Primary>LIBRARY</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-is similar to <Constant>HS_PROG</Constant>, except that
-it links <Constant>$(LIB_OBJS)</Constant> to make the library archive <Constant>$(LIBRARY)</Constant>, and
-<Literal>install</Literal> installs it in <Constant>$(libdir)</Constant>.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIB_DATA</Constant><IndexTerm><Primary>LIB_DATA</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-…
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>LIB_EXEC</Constant><IndexTerm><Primary>LIB_EXEC</Primary></IndexTerm></Term>
-<ListItem>
-<Para>
-…
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Constant>HS_SRCS</Constant><IndexTerm><Primary>HS_SRCS</Primary></IndexTerm>, <Constant>C_SRCS</Constant><IndexTerm><Primary>C_SRCS</Primary></IndexTerm>.</Term>
-<ListItem>
-<Para>
-If <Constant>HS_SRCS</Constant>
-is defined and non-empty, a rule for the target <Literal>depend</Literal> is included,
-which generates dependency information for Haskell programs.
-Similarly for <Constant>C_SRCS</Constant>.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-All of these rules are ``double-colon'' rules, thus
-</Para>
-
-<Para>
-
-<ProgramListing>
-install :: $(HS_PROG)
- ...how to install it...
-</ProgramListing>
-
-</Para>
-
-<Para>
-GNU <Command>make</Command> treats double-colon rules as separate entities. If there
-are several double-colon rules for the same target it takes each in
-turn and fires it if its dependencies say to do so. This means that
-you can, for example, define both <Constant>HS_PROG</Constant> and <Constant>LIBRARY</Constant>, which will
-generate two rules for <Literal>install</Literal>. When you type <Command>gmake install</Command> both
-rules will be fired, and both the program and the library will be
-installed, just as you wanted.
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-subdirs">
-<Title>Recursion
-
-<IndexTerm><Primary>recursion, in makefiles</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile, recursing into subdirectories</Primary></IndexTerm></Title>
-
-<Para>
-In leaf <Filename>Makefile</Filename>s the variable <Constant>SUBDIRS</Constant><IndexTerm><Primary>SUBDIRS</Primary></IndexTerm> is undefined.
-In non-leaf <Filename>Makefile</Filename>s, <Constant>SUBDIRS</Constant> is set to the list of
-sub-directories that contain subordinate <Filename>Makefile</Filename>s. <Emphasis>It is up to
-you to set <Constant>SUBDIRS</Constant> in the <Filename>Makefile</Filename>.</Emphasis> There is no automation here—<Constant>SUBDIRS</Constant> is too important to automate.
-</Para>
-
-<Para>
-When <Constant>SUBDIRS</Constant> is defined, <Filename>target.mk</Filename> includes a rather
-neat rule for the standard targets (<Xref LinkEnd="sec-standard-targets"> that simply invokes
-<Command>make</Command> recursively in each of the sub-directories.
-</Para>
-
-<Para>
-<Emphasis>These recursive invocations are guaranteed to occur in the order
-in which the list of directories is specified in <Constant>SUBDIRS</Constant>. </Emphasis>This
-guarantee can be important. For example, when you say <Command>gmake boot</Command> it
-can be important that the recursive invocation of <Command>make boot</Command> is done
-in one sub-directory (the include files, say) before another (the
-source files). Generally, put the most independent sub-directory
-first, and the most dependent last.
-</Para>
-
-</Sect2>
-
-<Sect2 id="sec-ways">
-<Title>Way management
-
-<IndexTerm><Primary>way management</Primary></IndexTerm></Title>
-
-<Para>
-We sometimes want to build essentially the same system in several
-different ``ways''. For example, we want to build GHC's <Literal>Prelude</Literal>
-libraries with and without profiling, with and without concurrency,
-and so on, so that there is an appropriately-built library archive to
-link with when the user compiles his program. It would be possible to
-have a completely separate build tree for each such ``way'', but it
-would be horribly bureaucratic, especially since often only parts of
-the build tree need to be constructed in multiple ways.
-</Para>
-
-<Para>
-Instead, the <Filename>target.mk</Filename><IndexTerm><Primary>target.mk</Primary></IndexTerm> contains some clever magic to
-allow you to build several versions of a system; and to control
-locally how many versions are built and how they differ. This section
-explains the magic.
-</Para>
-
-<Para>
-The files for a particular way are distinguished by munging the
-suffix. The ``normal way'' is always built, and its files have the
-standard suffices <Filename>.o</Filename>, <Filename>.hi</Filename>, and so on. In addition, you can build
-one or more extra ways, each distinguished by a <Emphasis>way tag</Emphasis>. The
-object files and interface files for one of these extra ways are
-distinguished by their suffix. For example, way <Literal>mp</Literal> has files
-<Filename>.mp_o</Filename> and <Filename>.mp_hi</Filename>. Library archives have their way tag the other
-side of the dot, for boring reasons; thus, <Filename>libHS_mp.a</Filename>.
-</Para>
-
-<Para>
-A <Command>make</Command> variable called <Constant>way</Constant> holds the current way tag. <Emphasis><Constant>way</Constant>
-is only ever set on the command line of a recursive invocation of
-<Command>gmake</Command>.</Emphasis> It is never set inside a <Filename>Makefile</Filename>. So it is a global
-constant for any one invocation of <Command>gmake</Command>. Two other <Command>make</Command>
-variables, <Constant>way_</Constant> and <Constant>_way</Constant> are immediately derived from <Constant>$(way)</Constant> and
-never altered. If <Constant>way</Constant> is not set, then neither are <Constant>way_</Constant> and
-<Constant>_way</Constant>, and the invocation of <Command>make</Command> will build the ``normal way''.
-If <Constant>way</Constant> is set, then the other two variables are set in sympathy.
-For example, if <Constant>$(way)</Constant> is ``<Literal>mp</Literal>'', then <Constant>way_</Constant> is set to ``<Literal>mp_</Literal>''
-and <Constant>_way</Constant> is set to ``<Literal>_mp</Literal>''. These three variables are then used
-when constructing file names.
-</Para>
-
-<Para>
-So how does <Command>make</Command> ever get recursively invoked with <Constant>way</Constant> set? There
-are two ways in which this happens:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- For some (but not all) of the standard targets, when in a leaf
-sub-directory, <Command>make</Command> is recursively invoked for each way tag in
-<Constant>$(WAYS)</Constant>. You set <Constant>WAYS</Constant> to the list of way tags you want these
-targets built for. The mechanism here is very much like the recursive
-invocation of <Command>make</Command> in sub-directories (<Xref LinkEnd="sec-subdirs">).
-
-It is up to you to set <Constant>WAYS</Constant> in your <Filename>Makefile</Filename>; this is how you
-control what ways will get built.
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- For a useful collection of
-targets (such as <Filename>libHS_mp.a</Filename>, <Filename>Foo.mp_o</Filename>) there is a rule which
-recursively invokes <Command>make</Command> to make the specified target, setting the
-<Constant>way</Constant> variable. So if you say <Command>gmake Foo.mp_o</Command> you should see a
-recursive invocation <Command>gmake Foo.mp_o way=mp</Command>, and <Emphasis>in this
-recursive invocation the pattern rule for compiling a Haskell file
-into a <Filename>.o</Filename> file will match</Emphasis>. The key pattern rules (in <Filename>suffix.mk</Filename>)
-look like this:
-
-
-<ProgramListing>
-%.$(way_)o : %.lhs
- $(HC) $(HC_OPTS) $< -o $@
-</ProgramListing>
-
-
-Neat, eh?
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</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="sec-booting-from-C">
-<Title>Booting/porting from C (<Filename>.hc</Filename>) files
-
-<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>
-
-<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>
-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>
-
-<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>
-
-<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
-</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>
-<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'':
-</Para>
-
-<Para>
-
-<OrderedList>
-<ListItem>
-
-<Para>
-One difficulty that comes up from time to time is running out of space
-in <Filename>/tmp</Filename>. (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>
-
-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>
-export TMPDIR=<dir>
-</ProgramListing>
-
-in your <Filename>build.mk</Filename> file.
-Then GHC and the other <Literal>fptools</Literal> programs will use the appropriate directory
-in all cases.
-
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-In compiling some support-code bits, e.g., in <Filename>ghc/rts/gmp</Filename> and even
-in <Filename>ghc/lib</Filename>, you may get a few C-compiler warnings. We think these
-are OK.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-When compiling via C, you'll sometimes get ``warning: assignment from
-incompatible pointer type'' out of GCC. Harmless.
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-Similarly, <Command>ar</Command>chiving warning messages like the following are not
-a problem:
-
-<Screen>
-ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
-ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
-...
-</Screen>
-
-
-</Para>
-</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
-vagaries of different systems, it seems. The solution is simple:
-
-
-<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
-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
-<Filename>Makefile</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- For GHC < 4.00, add a suitable <Option>-H</Option> flag to the <Filename>Makefile</Filename>, as
-above.
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-
-and try again: <Command>gmake</Command>. (see <Xref LinkEnd="sec-suffix"> for information about
-<Constant><module>_HC_OPTS</Constant>.)
-
-Alternatively, just cut to the chase:
-
-<Screen>
-% cd ghc/compiler
-% make EXTRA_HC_OPTS=-optCrts-M128M
-</Screen>
-
-
-</Para>
-</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.
-
-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>
-
-<Para>
-You <Emphasis>may</Emphasis> need to re-<Command>ranlib</Command><IndexTerm><Primary>ranlib</Primary></IndexTerm> your libraries (on Sun4s).
-
-
-<Screen>
-% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
-% foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
-? ranlib $i
-? # or, on some machines: ar s $i
-? end
-</Screen>
-
-
-We'd be interested to know if this is still necessary.
-
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-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>
-SLIT("Hello, world")
-</ProgramListing>
-
-
-Some <Command>cpp</Command>s treat the comma inside the string as separating two macro
-arguments, so you get
-
-
-<Screen>
-:731: macro `SLIT' used with too many (2) args
-</Screen>
-
-
-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.
-</Para>
-</ListItem>
-
-</OrderedList>
-
-</Para>
-
-</Sect1>
-
-
-<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
-
-<Para>
-This section summarises how to get the utilities you need on your
-Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
-installing and running GHC may be found in the user guide. In general,
-Win95/Win98 behave the same, and WinNT/Win2k behave the same. It is based
-largely on detailed advice from Sigbjørn Finne. You should read the
-GHC installation guide sections on Windows (in the user guide) before
-continuing to read these notes.
-</Para>
-
-
-<Sect2><Title>Installing ssh</Title>
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Extract the whole of <ULink URL="http://research.microsoft.com/~simonpj/ssh-1_2_26-cygwinb19.tar.gz">the ssh archive</ULink> into your <Filename>C:\</Filename> directory, and use the ``All files'' and ``User folder names'' options in WinZip extract dialogue box. This populates your <Filename>C:\usr\local</Filename> tree.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Extract <ULink URL="http://research.microsoft.com/~simonpj/cygwinb19.dll.zip">cygwinb19.dll</ULink> into <Filename>/usr/local/bin</Filename>. The current version
-of Cywin is b20, but this version of ssh was compiled with b19.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-On a Win2k machine, open up a bash and do
-</Para>
-
-<Screen>
-foo$ cd /etc
-foo$ mkpasswd -l > passwd
-</Screen>
-
-<Para>
-Check that your login entry is on the first line
-of that file. If not, move it to the top. It's OK
-for 'Administrator' to be the first entry, assuming you are one.
-</Para>
-
-<Para>
-However, Win9x doesn't support the calls that <Command>mkpasswd</Command> relies on
-(e.g., <Function>NetUserEnum</Function>). If you run <Command>mkpasswd</Command> you
-get errors like:
-</Para>
-
-<Screen>
-linked to missing export netapi32.dll:NetUserEnum
-</Screen>
-
-<Para>
-The passwd file is used
-by ssh in a fairly rudimentary manner, so I'd simply
-synthesise/copy an existing Unix <Filename>/etc/passwd</Filename>, i.e., create
-an <Filename>/etc/passwd</Filename> file containing the line
-</Para>
-
-<Screen>
-<login>::500:513:::/bin/sh
-</Screen>
-
-<Para>
-where <Literal><login></Literal> is your login id.
-</Para>
-</ListItem>
-
-<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>
- 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>
-
-<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>
-
-<Screen>
-c:\tmp> set CYGWIN32=tty
-c:\tmp> c:/user/local/bin/ssh-keygen1
-</Screen>
-</ListItem>
-
-<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>
- 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.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Sect2>
-
-
-<Sect2><Title>Installing CVS</Title>
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Unpack
-<ULink URL="http://research.microsoft.com/~simonpj/cvs-1_10-win.zip">
-CVS</ULink> and, following the instructions in the <Filename>README</Filename>, copy the
-appropriate files into <Filename>/usr/local/bin</Filename>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-From the System control panel,
-set the following <Emphasis>user</Emphasis> environment variables (see the GHC user guide)
-</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>: <Filename>c:/usr/local/bin/ssh1</Filename>
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Constant>CVSROOT</Constant>: <Literal>:ext:username@cvs.haskell.org:/home/cvs/root</Literal>,
-where <Literal>username</Literal> is your userid
-</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>
-</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>
-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>
-
-<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:
-</Para>
-
-<Screen>
-setsockopt IPTOS_LOWDELAY: Invalid argument
-setsockopt IPTOS_THROUGHPUT: Invalid argument
-</Screen>
-
-<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.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-If you want to check out part of large tree, proceed as follows:
-</Para>
-
-<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.
-</Para>
-
-<Para>
-The <Command>cvs update</Command> command sucks in a named sub-directory.
-</Para>
-</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.
-</Para>
-
-</Sect2>
-
-
-<Sect2><Title>Installing autoconf</Title>
-
-<Para>
-Only required if you are doing builds from GHC's sources
-checked out from the CVS tree.
-</Para>
-
-<ItemizedList>
-<ListItem>
-<Para>
-Fetch the (standard, Unix) <Command>autoconf</Command> distribution from
-<ULink URL="ftp://ftp.gnu.org/gnu/autoconf">ftp.gnu.org</ULink>.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-Unpack it into an arbitrary directory.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-Make sure that the directory <Filename>/usr/local/bin</Filename> exists.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-Say "<Filename>./configure</Filename>".
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-Now <Command>make install</Command>. This should put <Filename>autoheader</Filename>
-and <Filename>autoconf</Filename> in <Filename>/usr/local/bin</Filename>.
-</Para>
-</ListItem>
-</ItemizedList>
-
-<Para>
-<Command>autoheader</Command> doesn't seem to work, but you don't need it
-for GHC.
-</Para>
-
-</Sect2>
-
-
-<Sect2><Title>Building GHC</Title>
-
-<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>
-<Para>
-You have to 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
-mk/config.h is unchanged
-configuring in ghc
-running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
-./configure: ./configure: No such file or directory
-configure: error: ./configure failed for ghc
-</Screen>
-</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.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Sect2>
-
-</Sect1>
-
-</Article>
projects / ghc-hetmet.git / commitdiff