+ 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 and later are
+ significantly harder to bootstrap from C than earlier versions.
+ We recommend starting from version 4.08.2 if you need to
+ bootstrap in this way.</emphasis></para>
+
+ <para>HC files are architecture-dependent (but not
+ OS-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>