+ <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>
+
+ <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 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>