the parser specifications. If you don't want to alter the
parser then this saves you having to find and install
<command>happy</command>. You will still need a working
- version of GHC (preferably version 4.08+) on your machine in
+ version of GHC (version 5.x or later) on your machine in
order to compile (most of) the sources, however.</para>
</listitem>
</varlistentry>
<listitem>
<para>Set your <literal>$CVSROOT</literal> environment variable to
<literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+ <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
+ have any trailing spaces on that line, otherwise CVS will respond with
+ a perplexing message like
+ <programlisting>
+ /cvs : no such repository
+ </programlisting></para>
</listitem>
<listitem>
<para>Run the command</para>
<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>
<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> and/or <literal>Alex</literal>
+ installed, you need to check them 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>
<variablelist>
<varlistentry>
+ <term><literal>alex</literal></term>
+ <indexterm><primary><literal>alex</literal></primary>
+ <secondary>project</secondary></indexterm>
+ <listitem>
+ <para>The <ulink
+ url="http://www.haskell.org/alex/">Alex</ulink> lexical
+ analyser generator for Haskell.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>ghc</literal></term>
<indexterm><primary><literal>ghc</literal></primary>
<secondary>project</secondary></indexterm>
</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>
<term>sparc-sun-solaris2</term>
<indexterm><primary>sparc-sun-solaris2</primary></indexterm>
<listitem>
- <para>Fully supported (at least for Solaris 2.7),
+ <para>Fully supported (at least for Solaris 2.7 and 2.6),
including native-code generator.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term>sparc-unknown-openbsd</term>
+ <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
+ <listitem>
+ <para>Supported, including native-code generator. The
+ same should also be true of NetBSD</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
<indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
<listitem>
<term>ia64-unknown-linux</term>
<indexterm><primary>ia64-unknown-linux</primary></indexterm>
<listitem>
+ <para>Supported, except there is no native code
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>x86_64-unknown-linux</term>
+ <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
+ <listitem>
<para>GHC currently works unregisterised. A registerised
port is in progress.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term>mips64-sgi-irix6</term>
+ <indexterm><primary>mips-sgi-irix6</primary></indexterm>
+ <listitem>
+ <para>GHC currently works unregisterised.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>powerpc-ibm-aix</term>
<indexterm><primary>powerpc-ibm-aix</primary></indexterm>
<listitem>
<term>powerpc-apple-darwin</term>
<indexterm><primary>powerpc-apple-darwin</primary></indexterm>
<listitem>
- <para>Supported registerised. No native code
- generator.</para>
+ <para>Supported registerised. Native code generator is
+ almost working.</para>
</listitem>
</varlistentry>
<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>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
+ it and get things improved. (Exception: on x86
boxes—you may need to fiddle with GHC's
<option>-monly-N-regs</option> option; see the User's
Guide)</para>
(<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>
</varlistentry>
<varlistentry>
- <term>Autoconf</term>
- <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
- <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
+ <term>Alex</term>
+ <indexterm><primary>Alex</primary></indexterm>
+ <listitem>
+ <para>Alex is a lexical-analyser generator for Haskell,
+ which GHC uses to generate its lexer. Like Happy, Alex is
+ written in Haskell and is a project in the CVS repository.
+ Alex distributions are available from <ulink
+ url="http://www.haskell.org/alex/">Alex's Web
+ Page</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>autoconf</term>
+ <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
+ <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
<listitem>
- <para>GNU Autoconf is needed if you intend to build from the
+ <para>GNU autoconf is needed if you intend to build from the
CVS sources, it is <emphasis>not</emphasis> needed if you
just intend to build a standard source distribution.</para>
- <para>Autoconf builds the <command>configure</command>
- script from <filename>configure.in</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>
+ <para>Version 2.52 or later of the autoconf package is required.
+ NB. version 2.13 will no longer work, as of GHC version
+ 6.1.</para>
+
+ <para><command>autoreconf</command> (from the autoconf package)
+ recursively builds <command>configure</command> scripts from
+ the corresponding <filename>configure.ac</filename> and
+ <filename>aclocal.m4</filename> files. If you modify one of
+ the latter files, you'll need <command>autoreconf</command> to
+ rebuild the corresponding <filename>configure</filename>.</para>
</listitem>
</varlistentry>
<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
want a completely standard build, then the following should
work:</para>
-<screen>$ ./configure
+<screen>$ autoreconf
+$ ./configure
$ make
$ make install
</screen>
</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>
<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>
+ issue the command</para>
+<ProgramListing>
+autoreconf
+</ProgramListing>
+ <indexterm><primary>autoreconf</primary></indexterm>
+ <para>(with no arguments). This GNU program (recursively) converts
+ <filename><constant>$(FPTOOLS_TOP)</constant>/configure.ac</filename> and
+ <filename><constant>$(FPTOOLS_TOP)</constant>/aclocal.m4</filename>
to a shell script called
<filename><constant>$(FPTOOLS_TOP)</constant>/configure</filename>.
+ If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
+ then delete the latter and try again. Note that you must use <command>autoreconf</command>,
+ and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
+ a message like "No rule to make target 'mk/config.h.in'".
</para>
- <para>Some projects, including GHC, have their own
- configure script. If there's an
- <constant>$(FPTOOLS_TOP)/<project>/configure.in</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
- be short, although the resulting shell script,
- <command>configure</command>, and
- <filename>mk/config.h.in</filename>, are long.</para>
+ <para>Some projects, including GHC, have their own configure script.
+ <command>autoreconf</command> takes care of that, too, so all you have
+ to do is calling <command>autoreconf</command> in the top-level directory
+ <constant>$(FPTOOLS_TOP)</constant>.</para>
+
+ <para>These steps are completely platform-independent; they just mean
+ that the human-written files (<filename>configure.ac</filename> and
+ <filename>aclocal.m4</filename>) can be short, although the resulting
+ files (the <command>configure</command> shell scripts and the C header
+ template <filename>mk/config.h.in</filename>) are long.</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
</listitem>
</varlistentry>
</variablelist>
-
- <para><command>configure</command> caches the results of
- its run in <filename>config.cache</filename>. Quite often
- you don't want that; you're running
- <command>configure</command> a second time because
- something has changed. In that case, simply delete
- <filename>config.cache</filename>.</para>
</listitem>
</varlistentry>
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
<para>Prepare for system configuration:</para>
<programlisting>
-$ autoconf
+$ autoreconf
</programlisting>
<para>(You can skip this step if you are starting from a
source distribution, and you already have
<filename>configure</filename> and
<filename>mk/config.h.in</filename>.)</para>
-
- <para>Some projects, including GHC itself, have their own
- configure scripts, so it is necessary to run autoconf again
- in the appropriate subdirectories. eg:</para>
-
-<programlisting>
-$ (cd ghc; autoconf)
-</programlisting>
</listitem>
<listitem>
<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>
<para>Happy can similarly be run from the build tree, using
- <filename>happy/src/happy-inplace</filename>.</para>
+ <filename>happy/src/happy-inplace</filename>, and similarly for
+ Alex and Haddock.</para>
</sect2>
<sect2>
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 were hard to bootstrap
+ from C. We recommend using GHC 6.0.1 or
+ later.</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>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>
since unregisterised compilation is usually just a step on the
way to a full registerised port, we don't mind too much.</para>
- <sect3>
- <title>Building an unregisterised port</title>
+ <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>The first step is to get some unregisterised HC files.
- Either (a) download them from the GHC site (if there are
- some available for the right version of GHC), or
- (b) build them yourself on any machine with a working
- GHC. If at all possible this should be a machine with the
- same word size as the target.</para>
-
- <para>There is a script available which should automate the
- process of doing the 2-stage bootstrap necessary to get the
- unregisterised HC files - it's available in <ulink
- url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
- in CVS.</para>
-
- <para>Now take these unregisterised HC files to the target
- platform and bootstrap a compiler from them as per the
- instructions in <xref linkend="sec-booting-from-hc">. In
- <filename>build.mk</filename>, you need to tell the build
- system that the compiler you're building is
- (a) unregisterised itself, and (b) builds
- unregisterised binaries. This varies depending on the GHC
- version you're bootstraping:</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>
-<programlisting>
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
-</programlisting>
+ <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>
-# build.mk for GHC 5.xx
-GhcUnregisterised=YES
+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>
- <para>Version 5.xx only: use the option
- <option>--enable-hc-boot-unregisterised</option> instead of
- <option>--enable-hc-boot</option> when running
- <filename>./configure</filename>.</para>
-
- <para>The build may not go through cleanly. We've tried to
- stick to writing portable code in most parts of the compiler,
- 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>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>
-
- <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>
+ <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>
<para>To support GHCi, you need to port the dynamic linker
(<filename>fptools/ghc/rts/Linker.c</filename>). The linker
currently supports the ELF and PEi386 object file formats - if
- your platform uses one of these then you probably don't have
- to do anything except fiddle with the
- <literal>#ifdef</literal>s at the top of
- <filename>Linker.c</filename> to tell it about your OS.</para>
+ your platform uses one of these then things will be
+ significantly easier. The majority of Unix platforms use the
+ ELF format these days. Even so, there are some
+ machine-specific parts of the ELF linker: for example, the
+ code for resolving particular relocation types is
+ machine-specific, so some porting of this code to your
+ architecture will probaly be necessary.</para>
<para>If your system uses a different object file format, then
you have to write a linker — good luck!</para>
</para>
-<sect2><Title>Cygwin and MinGW</Title>
+<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>
</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>
<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 all of the following:
+<itemizedlist>
+<listitem><para>
+ <command>cvs</command>,
+</para></listitem>
+<listitem><para>
+ <command>openssh</command>,
+</para></listitem>
+<listitem><para>
+ <command>autoconf</command>,
+</para></listitem>
+<listitem><para>
+ <command>binutils</command> (includes ld and (I think) ar),
+</para></listitem>
+<listitem><para>
+ <command>gcc</command>,
+</para></listitem>
+<listitem><para>
+ <command>flex</command>,
+</para></listitem>
+<listitem><para>
+ <command>make</command>.
+</para></listitem>
+</itemizedlist>
+If you miss out any of these, strange things will happen to you. To see thse packages,
+click on the "View" button in the "Select Packages"
+stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
+"Category" isn't very helpful, and the "View" button is rather unobtrousive.
</para>
<para> Now set the following user environment variables:
<itemizedlist>
</listitem>
<listitem><para> Set <constant>SHELL</constant> to
-<Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
+<Filename>c:/cygwin/bin/bash</Filename>. When you invoke a shell in Emacs, this
<constant>SHELL</constant> is what you get.
</para></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' (to do with quoting
-and length of command lines), 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:
</para>
</listitem>
+ <listitem>
+ <para>Install Alex. This can be done by building from the
+ source distribution in the usual way. Sources are
+ available from <ulink
+ url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
+ </listitem>
<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>
<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>
+
+
+<listitem>
<para> Finally, check out a copy of GHC sources from
the CVS repository, following the instructions above (<xref linkend="cvs-access">).
</para>
<ItemizedList>
<listitem>
<para>
-Run <Command>autoconf</Command> both in <filename>fptools</filename>
-and in <filename>fptools/ghc</filename>. If you omit the latter step you'll
-get an error when you run <filename>./configure</filename>:
+If you used <Command>autoconf</Command> instead of <Command>autoreconf</Command>,
+you'll get an error when you run <filename>./configure</filename>:
<Screen>
...lots of stuff...
creating mk/config.h
</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),
+<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
+read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
you get
<screen>
/usr/bin/autoconf: cannot create configure: permission denied
<listitem>
<para>
- After <command>autoconf</command> run <command>./configure</command> in
+ After <command>autoreconf</command> run <command>./configure</command> in
<filename>fptools/</filename> thus:
<Screen>
(see <xref linkend="ghc-mingw">). </para>
<para> Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
-Furthermore, it's very important 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
+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 does not come with
-a helpful error message, unfortunately.)
+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>
</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>
+
<listitem><para> Do not attempt to build the documentation.
It needs all kinds of wierd Jade stuff that we haven't worked out for
Win32.</para></listitem>
projects / ghc-hetmet.git / blobdiff