<para>
- [Windows users.] 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>
+ <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+ </para>
+
- <para>[Windows users.] 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>
the <literal>fpconfig</literal> bit.</para>
<screen>
$ cd <replaceable>directory</replaceable>
- $ cvs checkout ghc hslibs
+ $ cvs checkout ghc hslibs libraries
</screen>
<para>The second command here checks out the relevant
modules you want to work on. For a GHC build, for instance,
- you need at least the <literal>ghc</literal> and
- <literal>hslibs</literal> modules (for a full list of the
- projects available, see <xref linkend="projects">).</para>
+ you need at least the <literal>ghc</literal>,
+ <literal>hslibs</literal> and <literal>libraries</literal>
+ modules (for a full list of the projects available, see
+ <xref linkend="projects">).</para>
+
+ <para>Remember that if you do not have
+ <literal>happy</literal> installed, you need to check it out
+ as well.</para>
</listitem>
</itemizedlist>
</sect2>
you the results.</para>
</listitem>
- <listitem>
+ <listitem>
+ <para>If you changed something in the
+ <literal>fptools/libraries</literal> subdirectories, also run
+ <literal>make html</literal> to check if the documentation can
+ be generated successfully, too.</para>
+ </listitem>
+
+ <listitem>
<para>Before checking in a change, you need to update your
source tree:</para>
major cause of headaches. </para>
<para>So, to avoid a lot of hassle, follow this recipe for
- updating your tree: </para>
+ updating your tree:</para>
<screen>
$ cd fptools
-$ cvs update -Pd 2>&1 | tee log</screen>
+$ cvs update -P 2>&1 | tee log</screen>
<para>Look at the log file, and fix any conflicts (denoted by a
- <quote>C</quote> in the first column). If you're using multiple
- build trees, then for every build tree you have pointing at this
- source tree, you need to update the links in case any new files
- have appeared: </para>
+ <quote>C</quote> in the first column). New directories may have
+ appeared in the repository; CVS doesn't check these out by
+ default, so to get new directories you have to explicitly do
+<screen>
+$ cvs update -d</screen>
+ in each project subdirectory. Don't do this at the top level,
+ because then <emphasis>all</emphasis> the projects will be
+ checked out.</para>
+
+ <para>If you're using multiple build trees, then for every build
+ tree you have pointing at this source tree, you need to update
+ the links in case any new files have appeared: </para>
<screen>
$ cd <replaceable>build-tree</replaceable>
</varlistentry>
<varlistentry>
- <term><literal>green-card</literal></term>
- <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
+ <term><literal>greencard</literal></term>
+ <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
<listitem>
<para>The <ulink
- url="http://www.haskell.org/greencard/">Green Card</ulink>
+ url="http://www.haskell.org/greencard/">GreenCard</ulink>
system for generating Haskell foreign function
interfaces.</para>
</listitem>
<variablelist>
<varlistentry>
+ <term>GHC</term>
+ <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+ <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+ <listitem>
+ <para>GHC is required to build many of the tools, including
+ GHC itself. If you need to port GHC to your platform
+ because there isn't a binary distribution of GHC available,
+ then see <xref linkend="sec-porting-ghc">.</para>
+
+ <para>Which version of GHC you need will depend on the
+ packages you intend to build. GHC itself will normally
+ build using one of several older versions of itself - check
+ the announcement or release notes for details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>Perl</term>
<indexterm><primary>pre-supposed: Perl</primary></indexterm>
<indexterm><primary>Perl, pre-supposed</primary></indexterm>
<command>egcs</command>) have varying degrees of stability
depending on the platform.</para>
+ <para>GCC 3.2 is currently known to have problems building
+ GHC on Sparc, but is stable on x86.</para>
+
+ <para>GCC 3.3 currently cannot be used to build GHC, due to
+ some problems with the new C preprocessor.</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 iX86
(<literal>fptools/happy</literal>). It can be built from
source, but bear in mind that you'll need GHC installed in
order to build it. To avoid the chicken/egg problem,
- install a binary distribtion of either Happy or GHC to get
+ install a binary distribution of either Happy or GHC to get
started. Happy distributions are available from <ulink
url="http://www.haskell.org/happy/">Happy's Web
Page</ulink>.</para>
CVS 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 autoconf is required.
+ NB. vesrion 2.13 will no longer work, as of GHC version
+ 6.1.</para>
+
<para>Autoconf builds the <command>configure</command>
- script from <filename>configure.in</filename> and
+ script from <filename>configure.ac</filename> and
<filename>aclocal.m4</filename>. If you modify either of
these files, you'll need <command>autoconf</command> to
rebuild <filename>configure</filename>.</para>
<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. Concurent Haskell, which
+ 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
</variablelist>
</sect2>
- <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>All our documentation is written in SGML, using the
- DocBook DTD. Instructions on installing and configuring
- the DocBook tools are in the installation guide (in the
- GHC user guide).</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>
- </variablelist>
-
- <para> In order to actually build any documentation, you need to
- set <constant>SGMLDocWays</constant> in your
- <filename>build.mk</filename>. Valid values to add to this list
- are: <literal>dvi</literal>, <literal>ps</literal>,
- <literal>pdf</literal>, <literal>html</literal>, and
- <literal>rtf</literal>.</para>
- </sect2>
-
<sect2 id="pre-supposed-other-tools">
<title>Other useful tools</title>
</listitem>
</varlistentry>
</variablelist>
+
+ <para>More tools are required if you want to format the documentation
+ that comes with GHC and other fptools projects. See <xref
+ linkend="building-docs">.</para>
</sect2>
</sect1>
software, and lay hands on them gently when they don't
work.</para>
+ <sect2 id="quick-start">
+ <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>
+
+<screen>$ ./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.</para>
+
+ <para>If you want to do anything at all non-standard, or you
+ want to do some development, read on...</para>
+ </sect2>
+
<sect2 id="sec-source-tree">
<title>Your source tree</title>
</listitem>
<listitem>
- <para><filename>configure.in</filename>,
+ <para><filename>configure.ac</filename>,
<filename>config.sub</filename>,
<filename>config.guess</filename>: these files support the
configuration process.</para>
only one project (<literal>happy</literal>, say), you must have
a source tree whose root directory contains
<filename>Makefile</filename>, <filename>mk/</filename>,
- <filename>configure.in</filename>, and the project(s) you want
+ <filename>configure.ac</filename>, and the project(s) you want
(<filename>happy/</filename> in this case). You cannot get by
with just the <filename>happy/</filename> directory.</para>
</sect2>
<varlistentry>
<term>Step 1: get ready for configuration.</term>
<listitem>
+ <para>NOTE: if you're starting from a source distribution,
+ rather than CVS sources, you can skip this step.</para>
+
<para>Change directory to
<constant>$(FPTOOLS_TOP)</constant> and
issue the command
<command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
(with no arguments). This GNU program converts
- <filename><constant>$(FPTOOLS_TOP)</constant>/configure.in</filename>
+ <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename>
to a shell script called
<filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
</para>
<para>Some projects, including GHC, have their own
configure script. If there's an
- <constant>$(FPTOOLS_TOP)/<project>/configure.in</constant>,
+ <constant>$(FPTOOLS_TOP)/<project>/configure.ac</constant>,
then you need to run <command>autoconf</command> in that
directory too.</para>
<para>Both these steps are completely
platform-independent; they just mean that the
- human-written file (<filename>configure.in</filename>) can
+ human-written file (<filename>configure.ac</filename>) can
be short, although the resulting shell script,
<command>configure</command>, and
<filename>mk/config.h.in</filename>, are long.</para>
-
- <para>In case you don't have <command>autoconf</command>
- we distribute the results, <command>configure</command>,
- and <filename>mk/config.h.in</filename>, with the source
- distribution. They aren't kept in the repository,
- though.</para>
</listitem>
</varlistentry>
round your computer working out what architecture it has,
what operating system, whether it has the
<Function>vfork</Function> system call, where
- <command>yacc</command> is kept, whether
+ <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
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>
For example, there's a line that says:</para>
<ProgramListing>
-YACC = @YaccCmd@
+TAR = @TarCmd@
</ProgramListing>
- <para>This defines the Make variables <constant>YACC</constant>
- to the pathname for a <command>yacc</command> that
+ <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>yacc</command> you want to use instead, that's
+ 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>
-YACC = myyacc
+TAR = mytar
</ProgramListing>
<para>You do not <emphasis>have</emphasis> to have a
the top of your <literal>fptools</literal> tree and type
<command>gmake</command>. This will prepare the tree and build
the various projects in the correct order.</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 fptools <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. When building
+ GHC, the top-level fptools <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>
+ </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>ghc/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>ghc/compiler</literal>.</para>
</sect2>
<sect2 id="sec-standard-targets">
<para> Do <emphasis>NOT</emphasis> use
<filename>ghc/compiler/ghc</filename>, or
- <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
+ <filename>ghc/compiler/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>
</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>
target machine, and compiling them using gcc to get a working
GHC.</para>
- <para><emphasis>NOTE: GHC version 5.xx is significantly harder
- to bootstrap from C than previous versions. We recommend
- starting from version 4.08.2 if you need to bootstrap in this
- way.</emphasis></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
corresponding Haskell source (<filename>.hs</filename> or
<filename>.lhs</filename>) in the compiler subdirectory
<filename>ghc/compiler</filename> and in the libraries
- (<filename>ghc/lib</filename>, and subdirectories of
- <filename>hslibs</filename>).</para>
+ (subdirectories of <filename>hslibs</filename> and
+ <literal>libraries</literal>).</para>
</listitem>
<listitem>
</programlisting>
<programlisting>
-# build.mk for GHC 5.xx
+# build.mk for GHC 5.xx and 6.x
GhcUnregisterised=YES
</programlisting>
- <para>Version 5.xx only: use the option
+ <para>Versions 5.xx and 6.x only: use the option
<option>--enable-hc-boot-unregisterised</option> instead of
<option>--enable-hc-boot</option> when running
<filename>./configure</filename>.</para>
</para>
+<sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
+
+<para> The Windows situation for building GHC is rather confusing. This section
+tries to clarify, and to establish terminology.</para>
+
+<sect3 id="ghc-mingw"><title>GHC-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 GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
+<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
+GHC compiles Haskell to C (or to
+assembly code), and then invokes these MinGW tools to generate an executable binary.
+The resulting binaries can run on any Win32 system.
+</para>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+
+<para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
+Posix interface. So programs compiled with GHC-mingw cannot import the (Haskell) Posix
+library; they have to do
+their input output using standard Haskell I/O libraries, or native Win32 bindings.
+</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
+
+<para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.
+<ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
+Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
+<command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
+A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
+</para>
+<para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries? Because
+Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
+A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed.
+If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
+that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
+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. So programs compiled by GHC might only run with
+particular versions of Cygwin. All of this seems very undesirable.
+</para>
+<para>
+Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
+we will call that <emphasis>GHC-cygwin</emphasis>. The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+</para>
+</sect3>
+
+<sect3><title>HOST_OS vs TARGET_OS</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>
+
+<sect3><title>Summary</title>
+
+<para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW". It says nothing about
+how that GHC was <emphasis>built</emphasis>. It is entirely possible to have a GHC-mingw that was built
+by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
+
+<para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
+GHC-cygwin too is beyond our resources. The GHC we distribute
+therefore does not require Cygwin to run, nor do the programs it
+compiles require Cygwin.</para>
+
+<para>The instructions that follow describe how to build GHC-mingw. It is
+possible to build GHC-cygwin, but it's not a supported route, and the build system might
+be flaky.</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 right <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>
+</sect2>
+
<Sect2><Title>Installing and configuring Cygwin</Title>
-<para>You don't need Cygwin to <emphasis>use</emphasis> GHC, but you do need it to <emphasis>build</emphasis> GHC.</para>
+<para>You don't need Cygwin to <emphasis>use</emphasis> GHC,
+but you do need it to <emphasis>build</emphasis> GHC.</para>
<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>.
-Both <command>cvs</command> and <command>ssh</command>
-come with Cygwin, but you'll need them, so make sure you select them when running
-the Cygwin installer.
+During the installation dialogue, make sure that you select:
+<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>.
</para>
<para> Now set the following user environment variables:
<itemizedlist>
-<listitem><para> Add <filename>c:/cygwin/bin</filename> to your
+<listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
<constant>PATH</constant></para></listitem>
<listitem>
<itemizedlist>
<listitem>
<para>
+By default, cygwin provides the command shell <filename>ash</filename>
+as <filename>sh.exe</filename>. We have often seen build-system problems that
+turn 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.
+So, 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>
+
+<listitem>
+<para>
Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
-(and similarly for <Command>bash</Command>). Notice the hardwired path!
+(and similarly for <Command>sh</Command>). Notice the hardwired path!
So you need to ensure that your <Filename>/bin</Filename> directory has the following
binaries in it:
<itemizedlist>
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>).
+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.
-</para>
-</listitem>
-
-<listitem>
-<para>
-By default, cygwin provides the command shell <filename>ash</filename>
-as <filename>sh.exe</filename>. It has a couple of 'issues', so
-in your <filename>/bin</filename> directory, make sure that <filename>
-bash.exe</filename> is also provided as <filename>sh.exe</filename>
-(i.e. overwrite the old <filename>sh.exe</filename> with a copy of
-<filename>bash.exe</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>
</itemizedlist>
</Sect2>
+<Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
+
+<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
+you install Cygwin. (If not, the installer lets you update easily.) Look for <command>openssh</command>
+(not ssh) in the Cygwin list of applications!</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>
+<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
+<programlisting>
+ ssh -v cvs.haskell.org
+</programlisting>
+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:
<listitem>
<para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that. Just pick up a mingw bundle at
+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>Do <emphasis>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.
+</para>
+</listitem>
+
+
+<listitem>
+<para>We use <command>emacs</command> a lot, so we install that too.
+When you are in <filename>fptools/ghc/compiler</filename>, you can use
+"<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
+<filename>fptools/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>fptools/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>
</para>
</listitem>
+<listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
+read-only. So if you need to run autoconf 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>
You either need to add <filename>ghc</filename> to your
</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>
After <command>autoconf</command> run <command>./configure</command> in
<filename>fptools/</filename> thus:
<Screen>
- ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
+ ./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>
-Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
+<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:
+<programlisting>
+make[4]: Leaving directory `/cygdrive/e/fptools-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/fptools-stage1/ghc'
+make: *** [all] Error 1
+</programlisting>
+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> 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>
projects / ghc-hetmet.git / blobdiff