<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-<Article>
+<Article id="building-guide">
<ArtHeader>
-<Title>Building and Installing the Glasgow Functional Programming Tools Suite
-Version 4.04</Title>
+<Title>Building the Glasgow Functional Programming Tools Suite</Title>
<Author><OtherName>The GHC Team</OtherName></Author>
-<Address><Email>glasgow-haskell-{users,bugs}@dcs.gla.ac.uk</Email></Address>
+<Address><Email>glasgow-haskell-{users,bugs}@haskell.org</Email></Address>
<PubDate>January 2000</PubDate>
<Abstract>
<VariableList>
<VarListEntry>
-<Term><IndexTerm><Primary>Binary distribution</Primary></IndexTerm>.</Term>
+<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
</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>.</Term>
+<Term><IndexTerm><Primary>Source distribution</Primary></IndexTerm>Source distribution.</Term>
<ListItem>
<Para>
You have a supported
<Para>
Source-only distributions are either bugfix releases or snapshots of
current state of development. The release has undergone some testing.
-Source releases of 4.xx can be compiled up using 2.10 or later.
+Source releases of GHC 4.xx can be compiled up using GHC 2.10 or
+later.
</Para>
</ListItem></VarListEntry>
<VarListEntry>
</Para>
<Para>
-More information about our CVS repository is available at <ULink
-URL="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html"
->The Fptools CVS Cheat Sheet</ULink
->.
+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>
</Sect1>
-<Sect1>
+<Sect1 id="sec-build-checks">
<Title>Things to check before you start typing</Title>
<Para>
<ListItem>
<Para>
-<IndexTerm><Primary>Disk space needed</Primary></IndexTerm>: About 30MB (five hamburgers' 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 8–10 hamburgers.
-
-You'll need over 100MB (say, 20 hamburgers' worth) if you need to
-build the basic stuff from scratch.
-
-
-All of the above are <Emphasis>estimates</Emphasis> of disk-space needs. (I don't yet
-know the disk requirements for the non-GHC tools).
-
+<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, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD,
-or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are
-in pretty good shape. <Xref LinkEnd="sec-port-info">
-gives the full run-down on ports or lack thereof.
-
-NOTE: as of version 4.00, we lost a few ports. All of the x86 ports
-are working, as is the Sparc/Solaris port, but the rest will need a
-little work. Please contact us if you can provide hardware cycles
-and/or porting expertise.
-
+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>
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 <ULink
-URL="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html"
->known bugs page</ULink>.
+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 User's guide
+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@dcs.gla.ac.uk</Email>.
+If in doubt, please send a message to
+<Email>glasgow-haskell-bugs@haskell.org</Email>.
<IndexTerm><Primary>bugs, mailing list</Primary></IndexTerm>
</Para>
</ListItem>
<IndexTerm><Primary>GHC ports</Primary></IndexTerm>
<IndexTerm><Primary>supported platforms</Primary></IndexTerm>
<IndexTerm><Primary>platforms, supported</Primary></IndexTerm>
-</Para>
-
-<Para>
The main question is whether or not the Haskell compiler (GHC) runs on
your platform.
</Para>
<IndexTerm><Primary>native-code generator</Primary></IndexTerm>
<IndexTerm><Primary>registerised ports</Primary></IndexTerm>
<IndexTerm><Primary>unregisterised ports</Primary></IndexTerm>
-</Para>
-
-<Para>
The GHC hierarchy of Porting Goodness: (a) Best is a native-code
generator; (b) next best is a ``registerised''
port; (c) the bare minimum is an ``unregisterised'' port.
</Para>
<Para>
-We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and
-Linux, and DEC Alphas running OSF/1 V2.0, so those are the
-``fully-supported'' platforms, unsurprisingly. All have native-code
-generators, for quicker compilations. The native-code generator for
-iX86 platforms (e.g., Linux ELF) is <Emphasis>nearly</Emphasis> working; but is not
-turned on by default.
+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>
-Here's everything that's known about GHC ports. We identify platforms
-by their ``canonical'' CPU/Manufacturer/OS triple.
+We use Sparcs running Solaris 2.7 and x86 boxes running FreeBSD and
+Linux, so those are the best supported platforms, unsurprisingly.
</Para>
<Para>
-Note that some ports are fussy about which GCC version you use; or
-require GAS; or…
+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-osf1:</Term>
+<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>
-<IndexTerm><Primary>alpha-dec-osf1: fully supported</Primary></IndexTerm>
-</Para>
<Para>
-(We have OSF/1 V3.0.) Fully supported, including native-code
-generator. We recommend GCC 2.6.x or later.
+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>
-<IndexTerm><Primary>sparc-sun-sunos4: fully supported</Primary></IndexTerm>
-</Para>
<Para>
-Fully supported, including native-code generator.
+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>
-<IndexTerm><Primary>sparc-sun-solaris2: fully supported</Primary></IndexTerm>
-</Para>
<Para>
-Fully supported, including native-code generator. A couple of quirks,
-though: (a) the profiling libraries are bizarrely huge when compiled
-with object splitting; (b) the default <Command>xargs</Command><IndexTerm><Primary>xargs</Primary></IndexTerm> program is
-atrociously bad for building GHC libraries (see <Xref LinkEnd="sec-pre-supposed"> for
-details).
+Fully supported, including native-code generator.
</Para>
+
</ListItem></VarListEntry>
<VarListEntry>
-<Term>HP-PA box running HP</Term>
+<Term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</Term>
+<IndexTerm><Primary>hppa1.1-hp-hpux</Primary></IndexTerm>
<ListItem>
-<Para>
-UX 9.x:/
-<IndexTerm><Primary>hppa1.1-hp-hpux: registerised port</Primary></IndexTerm>
-</Para>
<Para>
-Works registerised. No native-code generator. For GCC, you're best
-off with one of the Utah releases of GCC 2.6.3 (`u3' or later), from
-<Literal>jaguar.cs.utah.edu</Literal>. We think a straight GCC 2.7.x works,
-too.
+Works registerised. No native-code generator.
</Para>
-<Para>
-Concurrent/Parallel Haskell probably don't work (yet).
-<IndexTerm><Primary>hppa1.1-hp-hpux: concurrent—no</Primary></IndexTerm>
-<IndexTerm><Primary>hppa1.1-hp-hpux: parallel—no</Primary></IndexTerm>
-</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term>i386-*-linux (PCs running Linux—ELF format):</Term>
+<Term>i386-unknown-linux (PCs running Linux—ELF binary format):</Term>
+<IndexTerm><Primary>i386-*-linux</Primary></IndexTerm>
<ListItem>
-<Para>
-<IndexTerm><Primary>i386-*-linux: registerised port</Primary></IndexTerm>
-</Para>
-
-<Para>
-GHC works registerised. You <Emphasis>must</Emphasis> have GCC 2.7.x or later. The
-iX86 native-code generator is <Emphasis>nearly</Emphasis> there, but it isn't turned
-on by default.
-</Para>
<Para>
-Profiling works, and Concurrent Haskell works.
-<IndexTerm><Primary>i386-*-linux: profiling—yes</Primary></IndexTerm>
-<IndexTerm><Primary>i386-*-linux: concurrent—yes</Primary></IndexTerm>
-Parallel Haskell probably works.
-<IndexTerm><Primary>i386-*-linux: parallel—maybe</Primary></IndexTerm>
+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>
-<Para>
-On old Linux a.out systems: should be the same.
-<IndexTerm><Primary>i386-*-linuxaout: registerised port</Primary></IndexTerm>
-</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and
-NetBSD/OpenBSD using FreeBSD emulation):</Term>
+<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>
-<IndexTerm><Primary>i386-*-freebsd:registerised port</Primary></IndexTerm>
-</Para>
<Para>
-GHC works registerised. Supports same set of bundles as the above.
+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>
-<Para>
-<IndexTerm><Primary>i386-*-freebsd: profiling—yes</Primary></IndexTerm>
-<IndexTerm><Primary>i386-*-freebsd: concurrent—yes</Primary></IndexTerm>
-<IndexTerm><Primary>i386-*-freebsd: parallel—maybe</Primary></IndexTerm>
-</Para>
</ListItem></VarListEntry>
<VarListEntry>
<Term>i386-unknown-cygwin32:</Term>
+<IndexTerm><Primary>i386-unknown-cygwin32</Primary></IndexTerm>
<ListItem>
-<Para>
-<IndexTerm><Primary>i386-unknown-cygwin32: fully supported</Primary></IndexTerm>
-</Para>
<Para>
-Fully supported under Win95/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.)
-Profiling works, so does Concurrent Haskell.
+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>
-<Para>
-<IndexTerm><Primary>i386-*-cygwin32: profiling—yes</Primary></IndexTerm>
-<IndexTerm><Primary>i386-*-cygwin32: concurrent—yes</Primary></IndexTerm>
-</Para>
</ListItem></VarListEntry>
<VarListEntry>
<Term>mips-sgi-irix5:</Term>
+<IndexTerm><Primary>mips-sgi-irix[5-6]</Primary></IndexTerm>
<ListItem>
-<Para>
-<IndexTerm><Primary>mips-sgi-irix5: registerised port</Primary></IndexTerm>
-</Para>
<Para>
-GHC works registerised (no native-code generator). I suspect any
-GCC 2.6.x (or later) is OK. The GCC that I used was built with
-<Option>--with-gnu-as</Option>; turns out that is important!
-</Para>
-
-<Para>
-Concurrent/Parallel Haskell probably don't work (yet).
-Profiling might work, but it is untested.
-<IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</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>
-<VarListEntry>
-<Term>mips-sgi-irix6:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>mips-sgi-irix6: registerised port</Primary></IndexTerm>
-</Para>
-
-<Para>
-Thanks to the fine efforts of Tomasz Cholewo <ULink
-URL="mailto:tjchol01@mecca.spd.louisville.edu"
->tjchol01@mecca.spd.louisville.edu</ULink
->, GHC works registerised (no
-native code generator) under IRIX 6.2 and 6.3. Depends on having a
-<ULink
-URL="http://mecca.spd.louisville.edu/~tjchol01/software/"
->specially tweaked version of gcc-2.7.2 around</ULink>.
-</Para>
-<Para>
-Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested).
-<IndexTerm><Primary>mips-sgi-irix6: concurrent—maybe</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix6: parallel—maybe</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix6: profiling—yes</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
<VarListEntry>
<Term>powerpc-ibm-aix:</Term>
<ListItem>
<Para>
-<IndexTerm><Primary>powerpc-ibm-aix: registerised port</Primary></IndexTerm>
-GHC works registerised (no native-code generator…yet).
-I suspect 2.7.x is what you need together with this.
-</Para>
-
-<Para>
-Concurrent/Parallel Haskell probably don't work (yet).
-Profiling might work, but it is untested.
-<IndexTerm><Primary>mips-sgi-irix5: concurrent—no</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix5: parallel—no</Primary></IndexTerm>
-<IndexTerm><Primary>mips-sgi-irix5: profiling—maybe</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>m68k-apple-macos7 (Mac, using MPW):</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>m68k-apple-macos7: historically ported</Primary></IndexTerm>
-Once upon a time, David Wright in Tasmania has actually
-gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow.
-You may be able to get Thomson's from here. (Not sure that it will
-excite you to death, but…)
-</Para>
-
-<Para>
-No particularly recent GHC is known to work on a Mac.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term>m68k-next-nextstep3:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>m68k-next-nextstep3: historically ported</Primary></IndexTerm>
-Carsten Schultz succeeded with a ``registerised'' port of GHC 0.29.
-There's probably a little bit-rot since then, but otherwise it should
-still be fine.
-</Para>
-
-<Para>
-Concurrent/Parallel Haskell probably won't work (yet).
-<IndexTerm><Primary>m68k-next-nextstep3: concurrent—no</Primary></IndexTerm>
-<IndexTerm><Primary>m68k-next-nextstep3: parallel—no</Primary></IndexTerm>
+<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>
-<VarListEntry>
-<Term>m68k-sun-sunos4 (Sun3):</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>m68k-sun-sunos4: registerised
-port</Primary></IndexTerm> GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC 0.26
-worked registerised. No native-code generator.
-</Para>
-<Para>
-Concurrent/Parallel Haskell probably don't work (yet).
-<IndexTerm><Primary>m68k-sun-sunos4: concurrent—no</Primary></IndexTerm>
-<IndexTerm><Primary>m68k-sun-sunos4: parallel—no</Primary></IndexTerm>
-</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>
Unless you hear otherwise, the other tools work if GHC works.
</Para>
-<Para>
-Haggis requires Concurrent Haskell to work.
-<IndexTerm><Primary>Haggis, Concurrent Haskell</Primary></IndexTerm>
-</Para>
-
</Sect2>
</Sect1>
<Para>
Here are the gory details about some utility programs you may need;
-<Command>perl</Command> and <Command>gcc</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>
+<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>
<VarListEntry>
<Term>Perl:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: Perl</Primary></IndexTerm>
<IndexTerm><Primary>Perl, pre-supposed</Primary></IndexTerm>
-<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.
+<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.
+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.
+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>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: GCC (GNU C compiler)</Primary></IndexTerm>
<IndexTerm><Primary>GCC (GNU C compiler), pre-supposed</Primary></IndexTerm>
-</Para>
+<ListItem>
<Para>
-Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other
-versions at your own risk!
+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>
<Option>-monly-N-regs</Option> option; see the User's Guide)
</Para>
</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Command>xargs</Command> on Solaris2:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>xargs, presupposed (Solaris only)</Primary></IndexTerm>
-<IndexTerm><Primary>Solaris: alternative xargs</Primary></IndexTerm>
-The GHC libraries are put together with something like:
-<ProgramListing>
-find bunch-of-dirs -name '*.o' -print | xargs ar q ...
-</ProgramListing>
+<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>
-Unfortunately the Solaris <Command>xargs</Command> (the shell-script equivalent
-of <Function>map</Function>) only ``bites off'' the <Filename>.o</Filename> files a few at a
-time—with near-infinite rebuilding of the symbol table in
-the <Filename>.a</Filename> file.
-</Para>
-
-<Para>
-The best solution is to install a sane <Command>xargs</Command> from the GNU
-findutils distribution. You can unpack, build, and install the GNU
-version in the time the Solaris <Command>xargs</Command> mangles just one GHC
-library.
-</Para>
-</ListItem></VarListEntry>
<VarListEntry>
<Term>Autoconf:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: Autoconf</Primary></IndexTerm>
<IndexTerm><Primary>Autoconf, pre-supposed</Primary></IndexTerm>
-</Para>
-
+<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.
+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>.
+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>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: sed</Primary></IndexTerm>
<IndexTerm><Primary>sed, pre-supposed</Primary></IndexTerm>
-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.)
+<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.
+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">
<VarListEntry>
<Term>PVM version 3:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: PVM3 (Parallel Virtual Machine)</Primary></IndexTerm>
<IndexTerm><Primary>PVM3 (Parallel Virtual Machine), pre-supposed</Primary></IndexTerm>
-</Para>
+<ListItem>
<Para>
PVM is the Parallel Virtual Machine on which Parallel Haskell programs
<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>.
+available on the net; I think I got it from
+<Literal>research.att.com</Literal>, in <Filename>netlib</Filename>.
</Para>
<Para>
</ListItem></VarListEntry>
<VarListEntry>
<Term><Command>bash</Command>:</Term>
+<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
<ListItem>
<Para>
-<IndexTerm><Primary>bash, presupposed (Parallel Haskell only)</Primary></IndexTerm>
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).
<VarListEntry>
<Term>DocBook:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: DocBook</Primary></IndexTerm>
<IndexTerm><Primary>DocBook, pre-supposed</Primary></IndexTerm>
-All our documentation is written in SGML, using the DocBook DTD and processed using the <ULink URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook tools</ULink>, which is the most shrink-wrapped SGML suite
-that we could find. Unfortunately, it's only packaged as RPMs. You can use it to generate HTML (and
-hence DVI, PDF and Postscript) and RTF from any
-LinuxDoc source file (including this manual).
+<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>
-<ListItem>
-<Para>
<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.
<Title>Other useful tools
</Title>
-<Para>
<VariableList>
-
<VarListEntry>
<Term>Flex:</Term>
-<ListItem>
-<Para>
<IndexTerm><Primary>pre-supposed: flex</Primary></IndexTerm>
<IndexTerm><Primary>flex, pre-supposed</Primary></IndexTerm>
-</Para>
+<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.
+of utilities in <Literal>glafp-utils</Literal>. Depending on your
+operating system, the supplied <Command>lex</Command> may or may not
+work; you should get the GNU version.
</Para>
</ListItem></VarListEntry>
</VariableList>
-</Para>
</Sect2>
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.
+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>
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
./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:
+<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>
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).
+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>
<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>.
+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>
reverses the effect of <Literal>install</Literal>.
</Para>
</ListItem></VarListEntry>
+
<VarListEntry>
<Term><Literal>clean</Literal>:</Term>
<ListItem>
<Para>
-remove all easily-rebuilt files.
-</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>veryclean</Literal>:</Term>
+<Term><Literal>maintainer-clean</Literal>:</Term>
<ListItem>
<Para>
-remove all files that can be rebuilt at all.
-There's a danger here that you may remove a file that needs a more
-obscure utility to rebuild it (especially if you started from a source
-distribution).
-</Para>
-</ListItem></VarListEntry>
+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>
</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>
+<Title>Fast Making <IndexTerm><Primary>fastmake</Primary></IndexTerm>
<IndexTerm><Primary>dependencies, omitting</Primary></IndexTerm>
-<IndexTerm><Primary>FAST, makefile variable</Primary></IndexTerm></Title>
+<IndexTerm><Primary>FAST, makefile
+variable</Primary></IndexTerm></Title>
<Para>
Sometimes the dependencies get in the way: if you've made a small
</Sect1>
-<Sect1>
+<Sect1 id="sec-makefile-arch">
<Title>The <Filename>Makefile</Filename> architecture
<IndexTerm><Primary>makefile architecture</Primary></IndexTerm></Title>
<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
+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.
+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.
-Then follow the `normal' instructions in <Xref LinkEnd="sec-building-from-source"> for setting
-up a build tree. When you invoke the configure script, you'll have
-to tell the script about your intentions:
+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% ./configure --enable-hc-boot
+foo% distrib/hc-build --prefix=INSTALL_DIRECTORY
</Screen>
-
-<IndexTerm><Primary>--enable-hc-boot</Primary></IndexTerm>
-<IndexTerm><Primary>--disable-hc-boot</Primary></IndexTerm>
-</Para>
-
+<IndexTerm><Primary>--hc-build</Primary></IndexTerm>
<Para>
-Assuming it configures OK and you don't need to create <Filename>mk/build.mk</Filename>
-for any other purposes, the next step is to proceed with a <Command>make boot</Command>
-followed by <Command>make all</Command>. At the successful completion of <Command>make all</Command>,
-you should end up with a binary of the compiler proper,
-<Filename>ghc/compiler/hsc</Filename>, plus archives (but no <Filename>.hi</Filename> files!) of the prelude
-libraries. To generate the Prelude interface files (and test drive the
-bootstrapped compiler), re-run the <Command>configure</Command> script, but this time
-without the <Option>--enable-hc-boot</Option> option. After that re-create the
-contents of <Filename>ghc/lib</Filename>:
+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>
-
-<Para>
-
<Screen>
-foo% ./configure
- ....
-foo% cd ghc/lib
-foo% make clean
-foo% make boot
-foo% make all
+foo% make install
</Screen>
-</Para>
-
<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
<ListItem>
<Para>
- If you're compiling with GHC 4.00 or above, 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>).
+ 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>
<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.
+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>
<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.05</Filename>, so you may need to duplicate this file as <Filename>ghc</Filename>
+<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.05</Filename> to <Filename>ghc</Filename>.
+just rename <Filename>ghc-4.08</Filename> to <Filename>ghc</Filename>.
And make sure that the directory is in your path.
</Para>
</ListItem>
-<ListItem>
-<Para>
-Compile <Command>happy</Command> and <Command>ghc</Command>
-with <Option>-static</Option>. To do this, set
-</Para>
-
-<ProgramListing>
-GhcHcOpts=-static
-HappyHcOpts=-static
-</ProgramListing>
-
-<Para>
-in your <Filename>build.mk</Filename> file.
-[Actually, I successfully compiled Happy without <Option>-static</Option> on Win2k, but not GHC.]
-</Para>
-</ListItem>
-
</ItemizedList>
</Sect2>
projects / ghc-hetmet.git / blobdiff