<title>Quick Start</title>
<para>If you are starting from a source distribution, and just
- want a completely standard build, then the following should
- work:</para>
+ want a completely standard build, then the following procedure should
+ work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
<screen>$ autoreconf
$ ./configure
</varlistentry>
<varlistentry>
- <term><literal>EXCLUDE_SRCS</literal>
- <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+ <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
<varlistentry>
<term><literal>EXTRA_SRCS</literal>
- <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+ <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
</term>
<listitem>
<para>Set to a list of extra source files (perhaps
<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'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 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>
+ 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>
<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>
+ <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>
-
- <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>
</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
<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>
+ 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 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>
+ that were generated on <emphasis>the same platform</emphasis>. There
+ may be some supplied on the GHC download page, otherwise you'll have to
+ compile some up yourself, or start from
+ <emphasis>unregisterised</emphasis> HC files - see <xref
+ linkend="unregisterised-porting"/>.</para>
<para>The following steps should result in a working GHC build
with full libraries:</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
<listitem>
<screen>$ cd <replaceable>T</replaceable>/ghc/includes
-$ make config.h</screen>
+$ make ghcconfig.h</screen>
</listitem>
</itemizedlist>
</listitem>
with the following contents:</para>
<programlisting>GhcUnregisterised = YES
-GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibHcOpts = -O -fvia-C -keep-hc-files
+GhcRtsHcOpts = -keep-hc-files
GhcLibWays =
SplitObjs = NO
GhcWithNativeCodeGen = NO
GhcWithInterpreter = NO
-GhcStage1HcOpts = -O -H32m -fasm
-GhcStage2HcOpts = -O -fvia-C -keep-hc-files</programlisting>
+GhcStage1HcOpts = -O -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
+SRC_HC_OPTS += -H32m
+GhcBootLibs = YES</programlisting>
</listitem>
<listitem>
<listitem>
<para>Copy
- <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
+ <filename><replaceable>T</replaceable>/ghc/includes/ghcconfig.h</filename>
to
<filename><replaceable>H</replaceable>/ghc/includes</filename>.
Note that we are building on the host machine, using the
</listitem>
<listitem>
- <para>Touch <literal>config.h</literal>, just to make
+ <para>Touch <literal>ghcconfig.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>
+<screen>$ touch <replaceable>H</replaceable>/ghc/includes/ghcconfig.h</screen>
</listitem>
<listitem>
</listitem>
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc
+<screen>$ cd <replaceable>H</replaceable>/ghc/compiler
$ make boot stage=2 && make stage=2</screen>
</listitem>
-
+
<listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/utils
+<screen>$ cd <replaceable>H</replaceable>/ghc/lib
+$ make clean
+$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+$ 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>
+$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
</listitem>
<listitem>
</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>
<listitem><para>
Set the following environment variables
<itemizedlist>
- <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path. (Of course, the version number may differ.)
+ <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>).
</listitem>
<listitem>
- <para>Install Alex. This can be done by building from the
+ <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>
<ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
We install it in <filename>c:/mingw</filename>.
</para>
-<para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
+
+<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.
projects / ghc-hetmet.git / blobdiff