-<?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" [
- <!ENTITY hacking SYSTEM "../../HACKING">
-]>
-
-<article id="building-guide">
-
-<articleinfo>
-
-<title>Building and developing GHC</title>
-<author><othername>The GHC Team</othername></author>
-<address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address>
-
- <abstract>
- <para>This Guide is primarily aimed at those who want to build and/or
- hack on GHC. It describes how to get started with building GHC on your
- machine, and how to tweak the settings to get the kind of build you
- want. It also describes the inner workings of the build system, so you
- can extend it, modify it, and use it to build your code.</para>
-
- <para>The bulk of this guide applies to building on Unix
- systems; see <xref linkend="winbuild"/> for Windows notes.</para>
- </abstract>
-
-</articleinfo>
-
-
- <sect1 id="sec-getting">
- <title>Getting the sources</title>
-
- <para>You can get your hands on the GHC sources in two ways:</para>
-
- <variablelist>
-
- <varlistentry>
- <term><indexterm><primary>Source
- distributions</primary></indexterm>Source distributions</term>
- <listitem>
- <para>You have a supported platform, but (a) you like
- the warm fuzzy feeling of compiling things yourself;
- (b) you want to build something ``extra”—e.g., a
- set of libraries with strictness-analysis turned off; or
- (c) you want to hack on GHC yourself.</para>
-
- <para>A source distribution contains complete sources for
- GHC. Not only that, but the more awkward
- machine-independent steps are done for you. For example, if
- you don't have
- <command>happy</command><indexterm><primary>happy</primary></indexterm>
- you'll find it convenient that the source distribution
- contains the result of running <command>happy</command> on
- the parser specifications. If you don't want to alter the
- parser then this saves you having to find and install
- <command>happy</command>. You will still need a working
- version of GHC (version 5.x or later) on your machine in
- order to compile (most of) the sources, however.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>The darcs repository.<indexterm><primary>darcs repository</primary></indexterm></term>
- <listitem>
- <para>We make releases infrequently. If you want more
- up-to-the minute (but less tested) source code then you need
- to get access to our darcs repository.</para>
-
- <para>Information on accessing the darcs repository is on
- the wiki: <ulink
- url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs"
- />.</para>
-
- <para>The repository holds source code only. It holds no
- mechanically generated files at all. So if you check out a
- source tree from darcs you will need to install every utility
- so that you can build all the derived files from
- scratch.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1 id="sec-build-checks">
- <title>Things to check before you start</title>
-
- <para>Here's a list of things to check before you get
- started.</para>
-
- <orderedlist>
-
- <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
- space needed: from about 100Mb for a basic GHC
- build, up to probably 500Mb for a GHC build with everything
- included (libraries built several different ways,
- etc.).</para>
- </listitem>
-
- <listitem>
- <para>Use an appropriate machine / operating system. <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
- installed. <xref linkend="sec-pre-supposed"/>
- elaborates.</para>
- </listitem>
-
- <listitem>
- <para>If you have any problem when building or installing the
- Glasgow tools, please check the “known pitfalls” (<xref
- linkend="sec-build-pitfalls"/>). Also check the FAQ for the
- version you're building, which is part of the User's Guide and
- available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
- site</ulink>.</para>
-
- <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
-
- <para>If you feel there is still some shortcoming in our
- procedure or instructions, please report it.</para>
-
- <para>For GHC, please see the <ulink
- url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
- section of the GHC Users' Guide</ulink>, to maximise the
- usefulness of your report.</para>
-
- <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
- <para>If in doubt, please send a message to
- <email>glasgow-haskell-bugs@haskell.org</email>.
- <indexterm><primary>bugs</primary><secondary>mailing
- list</secondary></indexterm></para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1 id="sec-pre-supposed">
- <title>Installing pre-supposed utilities</title>
-
- <indexterm><primary>pre-supposed utilities</primary></indexterm>
- <indexterm><primary>utilities, pre-supposed</primary></indexterm>
-
- <para>Here are the gory details about some utility programs you
- may need; <command>perl</command>, <command>gcc</command> and
- <command>happy</command> are the only important
- ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
- important if you're going for Parallel Haskell.) The
- <command>configure</command><indexterm><primary>configure</primary></indexterm>
- script will tell you if you are missing something.</para>
-
- <variablelist>
-
- <varlistentry>
- <term>GHC
- <indexterm><primary>pre-supposed: GHC</primary></indexterm>
- <indexterm><primary>GHC, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <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>
-
- <varlistentry>
- <term>Perl
- <indexterm><primary>pre-supposed: Perl</primary></indexterm>
- <indexterm><primary>Perl, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para><emphasis>You have to have Perl to proceed!</emphasis>
- Perl version 5 at least is required. GHC has been known to
- tickle bugs in Perl, so if you find that Perl crashes when
- running GHC try updating (or downgrading) your Perl
- installation. Versions of Perl before 5.6 have been known to have
- various bugs tickled by GHC, so the configure script
- will look for version 5.6 or later.</para>
-
- <para>For Win32 platforms, you should use the binary
- supplied in the InstallShield (copy it to
- <filename>/bin</filename>). The Cygwin-supplied Perl seems
- not to work.</para>
-
- <para>Perl should be put somewhere so that it can be invoked
- by the <literal>#!</literal> script-invoking
- mechanism. The full pathname may need to be less than 32
- characters long on some systems.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>GNU C (<command>gcc</command>)
- <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
- <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>Most GCC versions should work with the most recent GHC
- sources. Expect trouble if you use a recent GCC with
- an older GHC, though (trouble in the form of mis-compiled code,
- link errors, and errors from the <literal>ghc-asm</literal>
- script).</para>
-
- <para>If your GCC dies with “internal error” on
- some GHC source file, please let us know, so we can report
- it and get things improved. (Exception: on x86
- boxes—you may need to fiddle with GHC's
- <option>-monly-N-regs</option> option; see the User's
- Guide)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>GNU Make
- <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
- </term>
- <listitem>
- <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 GHC.</para>
-
- <para>NB. it has been reported that version 3.79 no longer
- works to build GHC, and 3.80 is required.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
- <indexterm><primary>Happy</primary></indexterm>
- </term>
- <listitem>
- <para>Happy is a parser generator tool for Haskell, and is
- used to generate GHC's parsers.</para>
-
- <para>If you start from a source tarball of GHC (i.e. not a darcs
- checkout), then you don't need Happy, because we supply the
- pre-processed versions of the Happy parsers. If you intend to
- 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.
- Grab a copy from <ulink
- url="http://www.haskell.org/happy/">Happy's Web
- Page</ulink>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Alex
- <indexterm><primary>Alex</primary></indexterm>
- </term>
- <listitem>
- <para>Alex is a lexical-analyser generator for Haskell,
- which GHC uses to generate its lexer.</para>
-
- <para>Like Happy, you don't need Alex if you're building GHC from a
- source tarball, but you do need it if you're modifying GHC and/or
- building a darcs checkout.</para>
-
- <para>Alex is
- written in Haskell and is a project in the darcs repository.
- Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
- Page</ulink>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>autoconf
- <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
- <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>GNU autoconf is needed if you intend to build from the
- darcs sources, it is <emphasis>not</emphasis> needed if you
- just intend to build a standard source distribution.</para>
-
- <para>Version 2.52 or later of the autoconf package is required.
- NB. version 2.13 will no longer work, as of GHC version
- 6.1.</para>
-
- <para><command>autoreconf</command> (from the autoconf package)
- recursively builds <command>configure</command> scripts from
- the corresponding <filename>configure.ac</filename> and
- <filename>aclocal.m4</filename> files. If you modify one of
- the latter files, you'll need <command>autoreconf</command> to
- rebuild the corresponding <filename>configure</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>sed</command>
- <indexterm><primary>pre-supposed: sed</primary></indexterm>
- <indexterm><primary>sed, pre-supposed</primary></indexterm>
- </term>
- <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>
-
- <sect2 id="pre-supposed-gph-tools">
- <title>Tools for building parallel GHC (GPH)</title>
-
- <variablelist>
- <varlistentry>
- <term>PVM version 3:
- <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
- <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>PVM is the Parallel Virtual Machine on which
- Parallel Haskell programs run. (You only need this if you
- plan to run Parallel Haskell. Concurrent Haskell, which
- runs concurrent threads on a uniprocessor doesn't need
- it.) Underneath PVM, you can have (for example) a network
- of workstations (slow) or a multiprocessor box
- (faster).</para>
-
- <para>The current version of PVM is 3.3.11; we use 3.3.7.
- It is readily available on the net; I think I got it from
- <literal>research.att.com</literal>, in
- <filename>netlib</filename>.</para>
-
- <para>A PVM installation is slightly quirky, but easy to
- do. Just follow the <filename>Readme</filename>
- instructions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>bash</command>:
- <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
- </term>
- <listitem>
- <para>Sadly, the <command>gr2ps</command> script, used to
- convert “parallelism profiles” to PostScript,
- is written in Bash (GNU's Bourne Again shell). This bug
- will be fixed (someday).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>More tools are required if you want to format the
- documentation that comes with GHC. See <xref
- linkend="building-docs"/>.</para>
- </sect2>
- </sect1>
-
- <sect1 id="sec-building-from-source">
- <title>Building from source</title>
-
- <indexterm><primary>Building from source</primary></indexterm>
- <indexterm><primary>Source, building from</primary></indexterm>
-
- <para>“I just want to build it!”</para>
-
- <para>No problem. This recipe should build and install a working GHC with
- all the default settings. (unless you're
- on Windows, in which case go to <xref linkend="winbuild" />).</para>
-
-<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
- </footnote>
-$ ./configure
-$ make
-$ make install</screen>
-
- <para>For GHC, this will do a 2-stage bootstrap build of the
- compiler, with profiling libraries, and install the
- results in the default location (under <filename>/usr/local</filename> on
- Unix, for example).</para>
-
- <para>The <literal>configure</literal> script is a standard GNU
- <literal>autoconf</literal> script, and accepts the usual options for
- changing install locations and the like. Run
- <literal>./configure --help</literal> for a list of options.</para>
-
- <para>If you want to do anything at all non-standard, or you
- want to do some development, read on...</para>
- </sect1>
-
- <sect1 id="quick-start">
- <title>Quick start for GHC developers</title>
-
- <para>This section is a copy of the file
- <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>
-
-<screen>
-&hacking;
- </screen>
- </sect1>
-
- <sect1 id="sec-working-with-the-build-system">
- <title>Working with the build system</title>
-
- <para>This rest of this guide is intended for duffers like me, who
- aren't really interested in Makefiles and systems configurations,
- but who need a mental model of the interlocking pieces so that
- they can make them work, extend them consistently when adding new
- software, and lay hands on them gently when they don't
- work.</para>
-
- <sect2>
- <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>
- <title>Build trees</title>
- <indexterm><primary>build trees</primary></indexterm>
- <indexterm><primary>link trees, for building</primary></indexterm>
-
- <para>If you just want to build the software once on a single
- platform, then your source tree can also be your build tree, and
- you can skip the rest of this section.</para>
-
- <para>We often want to build multiple versions of our software
- for different architectures, or with different options
- (e.g. profiling). It's very desirable to share a single copy of
- the source code among all these builds.</para>
-
- <para>So for every source tree we have zero or more
- <emphasis>build trees</emphasis>. Each build tree is initially
- an exact copy of the source tree, except that each file is a
- symbolic link to the source file, rather than being a copy of
- the source file. There are “standard” Unix
- utilities that make such copies, so standard that they go by
- different names:
- <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
- <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
- are two (If you don't have either, the source distribution
- includes sources for the X11
- <command>lndir</command>—check out
- <filename>utils/lndir</filename>). See <xref
- linkend="sec-storysofar"/> for a typical invocation.</para>
-
- <para>The build tree does not need to be anywhere near the
- source tree in the file system. Indeed, one advantage of
- separating the build tree from the source is that the build tree
- can be placed in a non-backed-up partition, saving your systems
- support people from backing up untold megabytes of
- easily-regenerated, and rapidly-changing, gubbins. The golden
- rule is that (with a single exception—<xref
- linkend="sec-build-config"/>) <emphasis>absolutely everything in
- the build tree is either a symbolic link to the source tree, or
- else is mechanically generated</emphasis>. It should be
- perfectly OK for your build tree to vanish overnight; an hour or
- two compiling and you're on the road again.</para>
-
- <para>You need to be a bit careful, though, that any new files
- you create (if you do any development work) are in the source
- tree, not a build tree!</para>
-
- <para>Remember, that the source files in the build tree are
- <emphasis>symbolic links</emphasis> to the files in the source
- tree. (The build tree soon accumulates lots of built files like
- <filename>Foo.o</filename>, as well.) You can
- <emphasis>delete</emphasis> a source file from the build tree
- without affecting the source tree (though it's an odd thing to
- do). On the other hand, if you <emphasis>edit</emphasis> a
- source file from the build tree, you'll edit the source-tree
- file directly. (You can set up Emacs so that if you edit a
- source file from the build tree, Emacs will silently create an
- edited copy of the source file in the build tree, leaving the
- source file unchanged; but the danger is that you think you've
- edited the source file whereas actually all you've done is edit
- the build-tree copy. More commonly you do want to edit the
- source file.)</para>
-
- <para>Like the source tree, the top level of your build tree
- must be (a linked copy of) the root directory of the 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>$(GHC_TOP)</constant> unless
- otherwise stated. For example, the file
- <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 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
- a bit different for each. There are some big differences too:
- for a different architecture we need to build GHC with a
- different native-code generator.</para>
-
- <para>There are also knobs you can turn to control how the
- software is built. For example, you might want to build GHC
- optimised (so that it runs fast) or unoptimised (so that you can
- compile it fast after you've modified it. Or, you might want to
- compile it with debugging on (so that extra consistency-checking
- code gets included) or off. And so on.</para>
-
- <para>All of this stuff is called the
- <emphasis>configuration</emphasis> of your build. You set the
- configuration using a three-step process.</para>
-
- <variablelist>
- <varlistentry>
- <term>Step 1: get ready for configuration.</term>
- <listitem>
- <para>NOTE: if you're starting from a source distribution,
- rather than darcs sources, you can skip this step.</para>
-
- <para>Change directory to
- <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>$(GHC_TOP)/configure.ac</filename> and
- <filename>$(GHC_TOP)/aclocal.m4</filename>
- to a shell script called
- <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 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>$(GHC_TOP)</filename>.</para>
-
- <para>These steps are completely platform-independent; they just mean
- that the human-written files (<filename>configure.ac</filename> and
- <filename>aclocal.m4</filename>) can be short, although the resulting
- files (the <command>configure</command> shell scripts and the C header
- template <filename>mk/config.h.in</filename>) are long.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Step 2: system configuration.</term>
- <listitem>
- <para>Runs the newly-created <command>configure</command>
- script, thus:</para>
-
-<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,
- what operating system, whether it has the
- <function>vfork</function> system call, where
- <command>tar</command> is kept, whether
- <command>gcc</command> is available, where various obscure
- <literal>#include</literal> files are, whether it's a
- leap year, and what the systems manager had for lunch. It
- communicates these snippets of information in two
- ways:</para>
-
- <itemizedlist>
- <listitem>
-
- <para>It translates
- <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
- to
- <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
- substituting for things between
- “<literal>@</literal>” brackets. So,
- “<literal>@HaveGcc@</literal>” will be
- replaced by “<literal>YES</literal>” or
- “<literal>NO</literal>” depending on what
- <command>configure</command> finds.
- <filename>mk/config.mk</filename> is included by every
- Makefile (directly or indirectly), so the
- configuration information is thereby communicated to
- all Makefiles.</para>
- </listitem>
-
- <listitem>
- <para> It translates
- <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
- to
- <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
- The latter is <literal>#include</literal>d by
- various C programs, which can thereby make use of
- configuration information.</para>
- </listitem>
- </itemizedlist>
-
- <para><command>configure</command> takes some optional
- arguments. Use <literal>./configure --help</literal> to
- get a list of the available arguments. Here are some of
- the ones you might need:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>--with-ghc=<parameter>path</parameter></literal>
- <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Specifies the path to an installed GHC which
- you would like to use. This compiler will be used
- for compiling GHC-specific code (eg. GHC itself).
- This option <emphasis>cannot</emphasis> be specified
- using <filename>build.mk</filename> (see later),
- because <command>configure</command> needs to
- auto-detect the version of GHC you're using. The
- default is to look for a compiler named
- <literal>ghc</literal> in your path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>--with-hc=<parameter>path</parameter></literal>
- <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Specifies the path to any installed Haskell
- compiler. This compiler will be used for compiling
- generic Haskell code. The default is to use
- <literal>ghc</literal>. (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>
-
- <varlistentry>
- <term><literal>--with-gcc=<parameter>path</parameter></literal>
- <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Specifies the path to the installed GCC. This
- compiler will be used to compile all C files,
- <emphasis>except</emphasis> any generated by the
- installed Haskell compiler, which will have its own
- idea of which C compiler (if any) to use. The
- default is to use <literal>gcc</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Step 3: build configuration.</term>
- <listitem>
- <para>Next, you say how this build of
- 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
- one and only file you edit in the build tree, precisely
- because it says how this build differs from the source.
- (Just in case your build tree does die, you might want to
- keep a private directory of <filename>build.mk</filename>
- files, and use a symbolic link in each build tree to point
- to the appropriate one.) So
- <filename>mk/build.mk</filename> never exists in the
- source tree—you create one in each build tree from
- the template. We'll discuss what to put in it
- shortly.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>And that's it for configuration. Simple, eh?</para>
-
- <para>What do you put in your build-specific configuration file
- <filename>mk/build.mk</filename>? <emphasis>For almost all
- purposes all you will do is put make variable definitions that
- override those in</emphasis>
- <filename>mk/config.mk.in</filename>. The whole point of
- <filename>mk/config.mk.in</filename>—and its derived
- counterpart <filename>mk/config.mk</filename>—is to define
- the build configuration. It is heavily commented, as you will
- see if you look at it. So generally, what you do is look at
- <filename>mk/config.mk.in</filename>, and add definitions in
- <filename>mk/build.mk</filename> that override any of the
- <filename>config.mk</filename> definitions that you want to
- change. (The override occurs because the main boilerplate file,
- <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
- includes <filename>build.mk</filename> after
- <filename>config.mk</filename>.)</para>
-
- <para>For 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=-Rghc-timing</programlisting>
-
- <para>The accompanying comment explains that this is the list of
- flags passed to GHC when building GHC itself. For doing
- development, it is wise to add <literal>-DDEBUG</literal>, to
- enable debugging code. So you would add the following to
- <filename>build.mk</filename>:</para>
-
-<programlisting>GhcHcOpts += -DDEBUG</programlisting>
-
- <para>GNU <command>make</command> allows existing definitions to
- have new text appended using the “<literal>+=</literal>”
- operator, which is quite a convenient feature.</para>
-
- <para>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>
-
-<programlisting>SRC_HC_OPTS = -H16m -O0</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
- by <command>configure</command> later. You
- <emphasis>can</emphasis> override the resulting definition if
- you want, but you need to be a bit surer what you are doing.
- For example, there's a line that says:</para>
-
-<programlisting>TAR = @TarCmd@</programlisting>
-
- <para>This defines the Make variables <constant>TAR</constant>
- to the pathname for a <command>tar</command> that
- <command>configure</command> finds somewhere. If you have your
- own pet <command>tar</command> you want to use instead, that's
- fine. Just add this line to <filename>mk/build.mk</filename>:</para>
-
-<programlisting>TAR = mytar</programlisting>
-
- <para>You do not <emphasis>have</emphasis> to have a
- <filename>mk/build.mk</filename> file at all; if you don't,
- you'll get all the default settings from
- <filename>mk/config.mk.in</filename>.</para>
-
- <para>You can also use <filename>build.mk</filename> to override
- anything that <command>configure</command> got wrong. One place
- where this happens often is with the definition of
- <constant>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">
- <title>The story so far</title>
-
- <para>Let's summarise the steps you need to carry to get
- yourself a fully-configured build tree from scratch.</para>
-
- <orderedlist>
- <listitem>
- <para> Get your source tree from somewhere (darcs repository
- or source distribution). Say you call the root directory
- <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 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
- the build tree a name that suggests its main defining
- characteristic (in your mind at least), in case you later
- add others.</para>
- </listitem>
-
- <listitem>
- <para>Change directory to the build tree. Everything is
- going to happen there now.</para>
-
-<screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
-
- </listitem>
-
- <listitem>
- <para>Prepare for system configuration:</para>
-
-<screen>$ autoreconf</screen>
-
- <para>(You can skip this step if you are starting from a
- source distribution, and you already have
- <filename>configure</filename> and
- <filename>mk/config.h.in</filename>.)</para>
- </listitem>
-
- <listitem>
- <para>Do system configuration:</para>
-
-<screen>$ ./configure</screen>
-
- <para>Don't forget to check whether you need to add any
- arguments to <literal>configure</literal>; for example, a
- common requirement is to specify which GHC to use with
- <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
- </listitem>
-
- <listitem>
- <para>Create the file <filename>mk/build.mk</filename>,
- adding definitions for your desired configuration
- options.</para>
- </listitem>
- </orderedlist>
-
- <para>You can make subsequent changes to
- <filename>mk/build.mk</filename> as often as you like. You do
- not have to run any further configuration programs to make these
- changes take effect. In theory you should, however, say
- <command>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>
- <title>Making things</title>
-
- <para>At this point you have made yourself a fully-configured
- build tree, so you are ready to start building real
- things.</para>
-
- <para>The first thing you need to know is that <emphasis>you
- must use GNU <command>make</command></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 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">
- <title>Bootstrapping GHC</title>
-
- <para>GHC requires a 2-stage bootstrap in order to provide
- full functionality, including GHCi. By a 2-stage bootstrap, we
- mean that the compiler is built once using the installed GHC,
- and then again using the compiler built in the first stage. You
- can also build a stage 3 compiler, but this normally isn't
- necessary except to verify that the stage 2 compiler is working
- properly.</para>
-
- <para>Note that when doing a bootstrap, the stage 1 compiler
- must be built, followed by the runtime system and libraries, and
- then the stage 2 compiler. The correct ordering is implemented
- by the top-level <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>
- <term>stage1</term>
- <listitem>
- <para>Build everything as normal, including the stage 1
- compiler.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>stage2</term>
- <listitem>
- <para>Build the stage 2 compiler only.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>stage3</term>
- <listitem>
- <para>Build the stage 3 compiler only.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>bootstrap</term> <term>bootstrap2</term>
- <listitem>
- <para>Build stage 1 followed by stage 2.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>bootstrap3</term>
- <listitem>
- <para>Build stages 1, 2 and 3.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>install</term>
- <listitem>
- <para>Install everything, including the compiler built in
- stage 2. To override the stage, say <literal>make install
- stage=<replaceable>n</replaceable></literal> where
- <replaceable>n</replaceable> is the stage to install.</para>
- </listitem>
- </varlistentry>
-
- <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
- to do the appropriate <literal>make boot</literal> steps (see
- below) before actually building anything.</para>
-
- <para>The <literal>stage1</literal>, <literal>stage2</literal>
- and <literal>stage3</literal> targets also work in the
- <literal>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>compiler</literal>.</para>
- </sect2>
-
- <sect2 id="sec-standard-targets">
- <title>Standard Targets</title>
- <indexterm><primary>targets, standard makefile</primary></indexterm>
- <indexterm><primary>makefile targets</primary></indexterm>
-
- <para>In any directory you should be able to make the following:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>boot</literal></term>
- <listitem>
- <para>does the one-off preparation required to get ready
- for the real work. Notably, it does <command>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
- 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>make
- boot</literal> is a good way to do it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>all</literal></term>
- <listitem>
- <para>makes all the final target(s) for this Makefile.
- Depending on which directory you are in a “final
- target” may be an executable program, a library
- archive, a shell script, or a Postscript file. Typing
- <command>make</command> alone is generally the same as
- typing <command>make all</command>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>install</literal></term>
- <listitem>
- <para>installs the things built by <literal>all</literal>
- (except for the documentation). Where does it install
- them? That is specified by
- <filename>mk/config.mk.in</filename>; you can override it
- in <filename>mk/build.mk</filename>, or by running
- <command>configure</command> with command-line arguments
- like <literal>--bindir=/home/simonpj/bin</literal>; see
- <literal>./configure --help</literal> for the full
- details.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>install-docs</literal></term>
- <listitem>
- <para>installs the documentation. Otherwise behaves just
- like <literal>install</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>uninstall</literal></term>
- <listitem>
- <para>reverses the effect of
- <literal>install</literal> (WARNING: probably doesn't work).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>clean</literal></term>
- <listitem>
- <para>Delete all files from the current directory that are
- normally created by building the program. Don't delete
- the files that record the configuration, or files
- generated by <command>make boot</command>. Also preserve
- files that could be made by building, but normally aren't
- because the distribution comes with them.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>distclean</literal></term>
- <listitem>
- <para>Delete all files from the current directory that are
- created by configuring or building the program. If you
- have unpacked the source and built the program without
- creating any other files, <literal>make
- distclean</literal> should leave only the files that were
- in the distribution.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>mostlyclean</literal></term>
- <listitem>
- <para>Like <literal>clean</literal>, but may refrain from
- deleting a few files that people normally don't want to
- recompile.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>maintainer-clean</literal></term>
- <listitem>
- <para>Delete everything from the current directory that
- can be reconstructed with this Makefile. This typically
- includes everything deleted by
- <literal>distclean</literal>, plus more: C source files
- produced by Bison, tags tables, Info files, and so
- on.</para>
-
- <para>One exception, however: <literal>make
- maintainer-clean</literal> should not delete
- <filename>configure</filename> even if
- <filename>configure</filename> can be remade using a rule
- in the <filename>Makefile</filename>. More generally,
- <literal>make maintainer-clean</literal> should not delete
- anything that needs to exist in order to run
- <filename>configure</filename> and then begin to build the
- program.</para>
-
- <para>After a <literal>maintainer-clean</literal>, a
- <literal>configure</literal> will be necessary before
- building again.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>All of these standard targets automatically recurse into
- sub-directories. Certain other standard targets do not:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>depend</literal></term>
- <listitem>
- <para>make a <filename>.depend</filename> file in each
- directory that needs it. This <filename>.depend</filename>
- file contains mechanically-generated dependency
- information; for example, suppose a directory contains a
- Haskell source module <filename>Foo.lhs</filename> which
- imports another module <literal>Baz</literal>. Then the
- generated <filename>.depend</filename> file will contain
- the dependency:</para>
-
-<programlisting>Foo.o : Baz.hi</programlisting>
-
- <para>which says that the object file
- <filename>Foo.o</filename> depends on the interface file
- <filename>Baz.hi</filename> generated by compiling module
- <literal>Baz</literal>. The <filename>.depend</filename>
- file is automatically included by every Makefile.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <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 GHC from the build tree</title>
-
- <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>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>
- </sect2>
-
- <sect2>
- <title>Fast Making</title>
-
- <indexterm><primary>fastmake</primary></indexterm>
- <indexterm><primary>dependencies, omitting</primary></indexterm>
- <indexterm><primary>FAST, makefile variable</primary></indexterm>
-
- <para>Sometimes the dependencies get in the way: if you've made
- a small change to one file, and you're absolutely sure that it
- won't affect anything else, but you know that
- <command>make</command> is going to rebuild everything anyway,
- the following hack may be useful:</para>
-
-<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
- temporarily removing the <filename>.depend</filename> file in
- the current directory (where <command>mkdependHS</command> and
- friends store their dependency information).</para>
-
- <para>A bit of history: GHC used to come with a
- <command>fastmake</command> script that did the above job, but
- GNU make provides the features we need to do it without
- resorting to a script. Also, we've found that fastmaking is
- less useful since the advent of GHC's recompilation checker (see
- the User's Guide section on "Separate Compilation").</para>
- </sect2>
- </sect1>
-
- <sect1 id="sec-makefile-arch">
- <title>The <filename>Makefile</filename> architecture</title>
- <indexterm><primary>makefile architecture</primary></indexterm>
-
- <para><command>make</command> is great if everything
- works—you type <command>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
- bowels of a directory you didn't know existed.</para>
-
- <para>The purpose of this section is to give you a road-map to
- help you figure out what is going right and what is going
- wrong.</para>
-
- <sect2>
- <title>Debugging</title>
-
- <para>Debugging <filename>Makefile</filename>s is something of a
- black art, but here's a couple of tricks that we find
- particularly useful. The following command allows you to see
- the contents of any make variable in the context of the current
- <filename>Makefile</filename>:</para>
-
-<screen>$ make show VALUE=HS_SRCS</screen>
-
- <para>where you can replace <literal>HS_SRCS</literal> with the
- name of any variable you wish to see the value of.</para>
-
- <para>GNU make has a <option>-d</option> option which generates
- a dump of the decision procedure used to arrive at a conclusion
- about which files should be recompiled. Sometimes useful for
- tracking down problems with superfluous or missing
- recompilations.</para>
- </sect2>
-
- <sect2>
- <title>A small example</title>
-
- <para>To get started, let us look at the
- <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 program "small"
-TOP = ..
-include $(TOP)/mk/boilerplate.mk
-
-HS_PROG = small
-
-include $(TOP)/target.mk</programlisting>
-
- <para>this <filename>Makefile</filename> has three
- sections:</para>
-
- <orderedlist>
- <listitem>
- <para>The first section includes
-<footnote>
-<para>
-One of the most important
-features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
-include another named file, very like <command>cpp</command>'s <literal>#include</literal>
-directive.
-</para>
-</footnote>
-
- a file of “boilerplate” code from the 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
- boilerplate in more detail in <xref linkend="sec-boiler"/>.
- <indexterm><primary>include, directive in
- Makefiles</primary></indexterm> <indexterm><primary>Makefile
- inclusion</primary></indexterm></para>
-
- <para>Before the <literal>include</literal> statement, you
- must define the <command>make</command> variable
- <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
- to be the 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>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
- that
- <filename>$(TOP)/mk/foo.mk</filename>
- refers to itself.</emphasis> It is up to the
- <filename>Makefile</filename> doing the
- <literal>include</literal> to ensure this is the case.</para>
- </listitem>
-
- <listitem>
- <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>
- </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>make</command> how
- to make the standard targets (<xref
- linkend="sec-standard-targets"/>). Why, you ask, can't this
- standard code be part of
- <filename>boilerplate.mk</filename>? Good question. We
- discuss the reason later, in <xref
- linkend="sec-boiler-arch"/>.</para>
-
- <para>You do not <emphasis>have</emphasis> to
- <literal>include</literal> the
- <filename>target.mk</filename> file. Instead, you can write
- rules of your own for all the standard targets. Usually,
- though, you will find quite a big payoff from using the
- canned rules in <filename>target.mk</filename>; the price
- tag is that you have to understand what canned rules get
- enabled, and what they do (<xref
- linkend="sec-targets"/>).</para>
- </listitem>
- </orderedlist>
-
- <para>In our example <filename>Makefile</filename>, most of the
- work is done by the two <literal>include</literal>d files. When
- you say <command>make all</command>, the following things
- happen:</para>
-
- <itemizedlist>
- <listitem>
- <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.hs</filename> to <filename>Foo.o</filename>
- using a Haskell compiler. (Which one? That is set in the
- build configuration.)</para>
- </listitem>
-
- <listitem>
- <para>It uses another standard pattern rule to compile
- <filename>Baz.c</filename> to <filename>Baz.o</filename>,
- using a C compiler. (Ditto.)</para>
- </listitem>
-
- <listitem>
- <para>It links the resulting <filename>.o</filename> files
- together to make <literal>small</literal>, using the Haskell
- compiler to do the link step. (Why not use
- <command>ld</command>? Because the Haskell compiler knows
- what standard libraries to link in. How did
- <command>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>
- </listitem>
- </itemizedlist>
-
- <para>All <filename>Makefile</filename>s should follow the above
- three-section format.</para>
- </sect2>
-
- <sect2 id="sec-boiler-arch">
- <title>Boilerplate architecture</title>
- <indexterm><primary>boilerplate architecture</primary></indexterm>
-
- <para>Every <filename>Makefile</filename> includes a
- <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
- file at the top, and
- <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
- file at the bottom. In this section we discuss what is in these
- files, and why there have to be two of them. In general:</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>boilerplate.mk</filename> consists of:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Definitions of millions of
- <command>make</command> variables</emphasis> that
- collectively specify the build configuration. Examples:
- <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
- the options to feed to the Haskell compiler;
- <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
- the sub-directories to enable within the
- <literal>nofib</literal> project;
- <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
- the name of the Haskell compiler to use when compiling
- GHC in the <literal>ghc</literal> project.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Standard pattern rules</emphasis> that
- tell <command>make</command> how to construct one file
- from another.</para>
- </listitem>
- </itemizedlist>
-
- <para><filename>boilerplate.mk</filename> needs to be
- <literal>include</literal>d at the <emphasis>top</emphasis>
- of each <filename>Makefile</filename>, so that the user can
- replace the boilerplate definitions or pattern rules by
- simply giving a new definition or pattern rule in the
- <filename>Makefile</filename>. <command>make</command>
- simply takes the last definition as the definitive one.</para>
-
- <para>Instead of <emphasis>replacing</emphasis> boilerplate
- definitions, it is also quite common to
- <emphasis>augment</emphasis> them. For example, a
- <filename>Makefile</filename> might say:</para>
-
-<programlisting>SRC_HC_OPTS += -O</programlisting>
-
- <para>thereby adding “<option>-O</option>” to
- the end of
- <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
- </listitem>
-
- <listitem>
- <para><filename>target.mk</filename> contains
- <command>make</command> rules for the standard targets
- described in <xref linkend="sec-standard-targets"/>. These
- rules are selectively included, depending on the setting of
- certain <command>make</command> variables. These variables
- are usually set in the middle section of the
- <filename>Makefile</filename> between the two
- <literal>include</literal>s.</para>
-
- <para><filename>target.mk</filename> must be included at the
- end (rather than being part of
- <filename>boilerplate.mk</filename>) for several tiresome
- reasons:</para>
-
- <itemizedlist>
- <listitem>
-
- <para><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>
-
-<programlisting>$(HS_PROG) : $(OBJS)
- $(HC) $(LD_OPTS) $< -o $@</programlisting>
-
- <para>If this rule was in
- <filename>boilerplate.mk</filename> then
- <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
- and
- <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
- would not have their final values at the moment
- <command>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
- of firing.) So, the rule must follow the definitions
- given in the <filename>Makefile</filename> itself.</para>
- </listitem>
-
- <listitem>
- <para>Unlike pattern rules, ordinary rules cannot be
- overriden or replaced by subsequent rules for the same
- target (at least, not without an error message).
- Including ordinary rules in
- <filename>boilerplate.mk</filename> would prevent the
- user from writing rules for specific targets in specific
- cases.</para>
- </listitem>
-
- <listitem>
- <para>There are a couple of other reasons I've
- forgotten, but it doesn't matter too much.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="sec-boiler">
- <title>The <filename>mk/boilerplate.mk</filename> file</title>
- <indexterm><primary>boilerplate.mk</primary></indexterm>
-
- <para>If you look at
- <filename>$(GHC_TOP)/mk/boilerplate.mk</filename>
- you will find that it consists of the following sections, each
- held in a separate file:</para>
-
- <variablelist>
- <varlistentry>
- <term><filename>config.mk</filename>
- <indexterm><primary>config.mk</primary></indexterm>
- </term>
- <listitem>
- <para>is the build configuration file we discussed at
- length in <xref linkend="sec-build-config"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>paths.mk</filename>
- <indexterm><primary>paths.mk</primary></indexterm>
- </term>
- <listitem>
- <para>defines <command>make</command> variables for
- pathnames and file lists. This file contains code for
- automatically compiling lists of source files and deriving
- lists of object files from those. The results can be
- overriden in the <filename>Makefile</filename>, but in
- most cases the automatic setup should do the right
- thing.</para>
-
- <para>The following variables may be set in the
- <filename>Makefile</filename> to affect how the automatic
- source file search is done:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>ALL_DIRS</literal>
- <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Set to a list of directories to search in
- addition to the current directory for source
- files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>EXCLUDED_SRCS</literal>
- <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Set to a list of source files (relative to the
- current directory) to omit from the automatic
- search. The source searching machinery is clever
- enough to know that if you exclude a source file
- from which other sources are derived, then the
- derived sources should also be excluded. For
- example, if you set <literal>EXCLUDED_SRCS</literal>
- to include <filename>Foo.y</filename>, then
- <filename>Foo.hs</filename> will also be
- excluded.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>EXTRA_SRCS</literal>
- <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Set to a list of extra source files (perhaps
- in directories not listed in
- <literal>ALL_DIRS</literal>) that should be
- considered.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The results of the automatic source file search are
- placed in the following make variables:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>SRCS</literal>
- <indexterm><primary><literal>SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>All source files found, sorted and without
- duplicates, including those which might not exist
- yet but will be derived from other existing sources.
- <literal>SRCS</literal> <emphasis>can</emphasis> be
- overriden if necessary, in which case the variables
- below will follow suit.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>HS_SRCS</literal>
- <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>all Haskell source files in the current
- directory, including those derived from other source
- files (eg. Happy sources also give rise to Haskell
- sources).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>HS_OBJS</literal>
- <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Object files derived from
- <literal>HS_SRCS</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>HS_IFACES</literal>
- <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Interface files (<literal>.hi</literal> files)
- derived from <literal>HS_SRCS</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>C_SRCS</literal>
- <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>All C source files found.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>C_OBJS</literal>
- <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>Object files derived from
- <literal>C_SRCS</literal>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>SCRIPT_SRCS</literal>
- <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>All script source files found
- (<literal>.lprl</literal> files).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>SCRIPT_OBJS</literal>
- <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
- </term>
- <listitem>
- <para><quote>object</quote> files derived from
- <literal>SCRIPT_SRCS</literal>
- (<literal>.prl</literal> files).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>HSC_SRCS</literal>
- <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>All <literal>hsc2hs</literal> source files
- (<literal>.hsc</literal> files).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>HAPPY_SRCS</literal>
- <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
- </term>
- <listitem>
- <para>All <literal>happy</literal> source files
- (<literal>.y</literal> or <literal>.hy</literal> files).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>OBJS</literal>
- <indexterm><primary>OBJS</primary></indexterm>
- </term>
- <listitem>
- <para>the concatenation of
- <literal>$(HS_OBJS)</literal>,
- <literal>$(C_OBJS)</literal>, and
- <literal>$(SCRIPT_OBJS)</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Any or all of these definitions can easily be
- overriden by giving new definitions in your
- <filename>Makefile</filename>.</para>
-
- <para>What, exactly, does <filename>paths.mk</filename>
- consider a <quote>source file</quote> to be? It's based
- on the file's suffix (e.g. <filename>.hs</filename>,
- <filename>.lhs</filename>, <filename>.c</filename>,
- <filename>.hy</filename>, etc), but this is the kind of
- detail that changes, so rather than enumerate the source
- suffices here the best thing to do is to look in
- <filename>paths.mk</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>opts.mk</filename>
- <indexterm><primary>opts.mk</primary></indexterm>
- </term>
- <listitem>
- <para>defines <command>make</command> variables for option
- strings to pass to each program. For example, it defines
- <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
- the option strings to pass to the Haskell compiler. See
- <xref linkend="sec-suffix"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>suffix.mk</filename>
- <indexterm><primary>suffix.mk</primary></indexterm>
- </term>
- <listitem>
- <para>defines standard pattern rules—see <xref
- linkend="sec-suffix"/>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Any of the variables and pattern rules defined by the
- boilerplate file can easily be overridden in any particular
- <filename>Makefile</filename>, because the boilerplate
- <literal>include</literal> comes first. Definitions after this
- <literal>include</literal> directive simply override the default
- ones in <filename>boilerplate.mk</filename>.</para>
- </sect2>
-
- <sect2 id="sec-platforms">
- <title>Platform settings</title>
- <indexterm><primary>Platform settings</primary>
- </indexterm>
-
- <para>There are three platforms of interest when building GHC:</para>
-
- <variablelist>
- <varlistentry>
- <term>The <emphasis>build</emphasis> platform</term>
- <listitem>
- <para>The platform on which we are doing this build.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>The <emphasis>host</emphasis> platform</term>
- <listitem>
- <para>The platform on which these binaries will run.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>The <emphasis>target</emphasis> platform</term>
- <listitem>
- <para>The platform for which this compiler will generate code.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>These platforms are set when running the
- <literal>configure</literal> script, using the
- <option>--build</option>, <option>--host</option>, and
- <option>--target</option> options. The <filename>mk/config.mk</filename>
- file defines several symbols related to the platform settings (see
- <filename>mk/config.mk</filename> for details).</para>
-
- <para>We don't currently support build & host being different, because
- the build process creates binaries that are both run during the build,
- and also installed.</para>
-
- <para>If host and target are different, then we are building a
- cross-compiler. For GHC, this means a compiler
- which will generate intermediate .hc files to port to the target
- architecture for bootstrapping. The libraries and stage 2 compiler
- will be built as HC files for the target system (see <xref
- linkend="sec-porting-ghc" /> for details.</para>
-
- <para>More details on when to use BUILD, HOST or TARGET can be found in
- the comments in <filename>config.mk</filename>.</para>
- </sect2>
-
- <sect2 id="sec-suffix">
- <title>Pattern rules and options</title>
- <indexterm><primary>Pattern rules</primary></indexterm>
-
- <para>The file
- <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
- defines standard <emphasis>pattern rules</emphasis> that say how
- to build one kind of file from another, for example, how to
- build a <filename>.o</filename> file from a
- <filename>.c</filename> file. (GNU <command>make</command>'s
- <emphasis>pattern rules</emphasis> are more powerful and easier
- to use than Unix <command>make</command>'s <emphasis>suffix
- rules</emphasis>.)</para>
-
- <para>Almost all the rules look something like this:</para>
-
-<programlisting>%.o : %.c
- $(RM) $@
- $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
-
- <para>Here's how to understand the rule. It says that
- <emphasis>something</emphasis><filename>.o</filename> (say
- <filename>Foo.o</filename>) can be built from
- <emphasis>something</emphasis><filename>.c</filename>
- (<filename>Foo.c</filename>), by invoking the C compiler (path
- name held in <constant>$(CC)</constant>), passing to it
- the options <constant>$(CC_OPTS)</constant> and
- the rule's dependent file of the rule
- <literal>$<</literal> (<filename>Foo.c</filename> in
- this case), and putting the result in the rule's target
- <literal>$@</literal> (<filename>Foo.o</filename> in this
- case).</para>
-
- <para>Every program is held in a <command>make</command>
- variable defined in <filename>mk/config.mk</filename>—look
- in <filename>mk/config.mk</filename> for the complete list. One
- important one is the Haskell compiler, which is called
- <constant>$(HC)</constant>.</para>
-
- <para>Every program's options are are held in a
- <command>make</command> variables called
- <constant><prog>_OPTS</constant>. the
- <constant><prog>_OPTS</constant> variables are
- defined in <filename>mk/opts.mk</filename>. Almost all of them
- are defined like this:</para>
-
-<programlisting>CC_OPTS = \
- $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
-
- <para>The four variables from which
- <constant>CC_OPTS</constant> is built have the following
- meaning:</para>
-
- <variablelist>
- <varlistentry>
- <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
- <listitem>
- <para>options passed to all C compilations.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
- <listitem>
- <para>options passed to C compilations for way
- <literal><way></literal>. For example,
- <constant>WAY_mp_CC_OPTS</constant>
- gives options to pass to the C compiler when compiling way
- <literal>mp</literal>. The variable
- <constant>WAY_CC_OPTS</constant> holds
- options to pass to the C compiler when compiling the
- standard way. (<xref linkend="sec-ways"/> dicusses
- multi-way compilation.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant><module>_CC_OPTS</constant>:</term>
- <listitem>
- <para>options to pass to the C compiler that are specific
- to module <literal><module></literal>. For example,
- <constant>SMap_CC_OPTS</constant> gives the
- specific options to pass to the C compiler when compiling
- <filename>SMap.c</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
- <listitem>
- <para>extra options to pass to all C compilations. This
- is intended for command line use, thus:</para>
-
-<screen>$ make libHS.a EXTRA_HC_OPTS="-v"</screen>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="sec-targets">
- <title>The main <filename>mk/target.mk</filename> file</title>
- <indexterm><primary>target.mk</primary></indexterm>
-
- <para><filename>target.mk</filename> contains canned rules for
- all the standard targets described in <xref
- linkend="sec-standard-targets"/>. It is complicated by the fact
- that you don't want all of these rules to be active in every
- <filename>Makefile</filename>. Rather than have a plethora of
- tiny files which you can include selectively, there is a single
- file, <filename>target.mk</filename>, which selectively includes
- rules based on whether you have defined certain variables in
- your <filename>Makefile</filename>. This section explains what
- rules you get, what variables control them, and what the rules
- do. Hopefully, you will also get enough of an idea of what is
- supposed to happen that you can read and understand any weird
- special cases yourself.</para>
-
- <variablelist>
- <varlistentry>
- <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
- <listitem>
- <para>If <constant>HS_PROG</constant> is defined,
- you get rules with the following targets:</para>
-
- <variablelist>
- <varlistentry>
- <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
- <listitem>
- <para>itself. This rule links
- <constant>$(OBJS)</constant> with the Haskell
- runtime system to get an executable called
- <constant>$(HS_PROG)</constant>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
- <listitem>
- <para>installs
- <constant>$(HS_PROG)</constant> in
- <constant>$(bindir)</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
- <listitem>
- <para>is similar to <constant>HS_PROG</constant>,
- except that the link step links
- <constant>$(C_OBJS)</constant> with the C
- runtime system.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
- <listitem>
- <para>is similar to <constant>HS_PROG</constant>,
- except that it links
- <constant>$(LIB_OBJS)</constant> to make the
- library archive <constant>$(LIBRARY)</constant>,
- and <literal>install</literal> installs it in
- <constant>$(libdir)</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Some rules are “double-colon” rules,
- thus</para>
-
-<programlisting>install :: $(HS_PROG)
- ...how to install it...</programlisting>
-
- <para>GNU <command>make</command> treats double-colon rules as
- separate entities. If there are several double-colon rules for
- the same target it takes each in turn and fires it if its
- dependencies say to do so. This means that you can, for
- example, define both <constant>HS_PROG</constant> and
- <constant>LIBRARY</constant>, which will generate two rules for
- <literal>install</literal>. When you type <command>make
- install</command> both rules will be fired, and both the program
- and the library will be installed, just as you wanted.</para>
- </sect2>
-
- <sect2 id="sec-subdirs">
- <title>Recursion</title>
- <indexterm><primary>recursion, in makefiles</primary></indexterm>
- <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
-
- <para>In leaf <filename>Makefile</filename>s the variable
- <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
- is undefined. In non-leaf <filename>Makefile</filename>s,
- <constant>SUBDIRS</constant> is set to the list of
- sub-directories that contain subordinate
- <filename>Makefile</filename>s. <emphasis>It is up to you to
- set <constant>SUBDIRS</constant> in the
- <filename>Makefile</filename>.</emphasis> There is no automation
- here—<constant>SUBDIRS</constant> is too important to
- automate.</para>
-
- <para>When <constant>SUBDIRS</constant> is defined,
- <filename>target.mk</filename> includes a rather neat rule for
- the standard targets (<xref linkend="sec-standard-targets"/> that
- simply invokes <command>make</command> recursively in each of
- the sub-directories.</para>
-
- <para><emphasis>These recursive invocations are guaranteed to
- occur in the order in which the list of directories is specified
- in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
- be important. For example, when you say <command>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).
- Generally, put the most independent sub-directory first, and the
- most dependent last.</para>
- </sect2>
-
- <sect2 id="sec-ways">
- <title>Way management</title>
- <indexterm><primary>way management</primary></indexterm>
-
- <para>We sometimes want to build essentially the same system in
- several different “ways”. For example, we want to build GHC's
- <literal>Prelude</literal> libraries with and without profiling,
- so that there is an appropriately-built library archive to link
- with when the user compiles his program. It would be possible
- to have a completely separate build tree for each such “way”,
- but it would be horribly bureaucratic, especially since often
- only parts of the build tree need to be constructed in multiple
- ways.</para>
-
- <para>Instead, the
- <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
- contains some clever magic to allow you to build several
- versions of a system; and to control locally how many versions
- are built and how they differ. This section explains the
- magic.</para>
-
- <para>The files for a particular way are distinguished by
- munging the suffix. The <quote>normal way</quote> is always
- built, and its files have the standard suffices
- <filename>.o</filename>, <filename>.hi</filename>, and so on.
- In addition, you can build one or more extra ways, each
- distinguished by a <emphasis>way tag</emphasis>. The object
- files and interface files for one of these extra ways are
- distinguished by their suffix. For example, way
- <literal>mp</literal> has files
- <filename>.mp_o</filename> and
- <filename>.mp_hi</filename>. Library archives have their
- way tag the other side of the dot, for boring reasons; thus,
- <filename>libHS_mp.a</filename>.</para>
-
- <para>A <command>make</command> variable called
- <constant>way</constant> holds the current way tag.
- <emphasis><constant>way</constant> is only ever set on the
- command line of <command>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>make</command>. Two other
- <command>make</command> variables,
- <constant>way_</constant> and
- <constant>_way</constant> are immediately derived from
- <constant>$(way)</constant> and never altered. If
- <constant>way</constant> is not set, then neither are
- <constant>way_</constant> and
- <constant>_way</constant>, and the invocation of
- <command>make</command> will build the <quote>normal
- way</quote>. If <constant>way</constant> is set, then the other
- two variables are set in sympathy. For example, if
- <constant>$(way)</constant> is “<literal>mp</literal>”,
- then <constant>way_</constant> is set to
- “<literal>mp_</literal>” and
- <constant>_way</constant> is set to
- “<literal>_mp</literal>”. These three variables are
- then used when constructing file names.</para>
-
- <para>So how does <command>make</command> ever get recursively
- invoked with <constant>way</constant> set? There are two ways
- in which this happens:</para>
-
- <itemizedlist>
- <listitem>
- <para>For some (but not all) of the standard targets, when
- in a leaf sub-directory, <command>make</command> is
- recursively invoked for each way tag in
- <constant>$(WAYS)</constant>. You set
- <constant>WAYS</constant> in the
- <filename>Makefile</filename> to the list of way tags you
- want these targets built for. The mechanism here is very
- much like the recursive invocation of
- <command>make</command> in sub-directories (<xref
- linkend="sec-subdirs"/>). It is up to you to set
- <constant>WAYS</constant> in your
- <filename>Makefile</filename>; this is how you control what
- ways will get built.</para>
- </listitem>
-
- <listitem>
- <para>For a useful collection of targets (such as
- <filename>libHS_mp.a</filename>,
- <filename>Foo.mp_o</filename>) there is a rule which
- recursively invokes <command>make</command> to make the
- specified target, setting the <constant>way</constant>
- variable. So if you say <command>make
- Foo.mp_o</command> you should see a recursive
- 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
- <filename>suffix.mk</filename>) look like this:
-
-<programlisting>%.$(way_)o : %.lhs
- $(HC) $(HC_OPTS) $< -o $@</programlisting>
-
- Neat, eh?</para>
- </listitem>
-
- <listitem>
- <para>You can invoke <command>make</command> with a
- particular <literal>way</literal> setting yourself, in order
- to build files related to a particular
- <literal>way</literal> in the current directory. eg.
-
-<screen>$ make way=p</screen>
-
- will build files for the profiling way only in the current
- directory. </para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>When the canned rule isn't right</title>
-
- <para>Sometimes the canned rule just doesn't do the right thing.
- For example, in the <literal>nofib</literal> suite we want the
- link step to print out timing information. The thing to do here
- is <emphasis>not</emphasis> to define
- <constant>HS_PROG</constant> or
- <constant>C_PROG</constant>, and instead define a special
- purpose rule in your own <filename>Makefile</filename>. By
- using different variable names you will avoid the canned rules
- being included, and conflicting with yours.</para>
- </sect2>
- </sect1>
-
- <sect1 id="building-docs">
- <title>Building the documentation</title>
-
- <sect2 id="pre-supposed-doc-tools">
- <title>Tools for building the Documentation</title>
-
- <para>The following additional tools are required if you want to
- format the documentation that comes with GHC:</para>
-
- <variablelist>
- <varlistentry>
- <term>DocBook
- <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
- <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>Much of our documentation is written in DocBook XML, instructions
- on installing and configuring the DocBook tools are below.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>TeX
- <indexterm><primary>pre-supposed: TeX</primary></indexterm>
- <indexterm><primary>TeX, pre-supposed</primary></indexterm>
- </term>
- <listitem>
- <para>A decent TeX distribution is required if you want to
- produce printable documentation. We recomment teTeX,
- which includes just about everything you need.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Haddock
- <indexterm><primary>Haddock</primary></indexterm>
- </term>
- <listitem>
- <para>Haddock is a Haskell documentation tool that we use
- for automatically generating documentation from the
- 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>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Installing the DocBook tools</title>
-
- <sect3>
- <title>Installing the DocBook tools on Linux</title>
-
- <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
- you probably have working DocBook tools already installed. The
- configure script should detect your setup and you're away.</para>
-
- <para>If you don't have DocBook tools installed, and you are
- using a system that can handle RPM packages, you can use <ulink
- url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
- packages for your system. Search for the packages
- <literal>docbook-dtd</literal>,
- <literal>docbook-xsl-stylesheets</literal>,
- <literal>libxslt</literal>,
- <literal>libxml2</literal>,
- <literal>fop</literal>,
- <literal>xmltex</literal>, and
- <literal>dvips</literal>.</para>
- </sect3>
-
- <sect3>
- <title>Installing DocBook on FreeBSD</title>
-
- <para>On FreeBSD systems, the easiest way to get DocBook up
- and running is to install it from the ports tree or a
- pre-compiled package (packages are available from your local
- FreeBSD mirror site).</para>
-
- <para>To use the ports tree, do this:
-<screen>$ cd /usr/ports/textproc/docproj
-$ make install</screen>
- This installs the FreeBSD documentation project tools, which
- includes everything needed to format the GHC
- documentation.</para>
- </sect3>
-
- <sect3>
- <title>Installing from binaries on Windows</title>
-
- <para>Probably the fastest route to a working DocBook environment on
- Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
- with the complete <literal>Doc</literal> category. If you are using
- <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
- have to help <command>configure</command> a little bit: Set the
- environment variables <envar>XmllintCmd</envar> and
- <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
- <command>xmllint</command> and <command>xsltproc</command>,
- respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
- of the directory where the XSL stylesheets are installed,
- e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
- </para>
-
- <para>If you want to build HTML Help, you have to install the
- <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
- too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Configuring the DocBook tools</title>
-
- <para>Once the DocBook tools are installed, the configure script
- will detect them and set up the build system accordingly. If you
- have a system that isn't supported, let us know, and we'll try
- to help.</para>
- </sect2>
-
- <sect2>
- <title>Building the documentation</title>
-
- <para>To build documentation in a certain format, you can
- say, for example,</para>
-
-<screen>$ make html</screen>
-
- <para>to build HTML documentation below the current directory.
- The available formats are: <literal>dvi</literal>,
- <literal>ps</literal>, <literal>pdf</literal>,
- <literal>html</literal>, and <literal>rtf</literal>. Note that
- not all documentation can be built in all of these formats: HTML
- documentation is generally supported everywhere, and DocBook
- documentation might support the other formats (depending on what
- other tools you have installed).</para>
-
- <para>All of these targets are recursive; that is, saying
- <literal>make html</literal> will make HTML docs for all the
- documents recursively below the current directory.</para>
-
- <para>Because there are many different formats that the DocBook
- documentation can be generated in, you have to select which ones
- you want by setting the <literal>XMLDocWays</literal> variable
- to a list of them. For example, in
- <filename>build.mk</filename> you might have a line:</para>
-
-<screen>XMLDocWays = html ps</screen>
-
- <para>This will cause the documentation to be built in the requested
- formats as part of the main build (the default is not to build
- any documentation at all).</para>
- </sect2>
-
- <sect2>
- <title>Installing the documentation</title>
-
- <para>To install the documentation, use:</para>
-
-<screen>$ make install-docs</screen>
-
- <para>This will install the documentation into
- <literal>$(datadir)</literal> (which defaults to
- <literal>$(prefix)/share</literal>). The exception is HTML
- documentation, which goes into
- <literal>$(datadir)/html</literal>, to keep things tidy.</para>
-
- <para>Note that unless you set <literal>$(XMLDocWays)</literal>
- to a list of formats, the <literal>install-docs</literal> target
- won't do anything for DocBook XML documentation.</para>
- </sect2>
-
- </sect1>
-
-
- <sect1 id="sec-porting-ghc">
- <title>Porting GHC</title>
-
- <para>This section describes how to port GHC to a currenly
- unsupported platform. 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>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 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>
-
- <sect2 id="sec-booting-from-hc">
- <title>Booting/porting from C (<filename>.hc</filename>) files</title>
-
- <indexterm><primary>building GHC from .hc files</primary></indexterm>
- <indexterm><primary>booting GHC from .hc files</primary></indexterm>
- <indexterm><primary>porting GHC</primary></indexterm>
-
- <para>Bootstrapping GHC on a system without GHC already
- installed is achieved by taking the intermediate C files (known
- as HC files) from another GHC compilation, compiling them using gcc to
- get a working GHC.</para>
-
- <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
- from C. We recommend using GHC 6.0.1 or
- 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.</para>
-
- <para>The following steps should result in a working GHC build
- with full libraries:</para>
-
- <itemizedlist>
- <listitem>
- <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>
-
- <listitem>
- <para>The actual build process is fully automated by the
- <filename>hc-build</filename> script located in the
- <filename>distrib</filename> directory. If you eventually
- want to install GHC into the directory
- <replaceable>dir</replaceable>, the following
- command will execute the whole build process (it won't
- install yet):</para>
-
-<screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
-<indexterm><primary>--hc-build</primary></indexterm>
-
- <para>By default, the installation directory is
- <filename>/usr/local</filename>. If that is what you want,
- you may omit the argument to <filename>hc-build</filename>.
- Generally, any option given to <filename>hc-build</filename>
- is passed through to the configuration script
- <filename>configure</filename>. If
- <filename>hc-build</filename> successfully completes the
- build process, you can install the resulting system, as
- normal, with</para>
-
-<screen>$ make install</screen>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="unregisterised-porting">
- <title>Porting GHC to a new platform</title>
-
- <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>
-
- <itemizedlist>
- <listitem>
- <para>Global register variables: certain abstract machine
- <quote>registers</quote> are mapped to real machine
- registers, depending on how many machine registers are
- available (see
- <filename>ghc/includes/MachRegs.h</filename>).</para>
- </listitem>
-
- <listitem>
- <para>Assembly-mangling: when compiling via C, we feed the
- assembly generated by gcc though a Perl script known as the
- <firstterm>mangler</firstterm> (see
- <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
- mangler rearranges the assembly to support tail-calls and
- various other optimisations.</para>
- </listitem>
- </itemizedlist>
-
- <para>In an unregisterised build, neither of these hacks are
- used — the idea is that the C code generated by the
- compiler should compile using gcc only. The lack of these
- optimisations costs about a factor of two in performance, but
- since unregisterised compilation is usually just a step on the
- way to a full registerised port, we don't mind too much.</para>
-
- <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
- experience most systems differ from the standards in one way or
- another. Deal with any problems as they arise - if you get
- stuck, ask the experts on
- <email>glasgow-haskell-users@haskell.org</email>.</para>
-
- <para>Lots of useful information about the innards of GHC is
- available in the <ulink
- url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
- Commentary</ulink>, which might be helpful if you run into some
- code which needs tweaking for your system.</para>
-
- <sect3>
- <title>Cross-compiling to produce an unregisterised GHC</title>
-
- <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
- later. If you need instructions for an earlier version of GHC, try
- to get hold of the version of this document that was current at the
- time. It should be available from the appropriate download page on
- the <ulink
- url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
-
- <para>In this section, we explain how to bootstrap GHC on a
- new platform, using unregisterised intermediate C files. We
- haven't put a great deal of effort into automating this
- process, for two reasons: it is done very rarely, and the
- process usually requires human intervention to cope with minor
- porting issues anyway.</para>
-
- <para>The following step-by-step instructions should result in
- a fully working, albeit unregisterised, GHC. Firstly, you
- need a machine that already has a working GHC (we'll call this
- the <firstterm>host</firstterm> machine), in order to
- cross-compile the intermediate C files that we will use to
- bootstrap the compiler on the <firstterm>target</firstterm>
- machine.</para>
-
- <itemizedlist>
- <listitem>
- <para>On the target machine:</para>
-
- <itemizedlist>
- <listitem>
- <para>Unpack a source tree (preferably a released
- version). We will call the path to the root of this
- tree <replaceable>T</replaceable>.</para>
- </listitem>
-
- <listitem>
-<screen>$ cd <replaceable>T</replaceable>
-$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
-
- <para>You might need to update
- <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>/includes
-$ make</screen>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>On the host machine:</para>
-
- <itemizedlist>
- <listitem>
- <para>Unpack a source tree (same released version). Call
- this directory <replaceable>H</replaceable>.</para>
- </listitem>
-
- <listitem>
-<screen>$ cd <replaceable>H</replaceable>
-$ ./configure</screen>
- </listitem>
-
- <listitem>
- <para>Create
- <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
- with the following contents:</para>
-
-<programlisting>GhcUnregisterised = YES
-GhcLibHcOpts = -O -fvia-C -keep-hc-files
-GhcRtsHcOpts = -keep-hc-files
-GhcLibWays =
-SplitObjs = NO
-GhcWithNativeCodeGen = NO
-GhcWithInterpreter = NO
-GhcStage1HcOpts = -O
-GhcStage2HcOpts = -O -fvia-C -keep-hc-files
-SRC_HC_OPTS += -H32m
-GhcBootLibs = YES
-GhcWithSMP = NO</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit
- <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
- <itemizedlist>
- <listitem>
- <para>change <literal>TARGETPLATFORM</literal>
- appropriately, and set the variables involving
- <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
- <literal>--host</literal> and
- <literal>--target</literal> flags.</para>
- </listitem>
- <listitem>
- <para>copy <literal>LeadingUnderscore</literal>
- setting from target.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Copy
- <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>/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
- be suitable for compiling on the target system.</para>
- </listitem>
-
- <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>/includes
-$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
-$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
- </listitem>
-
- <listitem>
- <para>Now build the compiler:</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>
-<screen>$ cd <replaceable>H</replaceable>/libraries
-$ make boot && make</screen>
- </listitem>
-
- <listitem>
-<screen>$ cd <replaceable>H</replaceable>/compiler
-$ make boot stage=2 && make stage=2</screen>
- </listitem>
-
- <listitem>
-<screen>$ cd <replaceable>H</replaceable>/compat
-$ make clean
-$ rm .depend
-$ 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>
-
- <listitem>
-<screen>$ cd <replaceable>H</replaceable>
-$ make hc-file-bundle Project=Ghc</screen>
- </listitem>
-
- <listitem>
- <para>copy
- <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
- to <filename><replaceable>T</replaceable>/..</filename>.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>On the target machine:</para>
-
- <para>At this stage we simply need to bootstrap a compiler
- 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>
-
-<screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
-
- <para>However, since this is a bootstrap on a new machine,
- the automated process might not run to completion the
- first time. For that reason, you might want to treat the
- <literal>hc-build</literal> script as a list of
- instructions to follow, rather than as a fully automated
- script. This way you'll be able to restart the process
- part-way through if you need to fix anything on the
- way.</para>
-
- <para>Don't bother with running
- <literal>make install</literal> in the newly
- bootstrapped tree; just use the compiler in that tree to
- build a fresh compiler from scratch, this time without
- booting from C files. Before doing this, you might want
- to check that the bootstrapped compiler is generating
- working binaries:</para>
-
-<screen>$ cat >hello.hs
-main = putStrLn "Hello World!\n"
-^D
-$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
-$ ./hello
-Hello World!</screen>
-
- <para>Once you have the unregisterised compiler up and
- running, you can use it to start a registerised port. The
- following sections describe the various parts of the
- system that will need architecture-specific tweaks in
- order to get a registerised build going.</para>
-
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Porting the RTS</title>
-
- <para>The following files need architecture-specific code for a
- registerised build:</para>
-
- <variablelist>
- <varlistentry>
- <term><filename>ghc/includes/MachRegs.h</filename>
- <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
- </term>
- <listitem>
- <para>Defines the STG-register to machine-register
- mapping. You need to know your platform's C calling
- convention, and which registers are generally available
- for mapping to global register variables. There are
- plenty of useful comments in this file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>ghc/includes/TailCalls.h</filename>
- <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
- </term>
- <listitem>
- <para>Macros that cooperate with the mangler (see <xref
- linkend="sec-mangler"/>) to make proper tail-calls
- work.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>ghc/rts/Adjustor.c</filename>
- <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
- </term>
- <listitem>
- <para>Support for
- <literal>foreign import "wrapper"</literal>
- (aka
- <literal>foreign export dynamic</literal>).
- Not essential for getting GHC bootstrapped, so this file
- can be deferred until later if necessary.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>ghc/rts/StgCRun.c</filename>
- <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
- </term>
- <listitem>
- <para>The little assembly layer between the C world and
- the Haskell world. See the comments and code for the
- other architectures in this file for pointers.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>ghc/rts/MBlock.h</filename>
- <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
- </term>
- <term><filename>ghc/rts/MBlock.c</filename>
- <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
- </term>
- <listitem>
- <para>These files are really OS-specific rather than
- architecture-specific. In <filename>MBlock.h</filename>
- is specified the absolute location at which the RTS
- should try to allocate memory on your platform (try to
- find an area which doesn't conflict with code or dynamic
- libraries). In <filename>Mblock.c</filename> you might
- need to tweak the call to <literal>mmap()</literal> for
- your OS.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- <sect3 id="sec-mangler">
- <title>The mangler</title>
-
- <para>The mangler is an evil Perl-script
- (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
- rearranges the assembly code output from gcc to do two main
- things:</para>
-
- <itemizedlist>
- <listitem>
- <para>Remove function prologues and epilogues, and all
- movement of the C stack pointer. This is to support
- tail-calls: every code block in Haskell code ends in an
- explicit jump, so we don't want the C-stack overflowing
- while we're jumping around between code blocks.</para>
- </listitem>
- <listitem>
- <para>Move the <firstterm>info table</firstterm> for a
- closure next to the entry code for that closure. In
- unregisterised code, info tables contain a pointer to the
- entry code, but in registerised compilation we arrange
- that the info table is shoved right up against the entry
- code, and addressed backwards from the entry code pointer
- (this saves a word in the info table and an extra
- indirection when jumping to the closure entry
- code).</para>
- </listitem>
- </itemizedlist>
-
- <para>The mangler is abstracted to a certain extent over some
- architecture-specific things such as the particular assembler
- directives used to herald symbols. Take a look at the
- definitions for other architectures and use these as a
- starting point.</para>
- </sect3>
-
- <sect3>
- <title>The splitter</title>
-
- <para>The splitter is another evil Perl script
- (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
- cooperates with the mangler to support object splitting.
- Object splitting is what happens when the
- <option>-split-objs</option> option is passed to GHC: the
- object file is split into many smaller objects. This feature
- is used when building libraries, so that a program statically
- linked against the library will pull in less of the
- library.</para>
-
- <para>The splitter has some platform-specific stuff; take a
- look and tweak it for your system.</para>
- </sect3>
-
- <sect3>
- <title>The native code generator</title>
-
- <para>The native code generator isn't essential to getting a
- registerised build going, but it's a desirable thing to have
- because it can cut compilation times in half. The native code
- generator is described in some detail in the <ulink
- url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
- commentary</ulink>.</para>
- </sect3>
-
- <sect3>
- <title>GHCi</title>
-
- <para>To support GHCi, you need to port the dynamic linker
- (<filename>$(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 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>
- </sect3>
- </sect2>
-
- </sect1>
-
-<sect1 id="sec-build-pitfalls">
-<title>Known pitfalls in building Glasgow Haskell
-
-<indexterm><primary>problems, building</primary></indexterm>
-<indexterm><primary>pitfalls, in building</primary></indexterm>
-<indexterm><primary>building pitfalls</primary></indexterm></title>
-
-<para>
-WARNINGS about pitfalls and known “problems”:
-</para>
-
-<para>
-
-<orderedlist>
-<listitem>
-
-<para>
-One difficulty that comes up from time to time is running out of space
-in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
-compensate for the vagaries of different sysadmin approaches to temp
-space.)
-<indexterm><primary>tmp, running out of space in</primary></indexterm>
-
-The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
-even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
-of choice).
-
-The best way around it is to say
-
-<programlisting>export TMPDIR=<dir></programlisting>
-
-in your <filename>build.mk</filename> file. Then GHC and the other
-tools will use the appropriate directory in all cases.
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
-in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
-are OK.
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-When compiling via C, you'll sometimes get “warning: assignment from
-incompatible pointer type” out of GCC. Harmless.
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-Similarly, <command>ar</command>chiving warning messages like the following are not
-a problem:
-
-<screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
-ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
-...</screen>
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
- In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
-get an “Out of heap space” error message. These can vary with the
-vagaries of different systems, it seems. The solution is simple:
-
-
-<itemizedlist>
-<listitem>
-
-<para>
- If you're compiling with GHC 4.00 or later, then the
-<emphasis>maximum</emphasis> heap size must have been reached. This
-is somewhat unlikely, since the maximum is set to 64M by default.
-Anyway, you can raise it with the
-<option>-optCrts-M<size></option> flag (add this flag to
-<constant><module>_HC_OPTS</constant>
-<command>make</command> variable in the appropriate
-<filename>Makefile</filename>).
-
-</para>
-</listitem>
-<listitem>
-
-<para>
- For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
-above.
-
-</para>
-</listitem>
-
-</itemizedlist>
-
-
-and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about
-<constant><module>_HC_OPTS</constant>.)
-
-Alternatively, just cut to the chase:
-
-<screen>$ cd ghc/compiler
-$ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-If you try to compile some Haskell, and you get errors from GCC about
-lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
-mis-installed. <command>fixincludes</command> wasn't run when it should've been.
-
-As <command>fixincludes</command> is now automagically run as part of GCC installation,
-this bug also suggests that you have an old GCC.
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
-
-
-<screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
-$ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
-? ranlib $i
-? # or, on some machines: ar s $i
-? end</screen>
-
-
-We'd be interested to know if this is still necessary.
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
-GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
-a bit from one Unix to another. One particular gotcha is macro calls
-like this:
-
-
-<programlisting>SLIT("Hello, world")</programlisting>
-
-
-Some <command>cpp</command>s treat the comma inside the string as separating two macro
-arguments, so you get
-
-
-<screen>:731: macro `SLIT' used with too many (2) args</screen>
-
-
-Alas, <command>cpp</command> doesn't tell you the offending file!
-
-Workaround: don't put weird things in string args to <command>cpp</command> macros.
-</para>
-</listitem>
-
-</orderedlist>
-
-</para>
-
-</sect1>
-
-
-<sect1 id="platforms"><title>Platforms, scripts, and file names</title>
-<para>
-GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
-gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
-</para>
-
-<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
-
-<para> The build system is built around Unix-y makefiles. Because it's not native,
-the Windows situation for building GHC is particularly confusing. This section
-tries to clarify, and to establish terminology.</para>
-
-<sect3 id="ghc-mingw"><title>MinGW</title>
-
-<para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
-is a collection of header
-files and import libraries that allow one to use <command>gcc</command> and produce
-native Win32 programs that do not rely on any third-party DLLs. The
-current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
-Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
-other utilities.
-</para>
-
-<para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
-Posix interface.
-</para>
-</sect3>
-
-<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
-
-<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
-or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
-<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>.
-For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
-and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
-
-<itemizedlist>
-<listitem><para>
-Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
-compile code that has access to all of Posix. The price is that the executables must be
-dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
-that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
-does not change, but the implementation certainly does. Even the interfaces to functions
-it exports seem to change occasionally. </para>
-</listitem>
-
-<listitem><para>
-MSYS is a fork of the Cygwin tree, so they
-are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
-through fewer layers, so MSYS is quite a bit faster too.
-</para>
-
-<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
-compile binaries that run with no DLL support, on any Win32 system.
-However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
-<command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the
-MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
-</para>
-<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
-<command>ssh</command> and so on),
-not by programs compiled under MSYS.
-</para></listitem>
-
-</itemizedlist>
-
-</para>
-</sect3>
-
-<sect3><title>Targeting MinGW</title>
-
-<para>We want GHC to compile programs that work on any Win32 system. Hence:
-<itemizedlist>
-<listitem><para>
-GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
-invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
-will work on any system, but it also means that the programs GHC compiles do not have access
-to all of Posix. In particular, they cannot import the (Haskell) Posix
-library; they have to do
-their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
-<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
-</listitem>
-
-<listitem><para>
-To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
-<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
-</para></listitem>
-</itemizedlist>
-So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
-It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
-that targets Cygwin instead. The up-side of GHC-cygwin is
-that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
-<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
-</para>
-
-<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
-how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
-GHC; both work fine, though MSYS is rather lighter weight.</para>
-
-<para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
-uses the <command>gcc</command> that you specify using the
-<option>--with-gcc</option> flag when you run
-<command>configure</command> (see below).
-The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
-to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
-whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
-and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
-used to glom together .o files into a bigger .o file, or a .a file,
-so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
-Cygwin and MinGW use the same .o file format. So its ok.
-</para>
-</sect3>
-
-<sect3><title> File names </title>
-
-<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
-However:
-<itemizedlist>
-<listitem><para>
-MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
-<filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
-</para>
-<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
-directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
-arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
-if you invoke
-<programlisting>foogle -B/c/tmp/baz</programlisting>
-the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
-</para></listitem>
-
-<listitem><para>
-Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
-</para>
-<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
-</para></listitem>
-</itemizedlist>
-</para>
-</sect3>
-
-<sect3><title>Crippled <command>ld</command></title>
-
-<para>
-It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
-limit of 32kbytes on its command line. Especially when using split object
-files, the make system can emit calls to <command>ld</command> with thousands
-of files on it. Then you may see something like this:
-<programlisting>
-(cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
-/bin/sh: /mingw/bin/ld: Invalid argument
-</programlisting>
-The solution is either to switch off object file splitting (set
-<option>SplitObjs</option> to <literal>NO</literal> in your
-<filename>build.mk</filename>),
-or to make the module smaller.
-</para>
-</sect3>
-
-<sect3><title>Host System vs Target System</title>
-
-<para>
-In the source code you'll find various ifdefs looking like:
-<programlisting>#ifdef mingw32_HOST_OS
- ...blah blah...
-#endif</programlisting>
-and
-<programlisting>#ifdef mingw32_TARGET_OS
- ...blah blah...
-#endif</programlisting>
-These macros are set by the configure script (via the file config.h).
-Which is which? The criterion is this. In the ifdefs in GHC's source code:
-<itemizedlist>
- <listitem>
- <para>The "host" system is the one on which GHC itself will be run.</para>
- </listitem>
- <listitem>
- <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
- </listitem>
-</itemizedlist>
-For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
-So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
-
-</para>
-</sect3>
-
-</sect2>
-
-<sect2><title>Wrapper scripts</title>
-
-<para>
-Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
-For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
-GHC itself as an example:
-<itemizedlist>
- <listitem> <para>
- On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
- paths to the front of the source file <filename>ghc.sh</filename>,
- that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
- where to find its supporting files.
- </para> </listitem>
-
- <listitem> <para>
- On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
- native Windows shell <command>cmd</command> (e.g. limits on the length
- of the command line). So instead we invoke the GHC binary directly, with no -B flag.
- GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
- and from that figures out where the supporting files are.
- </para> </listitem>
-</itemizedlist>
-(You can find the layout of GHC's supporting files in the
- section "Layout of installed files" of Section 2 of the GHC user guide.)
-</para>
-<para>
-Things work differently for <emphasis>in-place</emphasis> execution, where you want to
-execute a program that has just been built in a build tree. The difference is that the
-layout of the supporting files is different.
-In this case, whether on Windows or Unix, we always use a shell script. This works OK
-on Windows because the script is executed by MSYS or Cygwin, which don't have the
-shortcomings of the native Windows <command>cmd</command> shell.
-</para>
-
-</sect2>
-
-</sect1>
-
-<sect1 id="winbuild"><title>Instructions for building under Windows</title>
-
-<para>
-This section gives detailed instructions for how to build
-GHC from source on your Windows machine. Similar instructions 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.
-</para>
-<para>
-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>
-
-
-<sect2 id="msys-install"><title>Installing and configuring MSYS</title>
-
-<para>
-MSYS is a lightweight alternative to Cygwin.
-You don't need MSYS to <emphasis>use</emphasis> GHC,
-but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
-Here's how to install MSYS.
-<itemizedlist>
-<listitem><para>
-Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
-download the following (of course, the version numbers will differ):
-<itemizedlist>
- <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
- </para></listitem>
- <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
- This provides <command>make</command>, <command>autoconf</command>,
- <command>ssh</command> and probably more besides.
- </para></listitem>
-</itemizedlist>
-Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
-</para></listitem>
-
-<listitem><para>
-Set the following environment variables
-<itemizedlist>
- <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
- <literal>c:/msys/1.0/local/bin</literal>
- to your path. (Of course, the version number may differ.)
- MSYS mounts the former as both <literal>/bin</literal> and
- <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
- </para></listitem>
-
- <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
- This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
- </para></listitem>
-
- <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
- </para></listitem>
-
- <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
- you are using CVS.
- </para></listitem>
-
- <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
- </para></listitem>
-
-</itemizedlist>
-</para></listitem>
-
-<listitem><para>
-Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
-that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
-causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
-file has too-liberal permissinos.
-</para></listitem>
-
-</itemizedlist>
-</para>
-<para>Here are some points to bear in mind when using MSYS:
-<itemizedlist>
-<listitem> <para> MSYS does some kind of special magic to binaries stored in
-<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
-to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
-Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
-they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
-which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
-
-<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
-</para></listitem>
-
-<listitem> <para>
-Win32 has a <command>find</command> command which is not the same as MSYS's find.
-You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
-before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
-environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
-variable. You can always invoke <command>find</command> with an absolute path, or rename it.
-</para></listitem>
-
-<listitem> <para>
-MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
-will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
-bzip'd dump.</para></listitem>
-
-</itemizedlist>
-</para>
-</sect2>
-
-<sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
-
-<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
-The installation process is straightforward; we install it in
-<filename>c:/cygwin</filename>.</para>
-<para>
-You must install enough Cygwin <emphasis>packages</emphasis> to support
-building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
-<itemizedlist>
-<listitem><para>The direct, but laborious way is to
-select all of the following packages in the installation dialogue:
- <command>cvs</command>,
- <command>openssh</command>,
- <command>autoconf</command>,
- <command>binutils</command> (includes ld and (I think) ar),
- <command>gcc</command>,
- <command>flex</command>,
- <command>make</command>.
-To see thse packages,
-click on the "View" button in the "Select Packages"
-stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
-"Category" isn't very helpful, and the "View" button is rather unobtrousive.
-</para>
-</listitem>
-
-<listitem><para>The clever way is to point the Cygwin installer at the
-<command>ghc-depends</command> package, which is kept at <ulink
-url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
-When the Cygwin installer asks you to "Choose a Download Site", choose one of
-the
-offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
-"User URL" box and click "Add"; now two sites are selected. (The Cygwin
-installer remembers this for next time.)
-Click "Next".</para>
-<para>In the "Select Packages" dialogue box that follows, click the "+" sign by
-"Devel", scroll down to the end of the "Devel" packages, and choose
-<command>ghc-depends</command>.
-The package <command>ghc-depends</command> will not actually install anything itself,
-but forces additional packages to be added by the Cygwin installer.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para> Now set the following user environment variables:
-<itemizedlist>
-
-<listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
-<constant>PATH</constant></para></listitem>
-
-<listitem>
-<para>
-Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
-don't do this you get very weird messages when you type
-<command>make</command>, such as:
-<screen>/c: /c: No such file or directory</screen>
-</para>
-</listitem>
-
-<listitem><para> Set <constant>SHELL</constant> to
-<filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
-<constant>SHELL</constant> is what you get.
-</para></listitem>
-
-<listitem><para> Set <constant>HOME</constant> to point to your
-home directory. This is where, for example,
-<command>bash</command> will look for your <filename>.bashrc</filename>
-file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
-</para></listitem>
-</itemizedlist>
-</para>
-
-<para>Here are some things to be aware of when using Cygwin:
-<itemizedlist>
-<listitem> <para>Cygwin doesn't deal well with filenames that include
-spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
-common gotchas.
-</para></listitem>
-
-<listitem> <para> Cygwin implements a symbolic link as a text file with some
-magical text in it. So other programs that don't use Cygwin's
-I/O libraries won't recognise such files as symlinks.
-In particular, programs compiled by GHC are meant to be runnable
-without having Cygwin, so they don't use the Cygwin library, so
-they don't recognise symlinks.
-</para></listitem>
-
-<listitem> <para>
-See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
-which apply to Cygwin too.
-</para></listitem>
-
-<listitem>
-<para>
-Some script files used in the make system start with "<command>#!/bin/perl</command>",
-(and similarly for <command>sh</command>). Notice the hardwired path!
-So you need to ensure that your <filename>/bin</filename> directory has at least
-<command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
-All these come in Cygwin's <filename>bin</filename> directory, which you probably have
-installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
-<filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
-(You can discover where your Cygwin
-root directory <filename>/</filename> is by typing <command>mount</command>.)
-Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
-directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
-directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
-</para>
-</listitem>
-
-<listitem>
-<para>
-By default, cygwin provides the command shell <filename>ash</filename>
-as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
-saw build-system problems that turned out to be due to bugs in <filename>ash</filename>
-(to do with quoting and length of command lines). On the other hand <filename>bash</filename> seems
-to be rock solid.
-If this happens to you (which it shouldn't), in <filename>cygwin/bin</filename>
-remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
-and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
-You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
-you can't rename a running program!
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-</sect2>
-
-
-<sect2 id="configure-ssh"><title>Configuring SSH</title>
-
-<para><command>ssh</command> comes with both Cygwin and MSYS.
-(Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
-in the Cygwin list of packages; or use the <command>ghc-depends</command>
-package -- see <xref linkend="install-cygwin"/>.)</para>
-
-<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
-<itemizedlist>
-<listitem>
-<para>
- The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
- seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
- they ask for a password). To solve this, start up <filename>cmd.exe</filename>
- and run it as follows:
-<screen>c:\tmp> set CYGWIN32=tty
-c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
-</listitem>
-
-<listitem><para> (Cygwin-only problem, I think.)
-<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
-To determine your home directory <command>ssh</command> first looks in
-<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
-there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
-the setting of the environment variable $HOME</emphasis>. If the home directory is
-bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
-<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
-<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
-you do that, <command>ssh</command> uses the $HOME environment variable instead.
-</para>
-
-</listitem>
-
-<listitem>
- <para>To protect your
- <literal>.ssh</literal> from access by anyone else,
- right-click your <literal>.ssh</literal> directory, and
- select <literal>Properties</literal>. If you are not on
- the access control list, add yourself, and give yourself
- full permissions (the second panel). Remove everyone else
- from the access control list. Don't leave them there but
- deny them access, because 'they' may be a list that
- includes you!</para>
-</listitem>
-
-<listitem>
- <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
- you to have Unix permissions 600 (read/write for owner only)
- on the <literal>.ssh/identity</literal> file, else it
- bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
- but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
- The solution seems to be to set the $CYGWIN environment
- variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
- in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
- and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
- </para>
-</listitem>
-</itemizedlist>
-</para>
-</sect2>
-
-<sect2><title>Other things you need to install</title>
-
-<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 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,
-<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
-provided they are in your path.
-<itemizedlist>
-<listitem>
-<para>
-Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
-This is what you will use to compile GHC. Add it in your
-<constant>PATH</constant>: the installer tells you the path element
-you need to add upon completion.
-</para>
-</listitem>
-
-<listitem>
-<para>
-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
-<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
-<constant>PATH</constant>.
-</para>
-</listitem>
-
- <listitem>
- <para>Install an executable Alex. This can be done by building from the
- source distribution in the same way as Happy. Sources are
- available from <ulink
- url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
- </listitem>
-
-<listitem>
-<para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
-Just pick up a mingw bundle at
-<ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
-We install it in <filename>c:/mingw</filename>.
-</para>
-
-<para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
-<command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
-in your path.
-</para>
-
-<para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
-They are only going to get used by explicit access (via the --with-gcc flag you
-give to <command>configure</command> later). If you do add them to your path
-you are likely to get into a mess because their names overlap with Cygwin
-binaries.
-On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
-(and perhaps one or two other things) in your path. The Cygwin ones are fine,
-but you must have them; hence needing the Cygwin binutils package.
-</para>
-</listitem>
-
-
-<listitem>
-<para>We use <command>emacs</command> a lot, so we install that too.
-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>$(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>
-
- <listitem>
- <para>You might want to install GLUT in your MSYS/Cygwin
- installation, otherwise the GLUT package will not be built with
- GHC.</para>
- </listitem>
-
-<listitem>
-<para> Finally, check out a copy of GHC sources from
-the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
-</listitem>
-</itemizedlist>
-</para>
-</sect2>
-
-<sect2><title>Building GHC</title>
-
-<para>OK!
-Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
-the bullets below only tell
-you about Windows-specific wrinkles.</para>
-<itemizedlist>
-<listitem>
-<para>
-If you used <command>autoconf</command> instead of <command>autoreconf</command>,
-you'll get an error when you run <filename>./configure</filename>:
-<screen>
-...lots of stuff...
-creating mk/config.h
-mk/config.h is unchanged
-configuring in ghc
-running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
-./configure: ./configure: No such file or directory
-configure: error: ./configure failed for ghc</screen>
-</para>
-</listitem>
-
-<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
-read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
-you get
-<screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
-Solution: delete <filename>configure</filename> first.
-</para></listitem>
-
-<listitem>
- <para>
- After <command>autoreconf</command> run <command>./configure</command> in
- <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
-(see <xref linkend="ghc-mingw"/>). </para>
-
-<para> Both these options are important! It's possible to get into
-trouble using the wrong C compiler!</para>
-<para>
-Furthermore, it's <emphasis>very important</emphasis> that you specify a
-full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
-uses this path to invoke <command>gcc</command>) is a MinGW program and won't
-understand a Cygwin path. For example, if you
-say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
-<filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
-time it tries to invoke it. Worse, the failure comes with
-no error message whatsoever. GHC simply fails silently when first invoked,
-typically leaving you with this:
-<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
- -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
- -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
- -optc-fomit-frame-pointer -O2 -static
- -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
-make[2]: *** [Adjustor.o] Error 1
-make[1]: *** [all] Error 1
-make[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc'
-make: *** [all] Error 1</screen>
-Be warned!
-</para>
-
-<para>
-If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
-you'll have to do something more like:
-<screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
-</para>
-</listitem>
-
-<listitem><para>
-If you are paranoid, delete <filename>config.cache</filename> if it exists.
-This file occasionally remembers out-of-date configuration information, which
-can be really confusing.
-</para>
-</listitem>
-
-<listitem><para> You almost certainly want to set
-<programlisting>SplitObjs = NO</programlisting>
-in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
-This tells the build system not to split each library into a myriad of little object files, one
-for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
-it dramatically increases the time taken to build the libraries in the first place.
-</para>
-</listitem>
-
-<listitem><para> Do not attempt to build the documentation.
-It needs all kinds of wierd Jade stuff that we haven't worked out for
-Win32.</para></listitem>
-</itemizedlist>
-</sect2>
-
-
-<sect2><title>A Windows build log using Cygwin</title>
-
-<para>Here is a complete, from-scratch, log of all you need to build GHC using
-Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
-choices, but it gives a single path that works.</para>
-<programlisting>- Install some editor (vim, emacs, whatever)
-
-- Install cygwin (http://www.cygwin.com)
- ; i used 1.5.16-1, installed in c:\cygwin
- - run 'setup.exe'
- Choose a Download Source:
- select 'download from internet';
- Select Root Install Directory:
- root dir: c:\cygwin;
- install for: all users;
- default file type: unix
- Select Local Package Directory
- choose a spare temporary home
- Select Your Internet Connection
- Use IE5 settings
- Choose a Download Site
- Choose your preferred main mirror and
- Add 'http://www.haskell.org/ghc/cygwin'
- Select Packages
- In addition to 'Base' (default install),
- select 'Devel->ghc-depends'
-
-- Install mingw (http://www.mingw.org/)
- ; i used MinGW-3.1.0-1.exe
- ; installed in c:\mingw
- - you probably want to add GLUT
- ; (http://www.xmission.com/~nate/glut.html)
- ; i used glut-3.7.3-mingw32.tar
-
-- Get recent binary snapshot of ghc-6.4.1 for mingw
- ; (http://www.haskell.org/ghc/dist/stable/dist/)
- - unpack in c:/ghc
- - add C:\ghc\ghc-6.4.1\bin to %PATH%
- (Start->Control Panel->System->Advanced->Environment Variables)
-
-- Get darcs version of ghc
- ; 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:/ghc-build; cd c:/ghc-build
- ; (or whereever you want your darcs tree to be)
- - darcs get http://darcs.haskell.org/ghc
- - cd ghc
- - chmod +x darcs-all
- - ./darcs-all get
-
-- Build ghc, using cygwin and mingw, targetting mingw
- - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
- ; for haddock, alex, happy (*)
- - export PATH=/cygdrive/c/mingw/bin:$PATH
- ; without, we pick up some cygwin tools at best!
- - cd c:/ghc-build
- ; (if you aren't there already)
- - autoreconf
- - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
- ; we use cygwin, but build for windows
- - cp mk/build.mk.sample mk/build.mk
- - in mk/build.mk:
- add line: SplitObjs = NO
- (MSYS seems slow when there are zillions of object files)
- uncomment line: BuildFlavour = perf
- (or BuildFlavour = devel, if you are doing development)
- add line: BIN_DIST=1
- - make 2>&1 | tee make.log
- ; always useful to have a log around
-
-- Package up binary distribution
- - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
- ; always useful to have a log around
- - cd ghc-6.5
- - chmod +x ../distrib/prep-bin-dist-mingw
- ; if you're happy with the script's contents (*)
- - ../distrib/prep-bin-dist-mingw
- ; then tar up, unpack where wanted, and enjoy</programlisting>
-</sect2>
-</sect1>
-
-<index/>
-
-</article>
projects / ghc-hetmet.git / commitdiff