+<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 the
+ <literal>fptools</literal> projects:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>DocBook</term>
+ <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
+ <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>Much of our documentation is written in SGML, using
+ the DocBook DTD. Instructions on installing and
+ configuring the DocBook tools are below.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TeX</term>
+ <indexterm><primary>pre-supposed: TeX</primary></indexterm>
+ <indexterm><primary>TeX, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>A decent TeX distribution is required if you want to
+ produce printable documentation. We recomment teTeX,
+ which includes just about everything you need.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Haddock</term>
+ <indexterm><primary>Haddock</primary>
+ </indexterm>
+ <listitem>
+ <para>Haddock is a Haskell documentation tool that we use
+ for automatically generating documentation from the
+ library source code. It is an <literal>fptools</literal>
+ project in itself. To build documentation for the
+ libraries (<literal>fptools/libraries</literal>) you
+ should check out and build Haddock in
+ <literal>fptools/haddock</literal>. Haddock requires GHC
+ 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 system (7.0+), 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 RedHat RPM packages, you can
+ probably use the <ULink
+ URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
+ DocBook tools</ULink>, which is the most shrink-wrapped SGML
+ suite that we could find. You need all the RPMs except for
+ psgml (i.e. <Filename>docbook</Filename>,
+ <Filename>jade</Filename>, <Filename>jadetex</Filename>,
+ <Filename>sgmlcommon</Filename> and
+ <Filename>stylesheets</Filename>). Note that most of these
+ RPMs are architecture neutral, so are likely to be found in a
+ <Filename>noarch</Filename> directory. The SuSE RPMs also
+ work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
+ (7.0 and later should be OK), but they are easy to fix: just
+ make a symlink from
+ <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
+ to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </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>It's a good idea to use Norman Walsh's <ULink
+ URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
+ notes</ULink> as a guide. You should get version 3.1 of
+ DocBook, and note that his file <Filename>test.sgm</Filename>
+ won't work, as it needs version 3.0. You should unpack Jade
+ into <Filename>\Jade</Filename>, along with the entities,
+ DocBook into <Filename>\docbook</Filename>, and the DocBook
+ stylesheets into <Filename>\docbook\stylesheets</Filename> (so
+ they actually end up in
+ <Filename>\docbook\stylesheets\docbook</Filename>).</para>
+ </Sect3>
+
+
+ <sect3>
+ <title>Installing the DocBook tools from source</title>
+
+ <sect4>
+ <title>Jade</title>
+
+ <para>Install <ULink
+ URL="http://openjade.sourceforge.net/">OpenJade</ULink>
+ (Windows binaries are available as well as sources). If you
+ want DVI, PS, or PDF then install JadeTeX from the
+ <Filename>dsssl</Filename> subdirectory. (If you get the
+ error:
+
+<screen>
+! LaTeX Error: Unknown option implicit=false' for package hyperref'.
+</screen>
+
+ your version of <Command>hyperref</Command> is out of date;
+ download it from CTAN
+ (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
+ and make it, ensuring that you have first removed or renamed
+ your old copy. If you start getting file not found errors
+ when making the test for <Command>hyperref</Command>, you
+ can abort at that point and proceed straight to
+ <Command>make install</Command>, or enter them as
+ <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
+
+ <para>Make links from <Filename>virtex</Filename> to
+ <Filename>jadetex</Filename> and
+ <Filename>pdfvirtex</Filename> to
+ <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
+ and PDF output will not work). Copy
+ <Filename>dsssl/*.{dtd,dsl}</Filename> and
+ <Filename>catalog</Filename> to
+ <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+ </sect4>
+
+ <sect4>
+ <title>DocBook and the DocBook stylesheets</title>
+
+ <para>Get a Zip of <ULink
+ URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
+ and install the contents in
+ <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
+
+ <para>Get the <ULink
+ URL="http://nwalsh.com/docbook/dsssl/">DocBook
+ stylesheets</ULink> and install in
+ <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
+ (thereby creating a subdirectory docbook). For indexing,
+ copy or link <Filename>collateindex.pl</Filename> from the
+ DocBook stylesheets archive in <Filename>bin</Filename> into
+ a directory on your <Constant>PATH</Constant>.</para>
+
+ <para>Download the <ULink
+ URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
+ entities</ULink> into
+ <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+ </sect4>
+ </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>Remaining problems</title>
+
+ <para>If you install from source, you'll get a pile of warnings
+ of the form
+
+<Screen>DTDDECL catalog entries are not supported</Screen>
+
+ every time you build anything. These can safely be ignored, but
+ if you find them tedious you can get rid of them by removing all
+ the <Constant>DTDDECL</Constant> entries from
+ <Filename>docbook.cat</Filename>.</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>SGMLDocWays</literal> variable
+ to a list of them. For example, in
+ <filename>build.mk</filename> you might have a line:</para>
+
+<screen>
+SGMLDocWays = 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>$(SGMLDocWays)</literal>
+ to a list of formats, the <literal>install-docs</literal> target
+ won't do anything for SGML 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. There are two distinct
+ possibilities:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The hardware architecture for your system is already
+ supported by GHC, but you're running an OS that isn't
+ supported (or perhaps has been supported in the past, but
+ currently isn't). This is the easiest type of porting job,
+ but it still requires some careful bootstrapping. Proceed to
+ <xref linkend="sec-booting-from-hc">.</para>
+ </listitem>
+
+ <listitem>
+ <para>Your system's hardware architecture isn't supported by
+ GHC. This will be a more difficult port (though by comparison
+ perhaps not as difficult as porting gcc). Proceed to <xref
+ linkend="unregisterised-porting">.</para>
+ </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 a GHC compilation on a supported system to the
+ target machine, and 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 similar hardware. There may be some
+ supplied on the GHC download page, otherwise you'll have to
+ compile some up yourself, or start from
+ <emphasis>unregisterised</emphasis> HC files - see <xref
+ linkend="unregisterised-porting">.</para>
+
+ <para>The following steps should result in a working GHC build
+ with full libraries:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Unpack the HC files on top of a fresh source tree
+ (make sure the source tree version matches the version of
+ the HC files <emphasis>exactly</emphasis>!). This will
+ place matching <filename>.hc</filename> files next to the
+ corresponding Haskell source (<filename>.hs</filename> or
+ <filename>.lhs</filename>) in the compiler subdirectory
+ <filename>ghc/compiler</filename> and in the libraries
+ (subdirectories of <filename>hslibs</filename> and
+ <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>
+foo% 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>
+foo% make install
+</Screen>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="unregisterised-porting">
+ <title>Porting GHC to a new architecture</title>
+
+ <para>The first step in porting to a new architecture 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>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>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.in</filename> to recognise the new
+ architecture, and re-generate
+ <filename>configure</filename> with
+ <literal>autoreconf</literal>.</para>
+ </listitem>
+
+ <listitem>
+<screen>
+$ cd <replaceable>T</replaceable>/ghc/includes
+$ make config.h
+</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 -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
+</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> 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>/ghc/includes/config.h</filename>
+ to
+ <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+ Note that we are building on the host machine, using the
+ target machine's <literal>config.h</literal> file. This
+ is so that the intermediate C files generated here will
+ be suitable for compiling on the target system.</para>
+
+ </listitem>
+
+ <listitem>
+ <para>Touch <literal>config.h</literal>, just to make
+ sure it doesn't get replaced during the build:</para>
+<screen>
+$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
+ </listitem>
+
+ <listitem>
+ <para>Now build the compiler:</para>
+<screen>
+$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
+$ cd <replaceable>H</replaceable>/ghc && make boot && make
+</screen>
+ <para>Don't worry if the build falls over in the RTS, we
+ don't need the RTS yet.</para>
+ </listitem>
+
+ <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/libraries
+$& make boot && make
+</screen>
+ </listitem>
+
+ <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/ghc
+$ make boot stage=2 && make stage=2
+</screen>
+ </listitem>
+
+ <listitem>
+ <screen>
+$ cd <replaceable>H</replaceable>/ghc/utils
+$ make clean
+$ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
+ 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>