</listitem>
<listitem>
- <para>Use an appropriate machine / operating system. <xref
- linkend="sec-port-info"/> lists the supported platforms; if
- yours isn't amongst these then you can try porting GHC (see
- <xref linkend="sec-porting-ghc"/>).</para>
- </listitem>
+ <para>Use an appropriate machine / operating system. <ulink
+ url="http://hackage.haskell.org/trac/ghc/wiki/Platforms">GHC
+ Platform Support</ulink> lists the currently supported
+ platforms; if yours isn't amongst these then you can try
+ porting GHC (see <xref linkend="sec-porting-ghc"/>).</para>
+ </listitem>
<listitem>
<para>Be sure that the “pre-supposed” utilities are
</orderedlist>
</sect1>
- <sect1 id="sec-port-info">
- <title>What machines GHC runs on</title>
-
-<indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
-<indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
-<indexterm><primary>platforms</primary><secondary>supported</secondary></indexterm>
-
- <para>A “platform” is a
- architecture/manufacturer/operating-system combination, such as
- <literal>sparc-sun-solaris2</literal>. Other common ones are
- <literal>alpha-dec-osf2</literal>,
- <literal>hppa1.1-hp-hpux9</literal>,
- <literal>i386-unknown-linux</literal>,
- <literal>i386-unknown-solaris2</literal>,
- <literal>i386-unknown-freebsd</literal>,
- <literal>i386-unknown-cygwin32</literal>,
- <literal>m68k-sun-sunos4</literal>,
- <literal>mips-sgi-irix5</literal>,
- <literal>sparc-sun-sunos4</literal>,
- <literal>sparc-sun-solaris2</literal>,
- <literal>powerpc-ibm-aix</literal>.</para>
-
- <para>Some libraries may only work on a limited number of
- platforms; for example, a sockets library is of no use unless the
- operating system supports the underlying BSDisms.</para>
-
- <indexterm><primary>fully-supported platforms</primary></indexterm>
- <indexterm><primary>native-code generator</primary></indexterm>
- <indexterm><primary>registerised ports</primary></indexterm>
- <indexterm><primary>unregisterised ports</primary></indexterm>
-
- <para>The GHC hierarchy of Porting Goodness: (a) Best is a
- native-code generator; (b) next best is a
- “registerised” port; (c) the bare minimum is an
- “unregisterised” port.
- (“Unregisterised” is so terrible that we won't say
- more about it).</para>
-
- <para>Here's everything that's known about GHC ports. We
- identify platforms by their “canonical”
- CPU/Manufacturer/OS triple.</para>
-
- <variablelist>
- <varlistentry>
- <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
- <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>
- </term>
- <listitem>
- <para>The OSF port is currently working (as of GHC version
- 5.02.1) and well supported. The native code generator is
- currently non-working. Other operating systems will
- require some minor porting.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sparc-sun-sunos4
- <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
- </term>
- <listitem>
- <para>Probably works with minor tweaks, hasn't been tested
- for a while.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sparc-sun-solaris2
- <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
- </term>
- <listitem>
- <para>Fully supported (at least for Solaris 2.7 and 2.6),
- including native-code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sparc-unknown-openbsd
- <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
- </term>
- <listitem>
- <para>Supported, including native-code generator. The
- same should also be true of NetBSD</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
- <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
- </term>
- <listitem>
- <para>A registerised port is available for version 4.08,
- but GHC hasn't been built on that platform since (as far
- as we know). No native-code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-linux (PCs running Linux, ELF binary format)
- <indexterm><primary>i386-*-linux</primary></indexterm>
- </term>
- <listitem>
- <para>GHC works registerised and has a native code
- generator. You <emphasis>must</emphasis> have GCC 2.7.x
- or later. NOTE about <literal>glibc</literal> versions:
- GHC binaries built on a system running <literal>glibc
- 2.0</literal> won't work on a system running
- <literal>glibc 2.1</literal>, and vice versa. In general,
- don't expect compatibility between
- <literal>glibc</literal> versions, even if the shared
- library version hasn't changed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
- <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
- </term>
- <listitem>
- <para>GHC works registerised. Pre-built packages are
- available in the native package format, so if you just
- need binaries you're better off just installing the
- package (it might even be on your installation
- CD!).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-openbsd (PCs running OpenBSD)
- <indexterm><primary>i386-unknown-openbsd</primary></indexterm>
- </term>
- <listitem>
- <para>Supported, with native code generator. Packages are
- available through the ports system in the native package
- format.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-netbsd (PCs running NetBSD)
- <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
- </term>
- <listitem>
- <para>Will require some minor porting effort, but should
- work registerised.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>i386-unknown-mingw32 (PCs running Windows)
- <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
- </term>
- <listitem>
- <para>Fully supported under Win9x, WinNT, Win2k, and
- WinXP. Includes a native code generator. Building from
- source requires a recent <ulink
- url="http://www.cygwin.com/">Cygwin</ulink> distribution
- to be installed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ia64-unknown-linux
- <indexterm><primary>ia64-unknown-linux</primary></indexterm>
- </term>
- <listitem>
- <para>Supported, except there is no native code
- generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>x86_64-unknown-linux
- <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
- </term>
-<term>amd64-unknown-openbsd
- <indexterm><primary>amd64-unknown-linux</primary></indexterm>
- </term>
- <listitem>
- <para>Fully supported, with a native code generator and GHCi.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>mips-sgi-irix5
- <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
- </term>
- <listitem>
- <para>Port has worked in the past, but hasn't been tested
- for some time (and will certainly have rotted in various
- ways). As usual, we don't have access to machines and
- there hasn't been an overwhelming demand for this port,
- but feel free to get in touch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>mips64-sgi-irix6
- <indexterm><primary>mips-sgi-irix6</primary></indexterm>
- </term>
- <listitem>
- <para>GHC currently works unregisterised.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>powerpc-ibm-aix
- <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
- </term>
- <listitem>
- <para>Port currently doesn't work, needs some minimal
- porting effort. As usual, we don't have access to
- machines and there hasn't been an overwhelming demand for
- this port, but feel free to get in touch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>powerpc-apple-darwin
- <indexterm><primary>powerpc-apple-darwin</primary></indexterm>
- </term>
- <listitem>
- <para>Supported registerised. Native code generator is
- almost working.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>powerpc-apple-linux
- <indexterm><primary>powerpc-apple-linux</primary></indexterm>
- </term>
- <listitem>
- <para>Not supported (yet).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Various other systems have had GHC ported to them in the
- distant past, including various Motorola 68k boxes. The 68k
- support still remains, but porting to one of these systems will
- certainly be a non-trivial task.</para>
- </sect1>
-
<sect1 id="sec-pre-supposed">
<title>Installing pre-supposed utilities</title>
<indexterm><primary>GHC, pre-supposed</primary></indexterm>
</term>
<listitem>
- <para>GHC is required to build many of the tools, including
- GHC itself. If you need to port GHC to your platform
- because there isn't a binary distribution of GHC available,
- then see <xref linkend="sec-porting-ghc"/>.</para>
-
- <para>Which version of GHC you need will depend on the
- packages you intend to build. GHC itself will normally
- build using one of several older versions of itself - check
- the announcement or release notes for details.</para>
+ <para>GHC is required to build GHC, because GHC itself is
+ written in Haskell, and uses GHC extensions. It is possible
+ to build GHC using just a C compiler, and indeed some
+ distributions of GHC do just that, but it isn't the best
+ supported method, and you may encounter difficulties. Full
+ instructions are in <xref linkend="sec-porting-ghc"/>.</para>
+
+ <para>GHC can be built using either an earlier released
+ version of GHC (currently 5.04 and later are supported), or
+ bootstrapped using a GHC built from exactly the same
+ sources. Note that this means you cannot in general build
+ GHC using an arbitrary development snapshot, or a build from
+ say last week. It might work, it might not - we don't
+ guarantee anything. To be on the safe side, start your
+ build using the most recently released stable version of
+ GHC.</para>
</listitem>
</varlistentry>
<indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
</term>
<listitem>
- <para>The fptools build system makes heavy use of features
+ <para>The GHC build system makes heavy use of features
specific to GNU <command>make</command>, so you must have
- this installed in order to build any of the fptools
- suite.</para>
+ this installed in order to build GHC.</para>
<para>NB. it has been reported that version 3.79 no longer
works to build GHC, and 3.80 is required.</para>
modify the compiler and/or you're using a darcs checkout, then you
need Happy.</para>
- <para>Happy version 1.15 is currently required to build GHC.</para>
-
- <para>Happy is written in
- Haskell, and is a project in the CVS repository
- (<literal>fptools/happy</literal>). It can be built from
- source, but bear in mind that you'll need GHC installed in
- order to build it. To avoid the chicken/egg problem,
- install a binary distribution of either Happy or GHC to get
- started. Happy distributions are available from <ulink url="http://www.haskell.org/happy/">Happy's Web
- Page</ulink>.</para>
+ <para>Happy version 1.15 is currently required to build GHC.
+ Grab a copy from <ulink
+ url="http://www.haskell.org/happy/">Happy's Web
+ Page</ulink>.</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
- <para>One <literal>fptools</literal> project is worth a quick note
- at this point, because it is useful for all the others:
- <literal>glafp-utils</literal> contains several utilities which
- aren't particularly Glasgow-ish, but Occasionally Indispensable.
- Like <command>lndir</command> for creating symbolic link
- trees.</para>
-
<sect2 id="pre-supposed-gph-tools">
<title>Tools for building parallel GHC (GPH)</title>
</listitem>
</varlistentry>
</variablelist>
- </sect2>
-
- <sect2 id="pre-supposed-other-tools">
- <title>Other useful tools</title>
- <variablelist>
- <varlistentry>
- <term>Flex
- <indexterm><primary>pre-supposed: flex</primary></indexterm>
- <indexterm><primary>flex, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>This is a quite-a-bit-better-than-Lex lexer. Used
- to build a couple of utilities in
- <literal>glafp-utils</literal>. Depending on your
- operating system, the supplied <command>lex</command> may
- or may not work; you should get the GNU version.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>More tools are required if you want to format the documentation
- that comes with GHC and other fptools projects. See <xref
+ <para>More tools are required if you want to format the
+ documentation that comes with GHC. See <xref
linkend="building-docs"/>.</para>
</sect2>
</sect1>
<title>Quick start for GHC developers</title>
<para>This section is a copy of the file
- <literal>ghc/HACKING</literal> from the GHC source tree. It describes
+ <literal>HACKING</literal> from the GHC source tree. It describes
how to get started with setting up your build tree for developing GHC
or its libraries, and how to start building.</para>
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>
-
- <itemizedlist>
- <listitem>
- <para><filename>Makefile</filename>: the root
- Makefile.</para>
- </listitem>
-
- <listitem>
- <para><filename>mk/</filename>: the directory that contains
- the main Makefile code, shared by all the
- <literal>fptools</literal> software.</para>
- </listitem>
-
- <listitem>
- <para><filename>configure.ac</filename>,
- <filename>config.sub</filename>,
- <filename>config.guess</filename>: these files support the
- configuration process.</para>
- </listitem>
-
- <listitem>
- <para><filename>install-sh</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <para>All the other directories are individual
- <emphasis>projects</emphasis> of the <literal>fptools</literal>
- system—for example, the Glasgow Haskell Compiler
- (<literal>ghc</literal>), the Happy parser generator
- (<literal>happy</literal>), the <literal>nofib</literal>
- benchmark suite, and so on. You can have zero or more of these.
- Needless to say, some of them are needed to build others.</para>
-
- <para>The important thing to remember is that even if you want
- only one project (<literal>happy</literal>, say), you must have
- a source tree whose root directory contains
- <filename>Makefile</filename>, <filename>mk/</filename>,
- <filename>configure.ac</filename>, and the project(s) you want
- (<filename>happy/</filename> in this case). You cannot get by
- with just the <filename>happy/</filename> directory.</para>
+ <sect2>
+ <title>History</title>
+
+ <para>First, a historical note. The GHC build system used to be
+ called "fptools": a generic build system used to build multiple
+ projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a
+ concept of the generic project-independent parts, and
+ project-specific parts that resided in a project
+ subdirectory.</para>
+
+ <para>Nowadays, most of these other projects are using <ulink
+ url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded
+ away, and GHC is the only regular user of the fptools build
+ system. We decided therefore to simplify the situation for
+ developers, and specialise the build system for GHC. This
+ resulted in a simpler organisation of the source tree and the
+ build system, which hopefully makes the whole thing easier to
+ understand.</para>
+
+ <para>You might find old comments that refer to "projects" or
+ "fptools" in the documentation and/or source; please let us know
+ if you do.</para>
</sect2>
<sect2>
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
+ <filename>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 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>.
+ must be (a linked copy of) the root directory of the GHC source
+ tree.. Inside Makefiles, the root of your build tree is called
+ <constant>$(GHC_TOP)</constant><indexterm><primary>GHC_TOP</primary></indexterm>.
In the rest of this document path names are relative to
- <constant>$(FPTOOLS_TOP)</constant> unless
+ <constant>$(GHC_TOP)</constant> unless
otherwise stated. For example, the file
- <filename>ghc/mk/target.mk</filename> is actually
- <filename>$(FPTOOLS_TOP)/ghc/mk/target.mk</filename>.</para>
+ <filename>mk/target.mk</filename> is actually
+ <filename>$(GHC_TOP)/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
+ <para>When you build GHC 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
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>
+ 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
rather than darcs sources, you can skip this step.</para>
<para>Change directory to
- <constant>$(FPTOOLS_TOP)</constant> and
+ <constant>$(GHC_TOP)</constant> and
issue the command</para>
<screen>$ autoreconf</screen>
<indexterm><primary>autoreconf</primary></indexterm>
<para>(with no arguments). This GNU program (recursively) converts
- <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
- <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
+ <filename>$(GHC_TOP)/configure.ac</filename> and
+ <filename>$(GHC_TOP)/aclocal.m4</filename>
to a shell script called
- <filename>$(FPTOOLS_TOP)/configure</filename>.
+ <filename>$(GHC_TOP)/configure</filename>.
If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
then delete the latter and try again. Note that you must use <command>autoreconf</command>,
and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
a message like "No rule to make target 'mk/config.h.in'".
</para>
- <para>Some projects, including GHC, have their own configure script.
+ <para>Some parts of the source tree, particularly
+ libraries, have their own configure script.
<command>autoreconf</command> takes care of that, too, so all you have
to do is calling <command>autoreconf</command> in the top-level directory
- <filename>$(FPTOOLS_TOP)</filename>.</para>
+ <filename>$(GHC_TOP)</filename>.</para>
<para>These steps are completely platform-independent; they just mean
that the human-written files (<filename>configure.ac</filename> and
<para>Specifies the path to any installed Haskell
compiler. This compiler will be used for compiling
generic Haskell code. The default is to use
- <literal>ghc</literal>.</para>
+ <literal>ghc</literal>. (NOTE: I'm not sure it
+ actually works to specify a compiler other than GHC
+ here; unless you really know what you're doing I
+ suggest not using this option at all.)</para>
</listitem>
</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
+ GHC 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
includes <filename>build.mk</filename> after
<filename>config.mk</filename>.)</para>
- <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
- that can serve as a starting point for your <filename>build.mk</filename>.</para>
+ <para>For your convenience, there's a file called
+ <filename>build.mk.sample</filename> that can serve as a starting
+ point for your <filename>build.mk</filename>.</para>
<para>For example, <filename>config.mk.in</filename> contains
the definition:</para>
-<programlisting>GhcHcOpts=-O -Rghc-timing</programlisting>
+<programlisting>GhcHcOpts=-Rghc-timing</programlisting>
<para>The accompanying comment explains that this is the list of
flags passed to GHC when building GHC itself. For doing
enable debugging code. So you would add the following to
<filename>build.mk</filename>:</para>
- <para>or, if you prefer,</para>
-
<programlisting>GhcHcOpts += -DDEBUG</programlisting>
<para>GNU <command>make</command> allows existing definitions to
have new text appended using the “<literal>+=</literal>”
- operator, which is quite a convenient feature.)</para>
+ operator, which is quite a convenient feature.</para>
+
+ <para>Haskell compilations by default have <literal>-O</literal>
+ turned on, by virtue of this setting from
+ <filename>config.mk</filename>:</para>
+
+<programlisting>SRC_HC_OPTS += -H16m -O</programlisting>
+
+ <para><literal>SRC_HC_OPTS</literal> means "options for HC from
+ the source tree", where HC stands for Haskell Compiler.
+ <literal>SRC_HC_OPTS</literal> are added to every Haskell
+ compilation. To turn off optimisation, you could add this to
+ <filename>build.mk</filename>:</para>
- <para>If you want to remove the <literal>-O</literal> as well (a
- good idea when developing, because the turn-around cycle gets a
- lot quicker), you can just override
- <literal>GhcLibHcOpts</literal> altogether:</para>
+<programlisting>SRC_HC_OPTS = -H16m -O0</programlisting>
-<programlisting>GhcHcOpts=-DDEBUG -Rghc-timing</programlisting>
+ <para>Or you could just add <literal>-O0</literal> to
+ <literal>GhcHcOpts</literal> to turn off optimisation for the
+ compiler. See <xref linkend="quick-start" /> for some more
+ suggestions.</para>
<para>When reading <filename>config.mk.in</filename>, remember
that anything between “@...@” signs is going to be substituted
<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
+ <constant>GHC_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">
<listitem>
<para> Get your source tree from somewhere (darcs 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>
+ <filename>myghc</filename> (it does not have to be
+ called <filename>ghc</filename>).</para>
</listitem>
<listitem>
-
<para>(Optional) Use <command>lndir</command> or
<command>mkshadowdir</command> to create a build tree.</para>
-<screen>$ cd myfptools
-$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4</screen>
+<screen>$ cd myghc
+$ mkshadowdir . /scratch/joe-bloggs/myghc-x86</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>
-<screen>$ cd /scratch/joe-bloggs/myfptools-sun4</screen>
+<screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
</listitem>
<para>Create the file <filename>mk/build.mk</filename>,
adding definitions for your desired configuration
options.</para>
-
-<screen>$ emacs mk/build.mk</screen>
</listitem>
</orderedlist>
<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>
+ <command>make clean; make</command>, because configuration
+ option changes could affect anything—but in practice you
+ are likely to know what's affected.</para>
</sect2>
<sect2>
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>
+ must use GNU <command>make</command></emphasis>. On some
+ systems (eg. FreeBSD) this is called <command>gmake</command>,
+ whereas on others it is the standard <command>make</command>
+ command. In this document we will always refer to it as
+ <command>make</command>; please substitute with
+ <command>gmake</command> if your system requires it. If you use
+ a the wrong <command>make</command> you will get all sorts of
+ error messages (but no damage) because the GHC
<command>Makefiles</command> use GNU <command>make</command>'s
facilities extensively.</para>
<para>To just build the whole thing, <command>cd</command> to
- the top of your <literal>fptools</literal> tree and type
- <command>gmake</command>. This will prepare the tree and build
- the various projects in the correct order.</para>
+ the top of your build tree and type <command>make</command>.
+ This will prepare the tree and build the various parts in the
+ correct order, resulting in a complete build of GHC that can
+ even be used directly from the tree, without being installed
+ first.</para>
</sect2>
<sect2 id="sec-bootstrapping">
<para>Note that when doing a bootstrap, the stage 1 compiler
must be built, followed by the runtime system and libraries, and
then the stage 2 compiler. The correct ordering is implemented
- by the top-level fptools <filename>Makefile</filename>, so if
- you want everything to work automatically it's best to start
- <command>make</command> from the top of the tree. When building
- GHC, the top-level fptools <filename>Makefile</filename> is set
- up to do a 2-stage bootstrap by default (when you say
- <command>make</command>). Some other targets it supports
- are:</para>
+ by the top-level <filename>Makefile</filename>, so if you want
+ everything to work automatically it's best to start
+ <command>make</command> from the top of the tree. The top-level
+ <filename>Makefile</filename> is set up to do a 2-stage
+ bootstrap by default (when you say <command>make</command>).
+ Some other targets it supports are:</para>
<variablelist>
<varlistentry>
<replaceable>n</replaceable> is the stage to install.</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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>dist</literal></term>
+ <listitem>
+ <para>make a source distribution. Note that this target
+ does “make distclean” as part of its work;
+ don't use it if you want to keep what you've built.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>The top-level <filename>Makefile</filename> also arranges
<para>The <literal>stage1</literal>, <literal>stage2</literal>
and <literal>stage3</literal> targets also work in the
- <literal>ghc/compiler</literal> directory, but don't forget that
+ <literal>compiler</literal> directory, but don't forget that
each stage requires its own <literal>make boot</literal> step:
for example, you must do</para>
<screen>$ make boot stage=2</screen>
<para>before <literal>make stage2</literal> in
- <literal>ghc/compiler</literal>.</para>
+ <literal>compiler</literal>.</para>
</sect2>
<sect2 id="sec-standard-targets">
<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
+ for the real work. Notably, it does <command>make
depend</command> in all directories that contain programs.
It also builds the necessary tools for compilation to
proceed.</para>
<para>Invoking the <literal>boot</literal> target
explicitly is not normally necessary. From the top-level
- <literal>fptools</literal> directory, invoking
- <literal>gmake</literal> causes <literal>gmake boot
- all</literal> to be invoked in each of the project
- subdirectories, in the order specified by
- <literal>$(AllTargets)</literal> in
- <literal>config.mk</literal>.</para>
+ directory, invoking <literal>make</literal> causes
+ <literal>make boot</literal> to be invoked in various
+ subdirectories first, in the right order. Unless you
+ really know what you are doing, it is best to always say
+ <literal>make</literal> from the top level first.</para>
<para>If you're working in a subdirectory somewhere and
- need to update the dependencies, <literal>gmake
+ need to update the dependencies, <literal>make
boot</literal> is a good way to do it.</para>
</listitem>
</varlistentry>
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>
+ <command>make</command> alone is generally the same as
+ typing <command>make all</command>.</para>
</listitem>
</varlistentry>
<term><literal>uninstall</literal></term>
<listitem>
<para>reverses the effect of
- <literal>install</literal>.</para>
+ <literal>install</literal> (WARNING: probably doesn't work).</para>
</listitem>
</varlistentry>
<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
+ generated by <command>make boot</command>. Also preserve
files that could be made by building, but normally aren't
because the distribution comes with them.</para>
</listitem>
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>
+ <para>After a <literal>maintainer-clean</literal>, a
+ <literal>configure</literal> will be necessary before
+ building again.</para>
</listitem>
</varlistentry>
</variablelist>
<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
file is automatically included by every Makefile.</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><literal>binary-dist</literal></term>
- <listitem>
- <para>make a binary distribution. This is the target we
- use to build the binary distributions of GHC and
- Happy.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>dist</literal></term>
- <listitem>
- <para>make a source distribution. Note that this target
- does “make distclean” as part of its work;
- don't use it if you want to keep what you've built.</para>
- </listitem>
- </varlistentry>
</variablelist>
- <para>Most <filename>Makefile</filename>s have targets other
+ <para>Some <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>
+ <title>Using GHC from the build tree</title>
- <para>If you want to build GHC (say) and just use it direct from
- the build tree without doing <literal>make install</literal>
- first, you can run the in-place driver script:
- <filename>ghc/compiler/ghc-inplace</filename>.</para>
+ <para>If you want to build GHC and just use it direct from the
+ build tree without doing <literal>make install</literal> first,
+ you can run the in-place driver script. To run the stage 1
+ compiler, use <filename>compiler/stage1/ghc-inplace</filename>,
+ stage 2 is <filename>compiler/stage2/ghc-inplace</filename>, and
+ so on.</para>
<para> Do <emphasis>NOT</emphasis> use
- <filename>ghc/compiler/ghc</filename>, or
- <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
+ <filename>compiler/stage1/ghc</filename>, or
+ <filename>compiler/stage1/ghc-6.xx</filename>, as these are the
scripts intended for installation, and contain hard-wired paths
to the installed libraries, rather than the libraries in the
build tree.</para>
-
- <para>Happy can similarly be run from the build tree, using
- <filename>happy/src/happy-inplace</filename>, and similarly for
- Alex and Haddock.</para>
</sect2>
<sect2>
<command>make</command> is going to rebuild everything anyway,
the following hack may be useful:</para>
-<screen>$ gmake FAST=YES</screen>
+<screen>$ make 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
<indexterm><primary>makefile architecture</primary></indexterm>
<para><command>make</command> is great if everything
- works—you type <command>gmake install</command> and lo! the
+ works—you type <command>make 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
</sect2>
<sect2>
- <title>A small project</title>
+ <title>A small example</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> for an imaginary small program,
+ <literal>small</literal>. Each program or library in the GHC
+ source tree typically has its own directory, in this case we'll
+ use <filename>$(GHC_TOP)/small</filename>.
+ Inside the <filename>small/</filename> directory there will be a
<filename>Makefile</filename>, looking something like
this:</para>
<indexterm><primary>Makefile, minimal</primary></indexterm>
-<programlisting># Makefile for fptools project "small"
-
+<programlisting># Makefile for program "small"
TOP = ..
include $(TOP)/mk/boilerplate.mk
-SRCS = $(wildcard *.lhs) $(wildcard *.c)
HS_PROG = small
include $(TOP)/target.mk</programlisting>
</para>
</footnote>
- a file of “boilerplate” code from the level
- above (which in this case will be
- <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
+ a file of “boilerplate” code from the top level
+ <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
<para>Before the <literal>include</literal> statement, you
must define the <command>make</command> variable
<constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
- to be the directory containing the <filename>mk</filename>
+ to be the top-level directory of the source tree, containing
+ the <filename>mk</filename>
directory in which the <filename>boilerplate.mk</filename>
file is. It is <emphasis>not</emphasis> OK to simply say</para>
<programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
-
<para>Why? Because the <filename>boilerplate.mk</filename>
file needs to know where it is, so that it can, in turn,
<literal>include</literal> other files. (Unfortunately,
when an <literal>include</literal>d file does an
<literal>include</literal>, the filename is treated relative
- to the directory in which <command>gmake</command> is being
+ to the directory in which <command>make</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
refers to itself.</emphasis> It is up to the
<filename>Makefile</filename> doing the
<literal>include</literal> to ensure this is the case.</para>
-
- <para>Files intended for inclusion in other
- <filename>Makefile</filename>s are written to have the
- following property: <emphasis>after
- <filename>foo.mk</filename> is <literal>include</literal>d,
- it leaves <constant>TOP</constant> containing the same value
- as it had just before the <literal>include</literal>
- statement</emphasis>. In our example, this invariant
- guarantees that the <literal>include</literal> for
- <filename>target.mk</filename> will look in the same
- directory as that for <filename>boilerplate.mk</filename>.</para>
</listitem>
<listitem>
- <para> The second section defines the following standard
- <command>make</command> variables:
- <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
- (the source files from which is to be built), and
+ <para> The second section defines the standard
+ <command>make</command> variable
<constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
(the executable binary to be built). We will discuss in
more detail what the “standard variables” are,
and how they affect what happens, in <xref
linkend="sec-targets"/>.</para>
-
- <para>The definition for <constant>SRCS</constant> uses the
- useful GNU <command>make</command> construct
- <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
- which expands to a list of all the files matching the
- pattern <literal>pat</literal> in the current directory. In
- this example, <constant>SRCS</constant> is set to the list
- of all the <filename>.lhs</filename> and
- <filename>.c</filename> files in the directory. (Let's
- suppose there is one of each, <filename>Foo.lhs</filename>
- and <filename>Baz.c</filename>.)</para>
</listitem>
<listitem>
<para>The last section includes a second file of standard
code, called
<filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
- It contains the rules that tell <command>gmake</command> how
+ It contains the rules that tell <command>make</command> how
to make the standard targets (<xref
linkend="sec-standard-targets"/>). Why, you ask, can't this
standard code be part of
<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
+ you say <command>make all</command>, the following things
happen:</para>
<itemizedlist>
<listitem>
- <para><command>gmake</command> figures out that the object
- files are <filename>Foo.o</filename> and
- <filename>Baz.o</filename>.</para>
+ <para><command>make</command> looks in the current directory
+ to see what source files it can find
+ (eg. <filename>Foo.hs</filename>,
+ <filename>Baz.c</filename>), and from that it figures out
+ what object files need to be built
+ (eg. <filename>Foo.o</filename>,
+ <filename>Baz.o</filename>). Because source files are found
+ and used automatically, omitting them from a program or
+ library has to be done manually (see
+ <literal>EXCLUDED_SRCS</literal> in <xref
+ linkend="sec-boiler" />).</para>
</listitem>
<listitem>
<para>It uses a boilerplate pattern rule to compile
- <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
+ <filename>Foo.hs</filename> to <filename>Foo.o</filename>
using a Haskell compiler. (Which one? That is set in the
build configuration.)</para>
</listitem>
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
+ <command>make</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>
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>
-
-<programlisting>$(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...</programlisting>
-
- <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>$(FPTOOLS_TOP)/ghc</filename>.
- It does most of its work by recursively invoking
- <command>gmake</command> on the <filename>Makefile</filename>s
- in the sub-directories. We say that
- <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
- <filename>Makefile</filename></emphasis>, because it does little
- except organise its children, while the
- <filename>Makefile</filename>s in the sub-directories are all
- <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
- principle the sub-directories might themselves contain a
- non-leaf <filename>Makefile</filename> and several
- sub-sub-directories, but that does not happen in GHC.)</para>
-
- <para>The <filename>Makefile</filename> in
- <filename>ghc/compiler</filename> is considered a leaf
- <filename>Makefile</filename> even though the
- <filename>ghc/compiler</filename> has sub-directories, because
- these sub-directories do not themselves have
- <filename>Makefile</filename>s in them. They are just used to
- structure the collection of modules that make up GHC, but all
- are managed by the single <filename>Makefile</filename> in
- <filename>ghc/compiler</filename>.</para>
-
- <para>You will notice that <filename>ghc/</filename> also
- contains a directory <filename>ghc/mk/</filename>. It contains
- GHC-specific <filename>Makefile</filename> boilerplate code.
- More precisely:</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>ghc/mk/boilerplate.mk</filename> is included
- at the top of <filename>ghc/Makefile</filename>, and of all
- the leaf <filename>Makefile</filename>s in the
- sub-directories. It in turn <literal>include</literal>s the
- main boilerplate file
- <filename>mk/boilerplate.mk</filename>.</para>
- </listitem>
-
- <listitem>
- <para><filename>ghc/mk/target.mk</filename> is
- <literal>include</literal>d at the bottom of
- <filename>ghc/Makefile</filename>, and of all the leaf
- <filename>Makefile</filename>s in the sub-directories. It
- in turn <literal>include</literal>s the file
- <filename>mk/target.mk</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <para>So these two files are the place to look for GHC-wide
- customisation of the standard boilerplate.</para>
- </sect2>
-
<sect2 id="sec-boiler-arch">
<title>Boilerplate architecture</title>
<indexterm><primary>boilerplate architecture</primary></indexterm>
<listitem>
<para><emphasis>Standard pattern rules</emphasis> that
- tell <command>gmake</command> how to construct one file
+ tell <command>make</command> how to construct one file
from another.</para>
</listitem>
</itemizedlist>
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>
+ <filename>Makefile</filename>. <command>make</command>
simply takes the last definition as the definitive one.</para>
<para>Instead of <emphasis>replacing</emphasis> boilerplate
<itemizedlist>
<listitem>
- <para><command>gmake</command> commits target and
+ <para><command>make</command> commits target and
dependency lists earlier than it should. For example,
<filename>target.mk</filename> has a rule that looks
like this:</para>
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
+ <command>make</command> encountered the rule. Alas,
+ <command>make</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
</sect2>
<sect2 id="sec-boiler">
- <title>The main <filename>mk/boilerplate.mk</filename> file</title>
+ <title>The <filename>mk/boilerplate.mk</filename> file</title>
<indexterm><primary>boilerplate.mk</primary></indexterm>
<para>If you look at
- <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
+ <filename>$(GHC_TOP)/mk/boilerplate.mk</filename>
you will find that it consists of the following sections, each
held in a separate file:</para>
<para>extra options to pass to all C compilations. This
is intended for command line use, thus:</para>
-<screen>$ gmake libHS.a EXTRA_CC_OPTS="-v"</screen>
+<screen>$ make libHS.a EXTRA_HC_OPTS="-v"</screen>
</listitem>
</varlistentry>
</variablelist>
<constant>$(libdir)</constant>.</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
- <listitem>
- <para>…</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
- <listitem>
- <para>…</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
- <listitem>
- <para>If <constant>HS_SRCS</constant> is defined
- and non-empty, a rule for the target
- <literal>depend</literal> is included, which generates
- dependency information for Haskell programs. Similarly
- for <constant>C_SRCS</constant>.</para>
- </listitem>
- </varlistentry>
</variablelist>
- <para>All of these rules are “double-colon” rules,
+ <para>Some rules are “double-colon” rules,
thus</para>
<programlisting>install :: $(HS_PROG)
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
+ <literal>install</literal>. When you type <command>make
install</command> both rules will be fired, and both the program
and the library will be installed, just as you wanted.</para>
</sect2>
<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
+ be important. For example, when you say <command>make
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).
<para>A <command>make</command> variable called
<constant>way</constant> holds the current way tag.
<emphasis><constant>way</constant> is only ever set on the
- command line of <command>gmake</command></emphasis> (usually in
- a recursive invocation of <command>gmake</command> by the
+ command line of <command>make</command></emphasis> (usually in
+ a recursive invocation of <command>make</command> by the
system). It is never set inside a
<filename>Makefile</filename>. So it is a global constant for
- any one invocation of <command>gmake</command>. Two other
+ any one invocation of <command>make</command>. Two other
<command>make</command> variables,
<constant>way_</constant> and
<constant>_way</constant> are immediately derived from
<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
+ variable. So if you say <command>make
Foo.mp_o</command> you should see a recursive
- invocation <command>gmake Foo.mp_o way=mp</command>,
+ invocation <command>make 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
<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>
+ format the documentation that comes with GHC:</para>
<variablelist>
<varlistentry>
<listitem>
<para>Haddock is a Haskell documentation tool that we use
for automatically generating documentation from the
- library source code. It is an <literal>fptools</literal>
- project in itself. To build documentation for the
- libraries (<literal>fptools/libraries</literal>) you
- should check out and build Haddock in
- <literal>fptools/haddock</literal>. Haddock requires GHC
+ library source code. To build documentation for the
+ libraries (<literal>$(GHC_TOP)/libraries</literal>) you
+ should build and install Haddock. Haddock requires GHC
to build.</para>
</listitem>
</varlistentry>
<title>Porting GHC</title>
<para>This section describes how to port GHC to a currenly
- unsupported platform. There are two distinct
- possibilities:</para>
+ unsupported platform. To avoid confusion, when we say
+ “architecture” we are referring to the processor, and
+ we use the term “platform” to refer to the combination
+ of architecture and operating system.</para>
+
+ <para>There are two distinct porting scenarios:</para>
<itemizedlist>
<listitem>
- <para>The hardware architecture for your system is already
- supported by GHC, but you're running an OS that isn't
- supported (or perhaps has been supported in the past, but
- currently isn't). This is the easiest type of porting job,
- but it still requires some careful bootstrapping. Proceed to
- <xref linkend="sec-booting-from-hc"/>.</para>
+ <para>Your platform is already supported, but you want to
+ compile up GHC using just a C compiler. This is a
+ straightforward bootstrap from HC files, and is described in
+ <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>
+ <para>Your platform isn't supported by GHC. You will need to
+ do an <emphasis>unregisterised bootstrap</emphasis>, proceed
+ to <xref linkend="unregisterised-porting"/>.</para>
</listitem>
</itemizedlist>
later.</emphasis></para>
<para>HC files are platform-dependent, so you have to get a set
- that were generated on <emphasis>the same platform</emphasis>. There
- may be some supplied on the GHC download page, otherwise you'll have to
- compile some up yourself, or start from
- <emphasis>unregisterised</emphasis> HC files - see <xref
- linkend="unregisterised-porting"/>.</para>
+ that were generated on <emphasis>the same platform</emphasis>.
+ There may be some supplied on the GHC download page, otherwise
+ you'll have to compile some up yourself.</para>
<para>The following steps should result in a working GHC build
with full libraries:</para>
<itemizedlist>
<listitem>
- <para>Unpack the HC files on top of a fresh source tree
- (make sure the source tree version matches the version of
- the HC files <emphasis>exactly</emphasis>!). This will
- place matching <filename>.hc</filename> files next to the
- corresponding Haskell source (<filename>.hs</filename> or
- <filename>.lhs</filename>) in the compiler subdirectory
- <filename>ghc/compiler</filename> and in the libraries
- (subdirectories of
+ <para>Make a set of HC files. On an identical system with
+ GHC already installed, get a GHC source tree and put the
+ following in <literal>mk/build.mk</literal>:</para>
+
+<programlisting>
+SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files
+GhcLibHcOpts = -O
+GhcLibWays =
+SplitObjs = NO
+</programlisting>
+
+ <para>Build GHC as normal, and then <literal>make
+ hc-file-bundle Project=ghc</literal> to creates the tar file
+ containing the hc files.</para>
+ </listitem>
+
+ <listitem>
+ <para>On the target system, unpack the HC files on top of a
+ fresh source tree (make sure the source tree version matches
+ the version of the HC files <emphasis>exactly</emphasis>!).
+ This will place matching <filename>.hc</filename> files next
+ to the corresponding Haskell source
+ (<filename>.hs</filename> or <filename>.lhs</filename>) in
+ the compiler subdirectory <filename>ghc/compiler</filename>
+ and in the libraries (subdirectories of
<literal>libraries</literal>).</para>
</listitem>
</sect2>
<sect2 id="unregisterised-porting">
- <title>Porting GHC to a new architecture</title>
+ <title>Porting GHC to a new platform</title>
- <para>The first step in porting to a new architecture is to get
- an <firstterm>unregisterised</firstterm> build working. An
+ <para>The first step in porting to a new platform is to get an
+ <firstterm>unregisterised</firstterm> build working. An
unregisterised build is one that compiles via vanilla C only.
By contrast, a registerised build uses the following
architecture-specific hacks for speed:</para>
since unregisterised compilation is usually just a step on the
way to a full registerised port, we don't mind too much.</para>
+ <para>You should go through this process even if your
+ architecture is already has registerised support in GHC, but
+ your OS currently isn't supported. In this case you probably
+ won't need to port any of the architecture-specific parts of the
+ code, and you can proceed straight from the unregisterised build
+ to build a registerised compiler.</para>
+
<para>Notes on GHC portability in general: we've tried to stick
to writing portable code in most parts of the system, so it
should compile on any POSIXish system with gcc, but in our
$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
<para>You might need to update
- <filename>configure.in</filename> to recognise the new
- architecture, and re-generate
+ <filename>configure.ac</filename> to recognise the new
+ platform, and re-generate
<filename>configure</filename> with
<literal>autoreconf</literal>.</para>
</listitem>
<listitem>
-<screen>$ cd <replaceable>T</replaceable>/ghc/includes
+<screen>$ cd <replaceable>T</replaceable>/includes
$ make</screen>
</listitem>
</itemizedlist>
GhcStage1HcOpts = -O
GhcStage2HcOpts = -O -fvia-C -keep-hc-files
SRC_HC_OPTS += -H32m
-GhcBootLibs = YES</programlisting>
+GhcBootLibs = YES
+GhcWithSMP = NO</programlisting>
</listitem>
<listitem>
<listitem>
<para>change <literal>TARGETPLATFORM</literal>
appropriately, and set the variables involving
- <literal>TARGET</literal> to the correct values for
+ <literal>TARGET</literal> or
+ <literal>Target</literal> to the correct values for
the target platform. This step is necessary because
currently <literal>configure</literal> doesn't cope
with specifying different values for the
<listitem>
<para>Copy
- <filename><replaceable>T</replaceable>/ghc/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/ghc/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/ghc/includes/GHCConstants.h</filename>
+ <filename><replaceable>T</replaceable>/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/includes/GHCConstants.h</filename>
to
- <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+ <filename><replaceable>H</replaceable>/includes</filename>.
Note that we are building on the host machine, using the
target machine's configuration files. This
is so that the intermediate C files generated here will
<listitem>
<para>Touch the generated configuration files, just to make
sure they don't get replaced during the build:</para>
-<screen>$ cd <filename><replaceable>H</replaceable></filename>/ghc/includes
+<screen>$ cd <filename><replaceable>H</replaceable></filename>/includes
$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
-
- <para>Note: it has been reported that these files still get
- overwritten during the next stage. We have installed a fix
- for this in GHC 6.4.2, but if you are building a version
- before that you need to watch out for these files getting
- overwritte by the <literal>Makefile</literal> in
- <literal>ghc/includes</literal>. If your system supports
- it, you might be able to prevent it by making them
- immutable:</para>
-<screen>$ chflags uchg ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
</listitem>
<listitem>
<para>Now build the compiler:</para>
-<screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
-$ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
- <para>Don't worry if the build falls over in the RTS, we
- don't need the RTS yet.</para>
+<screen>$ cd <replaceable>H</replaceable>/utils/mkdependC && make boot && make
+$ cd <replaceable>H</replaceable>/includes && make boot && make
+$ cd <replaceable>H</replaceable>/compat && make boot && make
+$ cd <replaceable>H</replaceable>/utils && make boot && make
+$ cd <replaceable>H</replaceable>/compiler && make boot && make
+$ cd <replaceable>H</replaceable>/rts && make boot && make</screen>
+ <para>Don't worry if the build falls over in the RTS, we
+ don't need the RTS yet.</para>
</listitem>
<listitem>
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/compiler
+<screen>$ cd <replaceable>H</replaceable>/compiler
$ make boot stage=2 && make stage=2</screen>
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
+<screen>$ cd <replaceable>H</replaceable>/compat
$ make clean
$ rm .depend
-$ make boot UseStage1=YES
-$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
-$ cd <replaceable>H</replaceable>/ghc/utils
+$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+$ cd <replaceable>H</replaceable>/utils
$ make clean
$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
</listitem>
<title>GHCi</title>
<para>To support GHCi, you need to port the dynamic linker
- (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
- currently supports the ELF and PEi386 object file formats - if
- your platform uses one of these then things will be
- significantly easier. The majority of Unix platforms use the
- ELF format these days. Even so, there are some
+ (<filename>$(GHC_TOP)/rts/Linker.c</filename>). The
+ linker currently supports the ELF and PEi386 object file
+ formats - if your platform uses one of these then things will
+ be significantly easier. The majority of Unix platforms use
+ the ELF format these days. Even so, there are some
machine-specific parts of the ELF linker: for example, the
code for resolving particular relocation types is
machine-specific, so some porting of this code to your
- architecture will probaly be necessary.</para>
+ architecture and/or OS will probaly be necessary.</para>
<para>If your system uses a different object file format, then
you have to write a linker — good luck!</para>
<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.
+in your <filename>build.mk</filename> file. Then GHC and the other
+tools will use the appropriate directory in all cases.
</para>
</itemizedlist>
-and try again: <command>gmake</command>. (see <xref linkend="sec-suffix"/> for information about
+and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about
<constant><module>_HC_OPTS</constant>.)
Alternatively, just cut to the chase:
<para>You have to install the following other things to build GHC, listed below.</para>
<para>On Windows you often install executables in directories with spaces, such as
-"<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
+"<filename>Program Files</filename>". However, the <literal>make</literal> system doesn't
deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
to put binaries for all tools in places with no spaces in their path.
On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
<listitem>
<para>We use <command>emacs</command> a lot, so we install that too.
-When you are in <filename>fptools/ghc/compiler</filename>, you can use
+When you are in <filename>$(GHC_TOP)/compiler</filename>, you can use
"<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
-<filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
-The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
+<filename>$(GHC_TOP)/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
+The most convenient way to do this is by going <literal>make boot</literal> in <filename>$(GHC_TOP)/ghc</filename>.
The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
</para>
<listitem>
<para>
After <command>autoreconf</command> run <command>./configure</command> in
- <filename>fptools/</filename> thus:
+ <filename>$(GHC_TOP)/</filename> thus:
<screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
This is the point at which you specify that you are building GHC-mingw
time it tries to invoke it. Worse, the failure comes with
no error message whatsoever. GHC simply fails silently when first invoked,
typically leaving you with this:
-<screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
+<screen>make[4]: Leaving directory `/cygdrive/e/ghc-stage1/ghc/rts/gmp'
../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
-optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
-optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
-package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
make[2]: *** [Adjustor.o] Error 1
make[1]: *** [all] Error 1
-make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc'
make: *** [all] Error 1</screen>
Be warned!
</para>
; also, subscribe to cvs-all@haskell.org, or follow the mailing list
; archive, in case you checkout a version with problems
; http://www.haskell.org//pipermail/cvs-all/
- - mkdir c:/fptools; cd c:/fptools
+ - mkdir c:/ghc-build; cd c:/ghc-build
; (or whereever you want your darcs tree to be)
- darcs get http://darcs.haskell.org/ghc
- cd ghc
; for haddock, alex, happy (*)
- export PATH=/cygdrive/c/mingw/bin:$PATH
; without, we pick up some cygwin tools at best!
- - cd c:/fptools/fptools
+ - cd c:/ghc-build
; (if you aren't there already)
- autoreconf
- ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
projects / ghc-hetmet.git / blobdiff