-<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="building-guide">
-<artheader>
+<articleinfo>
<title>Building the Glasgow Functional Programming Tools Suite</title>
<author><othername>The GHC Team</othername></author>
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>
+ systems; see <xref linkend="winbuild"/> for Windows notes.</para>
</abstract>
-</artheader>
+</articleinfo>
<sect1 id="sec-getting">
scratch.</para>
<para>More information about our CVS repository can be found
- in <xref linkend="sec-cvs">.</para>
+ in <xref linkend="sec-cvs"/>.</para>
</listitem>
</varlistentry>
</variablelist>
<title>Getting access to the CVS Repository</title>
<para>You can access the repository in one of two ways:
- read-only (<xref linkend="cvs-read-only">), or read-write (<xref
- linkend="cvs-read-write">).</para>
+ read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
+ linkend="cvs-read-write"/>).</para>
<sect3 id="cvs-read-only">
<title>Remote Read-only CVS Access</title>
</listitem>
<listitem>
- <para>Now go to <xref linkend="cvs-first">.</para>
+ <para>Now go to <xref linkend="cvs-first"/>.</para>
</listitem>
</orderedlist>
</sect3>
<para>
- <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+ <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
</para>
you need at least the <literal>ghc</literal>,
<literal>hslibs</literal> and <literal>libraries</literal>
modules (for a full list of the projects available, see
- <xref linkend="projects">).</para>
+ <xref linkend="projects"/>).</para>
<para>Remember that if you do not have
<literal>happy</literal> and/or <literal>Alex</literal>
<listitem>
<para>Use an appropriate machine / operating system. <xref
- linkend="sec-port-info"> lists the supported platforms; if
+ linkend="sec-port-info"/> lists the supported platforms; if
yours isn't amongst these then you can try porting GHC (see
- <xref linkend="sec-porting-ghc">).</para>
+ <xref linkend="sec-porting-ghc"/>).</para>
</listitem>
<listitem>
<para>Be sure that the “pre-supposed” utilities are
- installed. <xref linkend="sec-pre-supposed">
+ 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
+ linkend="sec-build-pitfalls"/>). Also check the FAQ for the
version you're building, which is part of the User's Guide and
available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
site</ulink>.</para>
<para>GHC is required to build many of the tools, including
GHC itself. If you need to port GHC to your platform
because there isn't a binary distribution of GHC available,
- then see <xref linkend="sec-porting-ghc">.</para>
+ then see <xref linkend="sec-porting-ghc"/>.</para>
<para>Which version of GHC you need will depend on the
packages you intend to build. GHC itself will normally
<para>More tools are required if you want to format the documentation
that comes with GHC and other fptools projects. See <xref
- linkend="building-docs">.</para>
+ linkend="building-docs"/>.</para>
</sect2>
</sect1>
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>
+ 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
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
+ 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
<para>Change directory to
<constant>$(FPTOOLS_TOP)</constant> and
issue the command</para>
-<programlisting>autoreconf</programlisting>
+<screen>$ autoreconf</screen>
<indexterm><primary>autoreconf</primary></indexterm>
<para>(with no arguments). This GNU program (recursively) converts
<filename>$(FPTOOLS_TOP)/configure.ac</filename> and
<para>Runs the newly-created <command>configure</command>
script, thus:</para>
-<programlisting>./configure <optional><parameter>args</parameter></optional></programlisting>
+<screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
<para><command>configure</command>'s mission is to scurry
round your computer working out what architecture it has,
<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>
+ linkend="sec-source-tree"/>).</para>
</listitem>
<listitem>
<para>(Optional) Use <command>lndir</command> or
<command>mkshadowdir</command> to create a build tree.</para>
-<programlisting>$ cd myfptools
-$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</programlisting>
+<screen>$ cd myfptools
+$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
<para>(N.B. <command>mkshadowdir</command>'s first argument
is taken relative to its second.) You probably want to give
<para>Change directory to the build tree. Everything is
going to happen there now.</para>
-<programlisting>$ cd /scratch/joe-bloggs/myfptools-sun4</programlisting>
+<screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
</listitem>
<listitem>
<para>Prepare for system configuration:</para>
-<programlisting>$ autoreconf</programlisting>
+<screen>$ autoreconf</screen>
<para>(You can skip this step if you are starting from a
source distribution, and you already have
<listitem>
<para>Do system configuration:</para>
-<programlisting>$ ./configure</programlisting>
+<screen>$ ./configure</screen>
<para>Don't forget to check whether you need to add any
arguments to <literal>configure</literal>; for example, a
adding definitions for your desired configuration
options.</para>
-<programlisting>$ emacs mk/build.mk</programlisting>
+<screen>$ emacs mk/build.mk</screen>
</listitem>
</orderedlist>
<para>is only available in the root directory
<constant>$(FPTOOLS_TOP)</constant>; it has
been discussed in <xref
- linkend="sec-build-config">.</para>
+ linkend="sec-build-config"/>.</para>
</listitem>
</varlistentry>
<command>make</command> is going to rebuild everything anyway,
the following hack may be useful:</para>
-<programlisting>gmake FAST=YES</programlisting>
+<screen>$ gmake FAST=YES</screen>
<para>This tells the make system to ignore dependencies and just
build what you tell it to. In other words, it's equivalent to
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">.
+ boilerplate in more detail in <xref linkend="sec-boiler"/>.
<indexterm><primary>include, directive in
Makefiles</primary></indexterm> <indexterm><primary>Makefile
inclusion</primary></indexterm></para>
(the executable binary to be built). We will discuss in
more detail what the “standard variables” are,
and how they affect what happens, in <xref
- linkend="sec-targets">.</para>
+ linkend="sec-targets"/>.</para>
<para>The definition for <constant>SRCS</constant> uses the
useful GNU <command>make</command> construct
<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
+ linkend="sec-standard-targets"/>). Why, you ask, can't this
standard code be part of
<filename>boilerplate.mk</filename>? Good question. We
discuss the reason later, in <xref
- linkend="sec-boiler-arch">.</para>
+ linkend="sec-boiler-arch"/>.</para>
<para>You do not <emphasis>have</emphasis> to
<literal>include</literal> 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>
+ linkend="sec-targets"/>).</para>
</listitem>
</orderedlist>
rare.) To give you the idea, here's part of the directory
structure for the (rather large) GHC project:</para>
-<screen>$(FPTOOLS_TOP)/ghc/
+<programlisting>$(FPTOOLS_TOP)/ghc/
Makefile
mk/
boilerplate.mk
Makefile
parser/...source files for parser...
renamer/...source files for renamer...
- ...etc...</screen>
+ ...etc...</programlisting>
<para>The sub-directories <filename>docs</filename>,
<filename>driver</filename>, <filename>compiler</filename>, and
<listitem>
<para><filename>target.mk</filename> contains
<command>make</command> rules for the standard targets
- described in <xref linkend="sec-standard-targets">. These
+ 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
</term>
<listitem>
<para>is the build configuration file we discussed at
- length in <xref linkend="sec-build-config">.</para>
+ length in <xref linkend="sec-build-config"/>.</para>
</listitem>
</varlistentry>
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>
+ <xref linkend="sec-suffix"/>.</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>defines standard pattern rules—see <xref
- linkend="sec-suffix">.</para>
+ linkend="sec-suffix"/>.</para>
</listitem>
</varlistentry>
</variablelist>
<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
+ standard way. (<xref linkend="sec-ways"/> dicusses
multi-way compilation.)</para>
</listitem>
</varlistentry>
<para>extra options to pass to all C compilations. This
is intended for command line use, thus:</para>
-<programlisting>gmake libHS.a EXTRA_CC_OPTS="-v"</programlisting>
+<screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
</listitem>
</varlistentry>
</variablelist>
<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
+ 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
<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
+ the standard targets (<xref linkend="sec-standard-targets"/> that
simply invokes <command>make</command> recursively in each of
the sub-directories.</para>
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
+ 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>
supported (or perhaps has been supported in the past, but
currently isn't). This is the easiest type of porting job,
but it still requires some careful bootstrapping. Proceed to
- <xref linkend="sec-booting-from-hc">.</para>
+ <xref linkend="sec-booting-from-hc"/>.</para>
</listitem>
<listitem>
<para>Your system's hardware architecture isn't supported by
GHC. This will be a more difficult port (though by comparison
perhaps not as difficult as porting gcc). Proceed to <xref
- linkend="unregisterised-porting">.</para>
+ linkend="unregisterised-porting"/>.</para>
</listitem>
</itemizedlist>
supplied on the GHC download page, otherwise you'll have to
compile some up yourself, or start from
<emphasis>unregisterised</emphasis> HC files - see <xref
- linkend="unregisterised-porting">.</para>
+ linkend="unregisterised-porting"/>.</para>
<para>The following steps should result in a working GHC build
with full libraries:</para>
command will execute the whole build process (it won't
install yet):</para>
-<screen>foo% distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
+<screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
<indexterm><primary>--hc-build</primary></indexterm>
<para>By default, the installation directory is
build process, you can install the resulting system, as
normal, with</para>
-<screen>foo% make install</screen>
+<screen>$ make install</screen>
</listitem>
</itemizedlist>
</sect2>
from the intermediate C files we generated above. The
process of bootstrapping from C files is automated by the
script in <literal>distrib/hc-build</literal>, and is
- described in <xref linkend="sec-booting-from-hc">.</para>
+ described in <xref linkend="sec-booting-from-hc"/>.</para>
<screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
</term>
<listitem>
<para>Macros that cooperate with the mangler (see <xref
- linkend="sec-mangler">) to make proper tail-calls
+ linkend="sec-mangler"/>) to make proper tail-calls
work.</para>
</listitem>
</varlistentry>
</itemizedlist>
-and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"> for information about
+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>
+<screen>$ cd ghc/compiler
+$ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
</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...
+<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>
Win95/Win98 behave the same, and WinNT/Win2k behave the same.
</para>
<para>
-Make sure you read the preceding section on platforms (<xref linkend="platforms">)
+Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
before reading section.
You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
</para></listitem>
<listitem> <para>
-See the notes in <xref linkend="msys-install"> about <command>find</command> and <command>bzip</command>,
+See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
which apply to Cygwin too.
</para></listitem>
</itemizedlist>
there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
the setting of the environment variable $HOME</emphasis>. If the home directory is
bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
-<programlisting>ssh -v cvs.haskell.org</programlisting>
+<screen>ssh -v cvs.haskell.org</screen>
which makes <command>ssh</command> print out information about its activity.
</para>
<para> You can fix this problem, either by correcting the home-directory field in
Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
build it from the source distribution using
-<programlisting>./configure
-make
-make install</programlisting>
+<screen>$ ./configure
+$ make
+$ make install</screen>
This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
on MSYS).
Make sure the installation directory is in your
<listitem>
<para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">).
+generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
Just pick up a mingw bundle at
<ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
We install it in <filename>c:/mingw</filename>.
<listitem>
<para> Finally, check out a copy of GHC sources from
-the CVS repository, following the instructions above (<xref linkend="cvs-access">).
+the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
</para>
</listitem>
</itemizedlist>
<sect2><title>Building GHC</title>
<para>OK!
-Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">);
+Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
the bullets below only tell
you about Windows-specific wrinkles.</para>
<itemizedlist>
After <command>autoreconf</command> run <command>./configure</command> in
<filename>fptools/</filename> thus:
-<screen>./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
+<screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
This is the point at which you specify that you are building GHC-mingw
-(see <xref linkend="ghc-mingw">). </para>
+(see <xref linkend="ghc-mingw"/>). </para>
<para> Both these options are important! It's possible to get into
trouble using the wrong C compiler!</para>
</para>
<para>
-If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
+If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
you'll have to do something more like:
-<screen>./configure --with-gcc=...the Cygwin gcc...</screen>
+<screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
</para>
</listitem>
<listitem><para> You almost certainly want to set
<programlisting>SplitObjs = NO</programlisting>
-in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
+in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
This tells the build system not to split each library into a myriad of little object files, one
for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
it dramatically increases the time taken to build the libraries in the first place.
projects / ghc-hetmet.git / commitdiff