diff options
| -rw-r--r-- | ANNOUNCE | 2 | ||||
| -rw-r--r-- | README | 2 | ||||
| -rw-r--r-- | docs/Makefile | 2 | ||||
| -rw-r--r-- | docs/building/Makefile | 7 | ||||
| -rw-r--r-- | docs/building/building.xml | 3859 | ||||
| -rw-r--r-- | docs/index.html | 14 | ||||
| -rw-r--r-- | docs/users_guide/installing.xml | 4 | ||||
| -rw-r--r-- | ghc.spec.in | 3 |
8 files changed, 15 insertions, 3878 deletions
@@ -89,7 +89,7 @@ difficulty. The builder's guide on the web site gives a complete run-down of what ports work and how to go about porting to a new platform; it can be found at - http://www.haskell.org/ghc/docs/latest/html/building/ + http://hackage.haskell.org/trac/ghc/wiki/Building Mailing lists @@ -98,7 +98,7 @@ References [1] http://www.haskell.org/ghc/ GHC Home Page [2] http://hackage.haskell.org/trac/ghc GHC Developer's Wiki - [3] http://www.haskell.org/ghc/docs/latest/html/building/index.html + [3] http://hackage.haskell.org/trac/ghc/wiki/Building Building Guide [4] http://www.haskell.org/happy/ Happy diff --git a/docs/Makefile b/docs/Makefile index 99b6d68e3b..ca9d52d17b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,7 @@ TOP = .. include $(TOP)/mk/boilerplate.mk -SUBDIRS = man building docbook-cheat-sheet ext-core storage-mgt users_guide +SUBDIRS = man docbook-cheat-sheet ext-core storage-mgt users_guide PAGES = index.html diff --git a/docs/building/Makefile b/docs/building/Makefile deleted file mode 100644 index fb9cce6ff5..0000000000 --- a/docs/building/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -TOP = ../.. -include $(TOP)/mk/boilerplate.mk - -XML_DOC = building -INSTALL_XML_DOC = building - -include $(TOP)/mk/target.mk diff --git a/docs/building/building.xml b/docs/building/building.xml deleted file mode 100644 index 6b8efa752b..0000000000 --- a/docs/building/building.xml +++ /dev/null @@ -1,3859 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - <!ENTITY hacking SYSTEM "../../HACKING"> -]> - -<article id="building-guide"> - -<articleinfo> - -<title>Building and developing GHC</title> -<author><othername>The GHC Team</othername></author> -<address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address> - - <abstract> - <para>This Guide is primarily aimed at those who want to build and/or - hack on GHC. It describes how to get started with building GHC on your - machine, and how to tweak the settings to get the kind of build you - want. It also describes the inner workings of the build system, so you - can extend it, modify it, and use it to build your code.</para> - - <para>The bulk of this guide applies to building on Unix - systems; see <xref linkend="winbuild"/> for Windows notes.</para> - </abstract> - -</articleinfo> - - - <sect1 id="sec-getting"> - <title>Getting the sources</title> - - <para>You can get your hands on the GHC sources in two ways:</para> - - <variablelist> - - <varlistentry> - <term><indexterm><primary>Source - distributions</primary></indexterm>Source distributions</term> - <listitem> - <para>You have a supported platform, but (a) you like - the warm fuzzy feeling of compiling things yourself; - (b) you want to build something ``extra”—e.g., a - set of libraries with strictness-analysis turned off; or - (c) you want to hack on GHC yourself.</para> - - <para>A source distribution contains complete sources for - GHC. Not only that, but the more awkward - machine-independent steps are done for you. For example, if - you don't have - <command>happy</command><indexterm><primary>happy</primary></indexterm> - you'll find it convenient that the source distribution - contains the result of running <command>happy</command> on - 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 (version 5.x or later) on your machine in - order to compile (most of) the sources, however.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The darcs repository.<indexterm><primary>darcs repository</primary></indexterm></term> - <listitem> - <para>We make releases infrequently. If you want more - up-to-the minute (but less tested) source code then you need - to get access to our darcs repository.</para> - - <para>Information on accessing the darcs repository is on - the wiki: <ulink - url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" - />.</para> - - <para>The repository holds source code only. It holds no - mechanically generated files at all. So if you check out a - source tree from darcs you will need to install every utility - so that you can build all the derived files from - scratch.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="sec-build-checks"> - <title>Things to check before you start</title> - - <para>Here's a list of things to check before you get - started.</para> - - <orderedlist> - - <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk - space needed: from about 100Mb for a basic GHC - build, up to probably 500Mb for a GHC build with everything - included (libraries built several different ways, - etc.).</para> - </listitem> - - <listitem> - <para>Use an appropriate machine / operating system. <ulink - url="http://hackage.haskell.org/trac/ghc/wiki/Platforms">GHC - Platform Support</ulink> lists the currently supported - platforms; if yours isn't amongst these then you can try - porting GHC (see <xref linkend="sec-porting-ghc"/>).</para> - </listitem> - - <listitem> - <para>Be sure that the “pre-supposed” utilities are - installed. <xref linkend="sec-pre-supposed"/> - elaborates.</para> - </listitem> - - <listitem> - <para>If you have any problem when building or installing the - Glasgow tools, please check the “known pitfalls” (<xref - linkend="sec-build-pitfalls"/>). Also check the FAQ for the - version you're building, which is part of the User's Guide and - available on the <ulink url="http://www.haskell.org/ghc/" >GHC web - site</ulink>.</para> - - <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm> - - <para>If you feel there is still some shortcoming in our - procedure or instructions, please report it.</para> - - <para>For GHC, please see the <ulink - url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting - section of the GHC Users' Guide</ulink>, to maximise the - usefulness of your report.</para> - - <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm> - <para>If in doubt, please send a message to - <email>glasgow-haskell-bugs@haskell.org</email>. - <indexterm><primary>bugs</primary><secondary>mailing - list</secondary></indexterm></para> - </listitem> - </orderedlist> - </sect1> - - <sect1 id="sec-pre-supposed"> - <title>Installing pre-supposed utilities</title> - - <indexterm><primary>pre-supposed utilities</primary></indexterm> - <indexterm><primary>utilities, pre-supposed</primary></indexterm> - - <para>Here are the gory details about some utility programs you - may need; <command>perl</command>, <command>gcc</command> and - <command>happy</command> are the only important - ones. (PVM<indexterm><primary>PVM</primary></indexterm> is - important if you're going for Parallel Haskell.) The - <command>configure</command><indexterm><primary>configure</primary></indexterm> - script will tell you if you are missing something.</para> - - <variablelist> - - <varlistentry> - <term>GHC - <indexterm><primary>pre-supposed: GHC</primary></indexterm> - <indexterm><primary>GHC, pre-supposed</primary></indexterm> - </term> - <listitem> - <para>GHC is required to build GHC, because GHC itself is - written in Haskell, and uses GHC extensions. It is possible - to build GHC using just a C compiler, and indeed some - distributions of GHC do just that, but it isn't the best - supported method, and you may encounter difficulties. Full - instructions are in <xref linkend="sec-porting-ghc"/>.</para> - - <para>GHC can be built using either an earlier released - version of GHC (currently 5.04 and later are supported), or - bootstrapped using a GHC built from exactly the same - sources. Note that this means you cannot in general build - GHC using an arbitrary development snapshot, or a build from - say last week. It might work, it might not - we don't - guarantee anything. To be on the safe side, start your - build using the most recently released stable version of - GHC.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Perl - <indexterm><primary>pre-supposed: Perl</primary></indexterm> - <indexterm><primary>Perl, pre-supposed</primary></indexterm> - </term> - <listitem> - <para><emphasis>You have to have Perl to proceed!</emphasis> - Perl version 5 at least is required. GHC has been known to - tickle bugs in Perl, so if you find that Perl crashes when - running GHC try updating (or downgrading) your Perl - installation. Versions of Perl before 5.6 have been known to have - various bugs tickled by GHC, so the configure script - will look for version 5.6 or later.</para> - - <para>For Win32 platforms, you should use the binary - supplied in the InstallShield (copy it to - <filename>/bin</filename>). The Cygwin-supplied Perl seems - not to work.</para> - - <para>Perl should be put somewhere so that it can be invoked - by the <literal>#!</literal> script-invoking - mechanism. The full pathname may need to be less than 32 - characters long on some systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>GNU C (<command>gcc</command>) - <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm> - <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm> - </term> - <listitem> - <para>Most GCC versions should work with the most recent GHC - sources. Expect trouble if you use a recent GCC with - an older GHC, though (trouble in the form of mis-compiled code, - link errors, and errors from the <literal>ghc-asm</literal> - script).</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 x86 - boxes—you may need to fiddle with GHC's - <option>-monly-N-regs</option> option; see the User's - Guide)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>GNU Make - <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm> - </term> - <listitem> - <para>The GHC build system makes heavy use of features - specific to GNU <command>make</command>, so you must have - this installed in order to build GHC.</para> - - <para>NB. it has been reported that version 3.79 no longer - works to build GHC, and 3.80 is required.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.haskell.org/happy">Happy</ulink> - <indexterm><primary>Happy</primary></indexterm> - </term> - <listitem> - <para>Happy is a parser generator tool for Haskell, and is - used to generate GHC's parsers.</para> - - <para>If you start from a source tarball of GHC (i.e. not a darcs - checkout), then you don't need Happy, because we supply the - pre-processed versions of the Happy parsers. If you intend to - modify the compiler and/or you're using a darcs checkout, then you - need Happy.</para> - - <para>Happy version 1.15 is currently required to build GHC. - Grab a copy from <ulink - url="http://www.haskell.org/happy/">Happy's Web - Page</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Alex - <indexterm><primary>Alex</primary></indexterm> - </term> - <listitem> - <para>Alex is a lexical-analyser generator for Haskell, - which GHC uses to generate its lexer.</para> - - <para>Like Happy, you don't need Alex if you're building GHC from a - source tarball, but you do need it if you're modifying GHC and/or - building a darcs checkout.</para> - - <para>Alex is - written in Haskell and is a project in the darcs repository. - Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web - Page</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>autoconf - <indexterm><primary>pre-supposed: autoconf</primary></indexterm> - <indexterm><primary>autoconf, pre-supposed</primary></indexterm> - </term> - <listitem> - <para>GNU autoconf is needed if you intend to build from the - darcs 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 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> - - <varlistentry> - <term><command>sed</command> - <indexterm><primary>pre-supposed: sed</primary></indexterm> - <indexterm><primary>sed, pre-supposed</primary></indexterm> - </term> - <listitem> - <para>You need a working <command>sed</command> if you are - going to build from sources. The build-configuration stuff - needs it. GNU sed version 2.0.4 is no good! It has a bug - in it that is tickled by the build-configuration. 2.0.5 is - OK. Others are probably OK too (assuming we don't create too - elaborate configure scripts.)</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2 id="pre-supposed-gph-tools"> - <title>Tools for building parallel GHC (GPH)</title> - - <variablelist> - <varlistentry> - <term>PVM version 3: - <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm> - <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm> - </term> - <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. 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 - (faster).</para> - - <para>The current version of PVM is 3.3.11; we use 3.3.7. - It is readily available on the net; I think I got it from - <literal>research.att.com</literal>, in - <filename>netlib</filename>.</para> - - <para>A PVM installation is slightly quirky, but easy to - do. Just follow the <filename>Readme</filename> - instructions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>bash</command>: - <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm> - </term> - <listitem> - <para>Sadly, the <command>gr2ps</command> script, used to - convert “parallelism profiles” to PostScript, - is written in Bash (GNU's Bourne Again shell). This bug - will be fixed (someday).</para> - </listitem> - </varlistentry> - </variablelist> - - <para>More tools are required if you want to format the - documentation that comes with GHC. See <xref - linkend="building-docs"/>.</para> - </sect2> - </sect1> - - <sect1 id="sec-building-from-source"> - <title>Building from source</title> - - <indexterm><primary>Building from source</primary></indexterm> - <indexterm><primary>Source, building from</primary></indexterm> - - <para>“I just want to build it!”</para> - - <para>No problem. This recipe should build and install a working GHC with - all the default settings. (unless you're - on Windows, in which case go to <xref linkend="winbuild" />).</para> - -<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para> - </footnote> -$ ./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 in the default location (under <filename>/usr/local</filename> on - Unix, for example).</para> - - <para>The <literal>configure</literal> script is a standard GNU - <literal>autoconf</literal> script, and accepts the usual options for - changing install locations and the like. Run - <literal>./configure --help</literal> for a list of options.</para> - - <para>If you want to do anything at all non-standard, or you - want to do some development, read on...</para> - </sect1> - - <sect1 id="quick-start"> - <title>Quick start for GHC developers</title> - - <para>This section is a copy of the file - <literal>HACKING</literal> from the GHC source tree. It describes - how to get started with setting up your build tree for developing GHC - or its libraries, and how to start building.</para> - -<screen> -&hacking; - </screen> - </sect1> - - <sect1 id="sec-working-with-the-build-system"> - <title>Working with the build system</title> - - <para>This rest of this guide is intended for duffers like me, who - aren't really interested in Makefiles and systems configurations, - but who need a mental model of the interlocking pieces so that - they can make them work, extend them consistently when adding new - software, and lay hands on them gently when they don't - work.</para> - - <sect2> - <title>History</title> - - <para>First, a historical note. The GHC build system used to be - called "fptools": a generic build system used to build multiple - projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a - concept of the generic project-independent parts, and - project-specific parts that resided in a project - subdirectory.</para> - - <para>Nowadays, most of these other projects are using <ulink - url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded - away, and GHC is the only regular user of the fptools build - system. We decided therefore to simplify the situation for - developers, and specialise the build system for GHC. This - resulted in a simpler organisation of the source tree and the - build system, which hopefully makes the whole thing easier to - understand.</para> - - <para>You might find old comments that refer to "projects" or - "fptools" in the documentation and/or source; please let us know - if you do.</para> - </sect2> - - <sect2> - <title>Build trees</title> - <indexterm><primary>build trees</primary></indexterm> - <indexterm><primary>link trees, for building</primary></indexterm> - - <para>If you just want to build the software once on a single - platform, then your source tree can also be your build tree, and - you can skip the rest of this section.</para> - - <para>We often want to build multiple versions of our software - for different architectures, or with different options - (e.g. profiling). It's very desirable to share a single copy of - the source code among all these builds.</para> - - <para>So for every source tree we have zero or more - <emphasis>build trees</emphasis>. Each build tree is initially - an exact copy of the source tree, except that each file is a - symbolic link to the source file, rather than being a copy of - the source file. There are “standard” Unix - utilities that make such copies, so standard that they go by - different names: - <command>lndir</command><indexterm><primary>lndir</primary></indexterm>, - <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm> - are two (If you don't have either, the source distribution - includes sources for the X11 - <command>lndir</command>—check out - <filename>utils/lndir</filename>). See <xref - linkend="sec-storysofar"/> for a typical invocation.</para> - - <para>The build tree does not need to be anywhere near the - source tree in the file system. Indeed, one advantage of - separating the build tree from the source is that the build tree - can be placed in a non-backed-up partition, saving your systems - support people from backing up untold megabytes of - easily-regenerated, and rapidly-changing, gubbins. The golden - rule is that (with a single exception—<xref - linkend="sec-build-config"/>) <emphasis>absolutely everything in - the build tree is either a symbolic link to the source tree, or - else is mechanically generated</emphasis>. It should be - perfectly OK for your build tree to vanish overnight; an hour or - two compiling and you're on the road again.</para> - - <para>You need to be a bit careful, though, that any new files - you create (if you do any development work) are in the source - tree, not a build tree!</para> - - <para>Remember, that the source files in the build tree are - <emphasis>symbolic links</emphasis> to the files in the source - tree. (The build tree soon accumulates lots of built files like - <filename>Foo.o</filename>, as well.) You can - <emphasis>delete</emphasis> a source file from the build tree - without affecting the source tree (though it's an odd thing to - do). On the other hand, if you <emphasis>edit</emphasis> a - source file from the build tree, you'll edit the source-tree - file directly. (You can set up Emacs so that if you edit a - source file from the build tree, Emacs will silently create an - edited copy of the source file in the build tree, leaving the - source file unchanged; but the danger is that you think you've - edited the source file whereas actually all you've done is edit - the build-tree copy. More commonly you do want to edit the - source file.)</para> - - <para>Like the source tree, the top level of your build tree - must be (a linked copy of) the root directory of the GHC source - tree.. Inside Makefiles, the root of your build tree is called - <constant>$(GHC_TOP)</constant><indexterm><primary>GHC_TOP</primary></indexterm>. - In the rest of this document path names are relative to - <constant>$(GHC_TOP)</constant> unless - otherwise stated. For example, the file - <filename>mk/target.mk</filename> is actually - <filename>$(GHC_TOP)/mk/target.mk</filename>.</para> - </sect2> - - <sect2 id="sec-build-config"> - <title>Getting the build you want</title> - - <para>When you build GHC you will be compiling code on a - particular <emphasis>host platform</emphasis>, to run on a - particular <emphasis>target platform</emphasis> (usually the - same as the host - platform)<indexterm><primary>platform</primary></indexterm>. - The difficulty is that there are minor differences between - different platforms; minor, but enough that the code needs to be - a bit different for each. There are some big differences too: - for a different architecture we need to build GHC with a - different native-code generator.</para> - - <para>There are also knobs you can turn to control how the - software is built. For example, you might want to build GHC - optimised (so that it runs fast) or unoptimised (so that you can - compile it fast after you've modified it. Or, you might want to - compile it with debugging on (so that extra consistency-checking - code gets included) or off. And so on.</para> - - <para>All of this stuff is called the - <emphasis>configuration</emphasis> of your build. You set the - configuration using a three-step process.</para> - - <variablelist> - <varlistentry> - <term>Step 1: get ready for configuration.</term> - <listitem> - <para>NOTE: if you're starting from a source distribution, - rather than darcs sources, you can skip this step.</para> - - <para>Change directory to - <constant>$(GHC_TOP)</constant> and - issue the command</para> -<screen>$ autoreconf</screen> - <indexterm><primary>autoreconf</primary></indexterm> - <para>(with no arguments). This GNU program (recursively) converts - <filename>$(GHC_TOP)/configure.ac</filename> and - <filename>$(GHC_TOP)/aclocal.m4</filename> - to a shell script called - <filename>$(GHC_TOP)/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 parts of the source tree, particularly - libraries, 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 - <filename>$(GHC_TOP)</filename>.</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> - - <varlistentry> - <term>Step 2: system configuration.</term> - <listitem> - <para>Runs the newly-created <command>configure</command> - script, thus:</para> - -<screen>$ ./configure <optional><parameter>args</parameter></optional></screen> - - <para><command>configure</command>'s mission is to scurry - round your computer working out what architecture it has, - what operating system, whether it has the - <function>vfork</function> system call, where - <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 - communicates these snippets of information in two - ways:</para> - - <itemizedlist> - <listitem> - - <para>It translates - <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm> - to - <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>, - substituting for things between - “<literal>@</literal>” brackets. So, - “<literal>@HaveGcc@</literal>” will be - replaced by “<literal>YES</literal>” or - “<literal>NO</literal>” depending on what - <command>configure</command> finds. - <filename>mk/config.mk</filename> is included by every - Makefile (directly or indirectly), so the - configuration information is thereby communicated to - all Makefiles.</para> - </listitem> - - <listitem> - <para> It translates - <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm> - to - <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>. - The latter is <literal>#include</literal>d by - various C programs, which can thereby make use of - configuration information.</para> - </listitem> - </itemizedlist> - - <para><command>configure</command> takes some optional - arguments. Use <literal>./configure --help</literal> to - get a list of the available arguments. Here are some of - the ones you might need:</para> - - <variablelist> - <varlistentry> - <term><literal>--with-ghc=<parameter>path</parameter></literal> - <indexterm><primary><literal>--with-ghc</literal></primary></indexterm> - </term> - <listitem> - <para>Specifies the path to an installed GHC which - you would like to use. This compiler will be used - for compiling GHC-specific code (eg. GHC itself). - This option <emphasis>cannot</emphasis> be specified - using <filename>build.mk</filename> (see later), - because <command>configure</command> needs to - auto-detect the version of GHC you're using. The - default is to look for a compiler named - <literal>ghc</literal> in your path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>--with-hc=<parameter>path</parameter></literal> - <indexterm><primary><literal>--with-hc</literal></primary></indexterm> - </term> - <listitem> - <para>Specifies the path to any installed Haskell - compiler. This compiler will be used for compiling - generic Haskell code. The default is to use - <literal>ghc</literal>. (NOTE: I'm not sure it - actually works to specify a compiler other than GHC - here; unless you really know what you're doing I - suggest not using this option at all.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>--with-gcc=<parameter>path</parameter></literal> - <indexterm><primary><literal>--with-gcc</literal></primary></indexterm> - </term> - <listitem> - <para>Specifies the path to the installed GCC. This - compiler will be used to compile all C files, - <emphasis>except</emphasis> any generated by the - installed Haskell compiler, which will have its own - idea of which C compiler (if any) to use. The - default is to use <literal>gcc</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Step 3: build configuration.</term> - <listitem> - <para>Next, you say how this build of - GHC is to differ from the standard - defaults by creating a new file - <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm> - <emphasis>in the build tree</emphasis>. This file is the - one and only file you edit in the build tree, precisely - because it says how this build differs from the source. - (Just in case your build tree does die, you might want to - keep a private directory of <filename>build.mk</filename> - files, and use a symbolic link in each build tree to point - to the appropriate one.) So - <filename>mk/build.mk</filename> never exists in the - source tree—you create one in each build tree from - the template. We'll discuss what to put in it - shortly.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>And that's it for configuration. Simple, eh?</para> - - <para>What do you put in your build-specific configuration file - <filename>mk/build.mk</filename>? <emphasis>For almost all - purposes all you will do is put make variable definitions that - override those in</emphasis> - <filename>mk/config.mk.in</filename>. The whole point of - <filename>mk/config.mk.in</filename>—and its derived - counterpart <filename>mk/config.mk</filename>—is to define - the build configuration. It is heavily commented, as you will - see if you look at it. So generally, what you do is look at - <filename>mk/config.mk.in</filename>, and add definitions in - <filename>mk/build.mk</filename> that override any of the - <filename>config.mk</filename> definitions that you want to - change. (The override occurs because the main boilerplate file, - <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>, - 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> - -<programlisting>GhcHcOpts=-Rghc-timing</programlisting> - - <para>The accompanying comment explains that this is the list of - flags passed to GHC when building GHC itself. For doing - development, it is wise to add <literal>-DDEBUG</literal>, to - enable debugging code. So you would add the following to - <filename>build.mk</filename>:</para> - -<programlisting>GhcHcOpts += -DDEBUG</programlisting> - - <para>GNU <command>make</command> allows existing definitions to - have new text appended using the “<literal>+=</literal>” - operator, which is quite a convenient feature.</para> - - <para>Haskell compilations by default have <literal>-O</literal> - turned on, by virtue of this setting from - <filename>config.mk</filename>:</para> - -<programlisting>SRC_HC_OPTS += -H16m -O</programlisting> - - <para><literal>SRC_HC_OPTS</literal> means "options for HC from - the source tree", where HC stands for Haskell Compiler. - <literal>SRC_HC_OPTS</literal> are added to every Haskell - compilation. To turn off optimisation, you could add this to - <filename>build.mk</filename>:</para> - -<programlisting>SRC_HC_OPTS = -H16m -O0</programlisting> - - <para>Or you could just add <literal>-O0</literal> to - <literal>GhcHcOpts</literal> to turn off optimisation for the - compiler. See <xref linkend="quick-start" /> for some more - suggestions.</para> - - <para>When reading <filename>config.mk.in</filename>, remember - that anything between “@...@” signs is going to be substituted - by <command>configure</command> later. You - <emphasis>can</emphasis> override the resulting definition if - you want, but you need to be a bit surer what you are doing. - For example, there's a line that says:</para> - -<programlisting>TAR = @TarCmd@</programlisting> - - <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>tar</command> you want to use instead, that's - fine. Just add this line to <filename>mk/build.mk</filename>:</para> - -<programlisting>TAR = mytar</programlisting> - - <para>You do not <emphasis>have</emphasis> to have a - <filename>mk/build.mk</filename> file at all; if you don't, - you'll get all the default settings from - <filename>mk/config.mk.in</filename>.</para> - - <para>You can also use <filename>build.mk</filename> to override - anything that <command>configure</command> got wrong. One place - where this happens often is with the definition of - <constant>GHC_TOP_ABS</constant>: this - variable is supposed to be the canonical path to the top of your - source tree, but if your system uses an automounter then the - correct directory is hard to find automatically. If you find - that <command>configure</command> has got it wrong, just put the - correct definition in <filename>build.mk</filename>.</para> - </sect2> - - <sect2 id="sec-storysofar"> - <title>The story so far</title> - - <para>Let's summarise the steps you need to carry to get - yourself a fully-configured build tree from scratch.</para> - - <orderedlist> - <listitem> - <para> Get your source tree from somewhere (darcs repository - or source distribution). Say you call the root directory - <filename>myghc</filename> (it does not have to be - called <filename>ghc</filename>).</para> - </listitem> - - <listitem> - <para>(Optional) Use <command>lndir</command> or - <command>mkshadowdir</command> to create a build tree.</para> - -<screen>$ cd myghc -$ mkshadowdir . /scratch/joe-bloggs/myghc-x86</screen> - - <para>(N.B. <command>mkshadowdir</command>'s first argument - is taken relative to its second.) You probably want to give - the build tree a name that suggests its main defining - characteristic (in your mind at least), in case you later - add others.</para> - </listitem> - - <listitem> - <para>Change directory to the build tree. Everything is - going to happen there now.</para> - -<screen>$ cd /scratch/joe-bloggs/myghc-x86</screen> - - </listitem> - - <listitem> - <para>Prepare for system configuration:</para> - -<screen>$ autoreconf</screen> - - <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> - </listitem> - - <listitem> - <para>Do system configuration:</para> - -<screen>$ ./configure</screen> - - <para>Don't forget to check whether you need to add any - arguments to <literal>configure</literal>; for example, a - common requirement is to specify which GHC to use with - <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para> - </listitem> - - <listitem> - <para>Create the file <filename>mk/build.mk</filename>, - adding definitions for your desired configuration - options.</para> - </listitem> - </orderedlist> - - <para>You can make subsequent changes to - <filename>mk/build.mk</filename> as often as you like. You do - not have to run any further configuration programs to make these - changes take effect. In theory you should, however, say - <command>make clean; make</command>, because configuration - option changes could affect anything—but in practice you - are likely to know what's affected.</para> - </sect2> - - <sect2> - <title>Making things</title> - - <para>At this point you have made yourself a fully-configured - build tree, so you are ready to start building real - things.</para> - - <para>The first thing you need to know is that <emphasis>you - must use GNU <command>make</command></emphasis>. On some - systems (eg. FreeBSD) this is called <command>gmake</command>, - whereas on others it is the standard <command>make</command> - command. In this document we will always refer to it as - <command>make</command>; please substitute with - <command>gmake</command> if your system requires it. If you use - a the wrong <command>make</command> you will get all sorts of - error messages (but no damage) because the GHC - <command>Makefiles</command> use GNU <command>make</command>'s - facilities extensively.</para> - - <para>To just build the whole thing, <command>cd</command> to - the top of your build tree and type <command>make</command>. - This will prepare the tree and build the various parts in the - correct order, resulting in a complete build of GHC that can - even be used directly from the tree, without being installed - first.</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 <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. The top-level - <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> - - <varlistentry> - <term><literal>binary-dist</literal></term> - <listitem> - <para>make a binary distribution. This is the target we - use to build the binary distributions of GHC.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>dist</literal></term> - <listitem> - <para>make a source distribution. Note that this target - does “make distclean” as part of its work; - don't use it if you want to keep what you've built.</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>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>compiler</literal>.</para> - </sect2> - - <sect2 id="sec-standard-targets"> - <title>Standard Targets</title> - <indexterm><primary>targets, standard makefile</primary></indexterm> - <indexterm><primary>makefile targets</primary></indexterm> - - <para>In any directory you should be able to make the following:</para> - - <variablelist> - <varlistentry> - <term><literal>boot</literal></term> - <listitem> - <para>does the one-off preparation required to get ready - for the real work. Notably, it does <command>make - depend</command> in all directories that contain programs. - It also builds the necessary tools for compilation to - proceed.</para> - - <para>Invoking the <literal>boot</literal> target - explicitly is not normally necessary. From the top-level - directory, invoking <literal>make</literal> causes - <literal>make boot</literal> to be invoked in various - subdirectories first, in the right order. Unless you - really know what you are doing, it is best to always say - <literal>make</literal> from the top level first.</para> - - <para>If you're working in a subdirectory somewhere and - need to update the dependencies, <literal>make - boot</literal> is a good way to do it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>all</literal></term> - <listitem> - <para>makes all the final target(s) for this Makefile. - Depending on which directory you are in a “final - target” may be an executable program, a library - archive, a shell script, or a Postscript file. Typing - <command>make</command> alone is generally the same as - typing <command>make all</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>install</literal></term> - <listitem> - <para>installs the things built by <literal>all</literal> - (except for the documentation). Where does it install - them? That is specified by - <filename>mk/config.mk.in</filename>; you can override it - in <filename>mk/build.mk</filename>, or by running - <command>configure</command> with command-line arguments - like <literal>--bindir=/home/simonpj/bin</literal>; see - <literal>./configure --help</literal> for the full - details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>install-docs</literal></term> - <listitem> - <para>installs the documentation. Otherwise behaves just - like <literal>install</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>uninstall</literal></term> - <listitem> - <para>reverses the effect of - <literal>install</literal> (WARNING: probably doesn't work).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>clean</literal></term> - <listitem> - <para>Delete all files from the current directory that are - normally created by building the program. Don't delete - the files that record the configuration, or files - generated by <command>make boot</command>. Also preserve - files that could be made by building, but normally aren't - because the distribution comes with them.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>distclean</literal></term> - <listitem> - <para>Delete all files from the current directory that are - created by configuring or building the program. If you - have unpacked the source and built the program without - creating any other files, <literal>make - distclean</literal> should leave only the files that were - in the distribution.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>mostlyclean</literal></term> - <listitem> - <para>Like <literal>clean</literal>, but may refrain from - deleting a few files that people normally don't want to - recompile.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>maintainer-clean</literal></term> - <listitem> - <para>Delete everything from the current directory that - can be reconstructed with this Makefile. This typically - includes everything deleted by - <literal>distclean</literal>, plus more: C source files - produced by Bison, tags tables, Info files, and so - on.</para> - - <para>One exception, however: <literal>make - maintainer-clean</literal> should not delete - <filename>configure</filename> even if - <filename>configure</filename> can be remade using a rule - in the <filename>Makefile</filename>. More generally, - <literal>make maintainer-clean</literal> should not delete - anything that needs to exist in order to run - <filename>configure</filename> and then begin to build the - program.</para> - - <para>After a <literal>maintainer-clean</literal>, a - <literal>configure</literal> will be necessary before - building again.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>All of these standard targets automatically recurse into - sub-directories. Certain other standard targets do not:</para> - - <variablelist> - <varlistentry> - <term><literal>depend</literal></term> - <listitem> - <para>make a <filename>.depend</filename> file in each - directory that needs it. This <filename>.depend</filename> - file contains mechanically-generated dependency - information; for example, suppose a directory contains a - Haskell source module <filename>Foo.lhs</filename> which - imports another module <literal>Baz</literal>. Then the - generated <filename>.depend</filename> file will contain - the dependency:</para> - -<programlisting>Foo.o : Baz.hi</programlisting> - - <para>which says that the object file - <filename>Foo.o</filename> depends on the interface file - <filename>Baz.hi</filename> generated by compiling module - <literal>Baz</literal>. The <filename>.depend</filename> - file is automatically included by every Makefile.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Some <filename>Makefile</filename>s have targets other - than these. You can discover them by looking in the - <filename>Makefile</filename> itself.</para> - </sect2> - - <sect2> - <title>Using GHC from the build tree</title> - - <para>If you want to build GHC and just use it direct from the - build tree without doing <literal>make install</literal> first, - you can run the in-place driver script. To run the stage 1 - compiler, use <filename>compiler/stage1/ghc-inplace</filename>, - stage 2 is <filename>compiler/stage2/ghc-inplace</filename>, and - so on.</para> - - <para> Do <emphasis>NOT</emphasis> use - <filename>compiler/stage1/ghc</filename>, or - <filename>compiler/stage1/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> - - <sect2> - <title>Fast Making</title> - - <indexterm><primary>fastmake</primary></indexterm> - <indexterm><primary>dependencies, omitting</primary></indexterm> - <indexterm><primary>FAST, makefile variable</primary></indexterm> - - <para>Sometimes the dependencies get in the way: if you've made - a small change to one file, and you're absolutely sure that it - won't affect anything else, but you know that - <command>make</command> is going to rebuild everything anyway, - the following hack may be useful:</para> - -<screen>$ make FAST=YES</screen> - - <para>This tells the make system to ignore dependencies and just - build what you tell it to. In other words, it's equivalent to - temporarily removing the <filename>.depend</filename> file in - the current directory (where <command>mkdependHS</command> and - friends store their dependency information).</para> - - <para>A bit of history: GHC used to come with a - <command>fastmake</command> script that did the above job, but - GNU make provides the features we need to do it without - resorting to a script. Also, we've found that fastmaking is - less useful since the advent of GHC's recompilation checker (see - the User's Guide section on "Separate Compilation").</para> - </sect2> - </sect1> - - <sect1 id="sec-makefile-arch"> - <title>The <filename>Makefile</filename> architecture</title> - <indexterm><primary>makefile architecture</primary></indexterm> - - <para><command>make</command> is great if everything - works—you type <command>make install</command> and lo! the - right things get compiled and installed in the right places. Our - goal is to make this happen often, but somehow it often doesn't; - instead some weird error message eventually emerges from the - bowels of a directory you didn't know existed.</para> - - <para>The purpose of this section is to give you a road-map to - help you figure out what is going right and what is going - wrong.</para> - - <sect2> - <title>Debugging</title> - - <para>Debugging <filename>Makefile</filename>s is something of a - black art, but here's a couple of tricks that we find - particularly useful. The following command allows you to see - the contents of any make variable in the context of the current - <filename>Makefile</filename>:</para> - -<screen>$ make show VALUE=HS_SRCS</screen> - - <para>where you can replace <literal>HS_SRCS</literal> with the - name of any variable you wish to see the value of.</para> - - <para>GNU make has a <option>-d</option> option which generates - a dump of the decision procedure used to arrive at a conclusion - about which files should be recompiled. Sometimes useful for - tracking down problems with superfluous or missing - recompilations.</para> - </sect2> - - <sect2> - <title>A small example</title> - - <para>To get started, let us look at the - <filename>Makefile</filename> for an imaginary small program, - <literal>small</literal>. Each program or library in the GHC - source tree typically has its own directory, in this case we'll - use <filename>$(GHC_TOP)/small</filename>. - Inside the <filename>small/</filename> directory there will be a - <filename>Makefile</filename>, looking something like - this:</para> - -<indexterm><primary>Makefile, minimal</primary></indexterm> - -<programlisting># Makefile for program "small" -TOP = .. -include $(TOP)/mk/boilerplate.mk - -HS_PROG = small - -include $(TOP)/target.mk</programlisting> - - <para>this <filename>Makefile</filename> has three - sections:</para> - - <orderedlist> - <listitem> - <para>The first section includes -<footnote> -<para> -One of the most important -features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to -include another named file, very like <command>cpp</command>'s <literal>#include</literal> -directive. -</para> -</footnote> - - a file of “boilerplate” code from the top level - <indexterm><primary>boilerplate.mk</primary></indexterm>). - As its name suggests, <filename>boilerplate.mk</filename> - consists of a large quantity of standard - <filename>Makefile</filename> code. We discuss this - boilerplate in more detail in <xref linkend="sec-boiler"/>. - <indexterm><primary>include, directive in - Makefiles</primary></indexterm> <indexterm><primary>Makefile - inclusion</primary></indexterm></para> - - <para>Before the <literal>include</literal> statement, you - must define the <command>make</command> variable - <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm> - to be the top-level directory of the source tree, containing - the <filename>mk</filename> - directory in which the <filename>boilerplate.mk</filename> - file is. It is <emphasis>not</emphasis> OK to simply say</para> - -<programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting> - - <para>Why? Because the <filename>boilerplate.mk</filename> - file needs to know where it is, so that it can, in turn, - <literal>include</literal> other files. (Unfortunately, - when an <literal>include</literal>d file does an - <literal>include</literal>, the filename is treated relative - to the directory in which <command>make</command> is being - run, not the directory in which the - <literal>include</literal>d sits.) In general, - <emphasis>every file <filename>foo.mk</filename> assumes - that - <filename>$(TOP)/mk/foo.mk</filename> - refers to itself.</emphasis> It is up to the - <filename>Makefile</filename> doing the - <literal>include</literal> to ensure this is the case.</para> - </listitem> - - <listitem> - <para> The second section defines the standard - <command>make</command> variable - <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm> - (the executable binary to be built). We will discuss in - more detail what the “standard variables” are, - and how they affect what happens, in <xref - linkend="sec-targets"/>.</para> - </listitem> - - <listitem> - <para>The last section includes a second file of standard - code, called - <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>. - It contains the rules that tell <command>make</command> how - to make the standard targets (<xref - linkend="sec-standard-targets"/>). Why, you ask, can't this - standard code be part of - <filename>boilerplate.mk</filename>? Good question. We - discuss the reason later, in <xref - linkend="sec-boiler-arch"/>.</para> - - <para>You do not <emphasis>have</emphasis> to - <literal>include</literal> the - <filename>target.mk</filename> file. Instead, you can write - rules of your own for all the standard targets. Usually, - though, you will find quite a big payoff from using the - canned rules in <filename>target.mk</filename>; the price - tag is that you have to understand what canned rules get - enabled, and what they do (<xref - linkend="sec-targets"/>).</para> - </listitem> - </orderedlist> - - <para>In our example <filename>Makefile</filename>, most of the - work is done by the two <literal>include</literal>d files. When - you say <command>make all</command>, the following things - happen:</para> - - <itemizedlist> - <listitem> - <para><command>make</command> looks in the current directory - to see what source files it can find - (eg. <filename>Foo.hs</filename>, - <filename>Baz.c</filename>), and from that it figures out - what object files need to be built - (eg. <filename>Foo.o</filename>, - <filename>Baz.o</filename>). Because source files are found - and used automatically, omitting them from a program or - library has to be done manually (see - <literal>EXCLUDED_SRCS</literal> in <xref - linkend="sec-boiler" />).</para> - </listitem> - - <listitem> - <para>It uses a boilerplate pattern rule to compile - <filename>Foo.hs</filename> to <filename>Foo.o</filename> - using a Haskell compiler. (Which one? That is set in the - build configuration.)</para> - </listitem> - - <listitem> - <para>It uses another standard pattern rule to compile - <filename>Baz.c</filename> to <filename>Baz.o</filename>, - using a C compiler. (Ditto.)</para> - </listitem> - - <listitem> - <para>It links the resulting <filename>.o</filename> files - together to make <literal>small</literal>, using the Haskell - compiler to do the link step. (Why not use - <command>ld</command>? Because the Haskell compiler knows - what standard libraries to link in. How did - <command>make</command> know to use the Haskell compiler to - do the link, rather than the C compiler? Because we set the - variable <constant>HS_PROG</constant> rather than - <constant>C_PROG</constant>.)</para> - </listitem> - </itemizedlist> - - <para>All <filename>Makefile</filename>s should follow the above - three-section format.</para> - </sect2> - - <sect2 id="sec-boiler-arch"> - <title>Boilerplate architecture</title> - <indexterm><primary>boilerplate architecture</primary></indexterm> - - <para>Every <filename>Makefile</filename> includes a - <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm> - file at the top, and - <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm> - file at the bottom. In this section we discuss what is in these - files, and why there have to be two of them. In general:</para> - - <itemizedlist> - <listitem> - <para><filename>boilerplate.mk</filename> consists of:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Definitions of millions of - <command>make</command> variables</emphasis> that - collectively specify the build configuration. Examples: - <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>, - the options to feed to the Haskell compiler; - <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>, - the sub-directories to enable within the - <literal>nofib</literal> project; - <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>, - the name of the Haskell compiler to use when compiling - GHC in the <literal>ghc</literal> project.</para> - </listitem> - - <listitem> - <para><emphasis>Standard pattern rules</emphasis> that - tell <command>make</command> how to construct one file - from another.</para> - </listitem> - </itemizedlist> - - <para><filename>boilerplate.mk</filename> needs to be - <literal>include</literal>d at the <emphasis>top</emphasis> - of each <filename>Makefile</filename>, so that the user can - replace the boilerplate definitions or pattern rules by - simply giving a new definition or pattern rule in the - <filename>Makefile</filename>. <command>make</command> - simply takes the last definition as the definitive one.</para> - - <para>Instead of <emphasis>replacing</emphasis> boilerplate - definitions, it is also quite common to - <emphasis>augment</emphasis> them. For example, a - <filename>Makefile</filename> might say:</para> - -<programlisting>SRC_HC_OPTS += -O</programlisting> - - <para>thereby adding “<option>-O</option>” to - the end of - <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para> - </listitem> - - <listitem> - <para><filename>target.mk</filename> contains - <command>make</command> rules for the standard targets - described in <xref linkend="sec-standard-targets"/>. These - rules are selectively included, depending on the setting of - certain <command>make</command> variables. These variables - are usually set in the middle section of the - <filename>Makefile</filename> between the two - <literal>include</literal>s.</para> - - <para><filename>target.mk</filename> must be included at the - end (rather than being part of - <filename>boilerplate.mk</filename>) for several tiresome - reasons:</para> - - <itemizedlist> - <listitem> - - <para><command>make</command> commits target and - dependency lists earlier than it should. For example, - <filename>target.mk</filename> has a rule that looks - like this:</para> - -<programlisting>$(HS_PROG) : $(OBJS) - $(HC) $(LD_OPTS) $< -o $@</programlisting> - - <para>If this rule was in - <filename>boilerplate.mk</filename> then - <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm> - and - <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm> - would not have their final values at the moment - <command>make</command> encountered the rule. Alas, - <command>make</command> takes a snapshot of their - current values, and wires that snapshot into the rule. - (In contrast, the commands executed when the rule - “fires” are only substituted at the moment - of firing.) So, the rule must follow the definitions - given in the <filename>Makefile</filename> itself.</para> - </listitem> - - <listitem> - <para>Unlike pattern rules, ordinary rules cannot be - overriden or replaced by subsequent rules for the same - target (at least, not without an error message). - Including ordinary rules in - <filename>boilerplate.mk</filename> would prevent the - user from writing rules for specific targets in specific - cases.</para> - </listitem> - - <listitem> - <para>There are a couple of other reasons I've - forgotten, but it doesn't matter too much.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="sec-boiler"> - <title>The <filename>mk/boilerplate.mk</filename> file</title> - <indexterm><primary>boilerplate.mk</primary></indexterm> - - <para>If you look at - <filename>$(GHC_TOP)/mk/boilerplate.mk</filename> - you will find that it consists of the following sections, each - held in a separate file:</para> - - <variablelist> - <varlistentry> - <term><filename>config.mk</filename> - <indexterm><primary>config.mk</primary></indexterm> - </term> - <listitem> - <para>is the build configuration file we discussed at - length in <xref linkend="sec-build-config"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>paths.mk</filename> - <indexterm><primary>paths.mk</primary></indexterm> - </term> - <listitem> - <para>defines <command>make</command> variables for - pathnames and file lists. This file contains code for - automatically compiling lists of source files and deriving - lists of object files from those. The results can be - overriden in the <filename>Makefile</filename>, but in - most cases the automatic setup should do the right - thing.</para> - - <para>The following variables may be set in the - <filename>Makefile</filename> to affect how the automatic - source file search is done:</para> - - <variablelist> - <varlistentry> - <term><literal>ALL_DIRS</literal> - <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm> - </term> - <listitem> - <para>Set to a list of directories to search in - addition to the current directory for source - files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <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 - current directory) to omit from the automatic - search. The source searching machinery is clever - enough to know that if you exclude a source file - from which other sources are derived, then the - derived sources should also be excluded. For - example, if you set <literal>EXCLUDED_SRCS</literal> - to include <filename>Foo.y</filename>, then - <filename>Foo.hs</filename> will also be - excluded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>EXTRA_SRCS</literal> - <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>Set to a list of extra source files (perhaps - in directories not listed in - <literal>ALL_DIRS</literal>) that should be - considered.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The results of the automatic source file search are - placed in the following make variables:</para> - - <variablelist> - <varlistentry> - <term><literal>SRCS</literal> - <indexterm><primary><literal>SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>All source files found, sorted and without - duplicates, including those which might not exist - yet but will be derived from other existing sources. - <literal>SRCS</literal> <emphasis>can</emphasis> be - overriden if necessary, in which case the variables - below will follow suit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HS_SRCS</literal> - <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>all Haskell source files in the current - directory, including those derived from other source - files (eg. Happy sources also give rise to Haskell - sources).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HS_OBJS</literal> - <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm> - </term> - <listitem> - <para>Object files derived from - <literal>HS_SRCS</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HS_IFACES</literal> - <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm> - </term> - <listitem> - <para>Interface files (<literal>.hi</literal> files) - derived from <literal>HS_SRCS</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>C_SRCS</literal> - <indexterm><primary><literal>C_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>All C source files found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>C_OBJS</literal> - <indexterm><primary><literal>C_OBJS</literal></primary></indexterm> - </term> - <listitem> - <para>Object files derived from - <literal>C_SRCS</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>SCRIPT_SRCS</literal> - <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>All script source files found - (<literal>.lprl</literal> files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>SCRIPT_OBJS</literal> - <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm> - </term> - <listitem> - <para><quote>object</quote> files derived from - <literal>SCRIPT_SRCS</literal> - (<literal>.prl</literal> files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HSC_SRCS</literal> - <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>All <literal>hsc2hs</literal> source files - (<literal>.hsc</literal> files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HAPPY_SRCS</literal> - <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm> - </term> - <listitem> - <para>All <literal>happy</literal> source files - (<literal>.y</literal> or <literal>.hy</literal> files).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>OBJS</literal> - <indexterm><primary>OBJS</primary></indexterm> - </term> - <listitem> - <para>the concatenation of - <literal>$(HS_OBJS)</literal>, - <literal>$(C_OBJS)</literal>, and - <literal>$(SCRIPT_OBJS)</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Any or all of these definitions can easily be - overriden by giving new definitions in your - <filename>Makefile</filename>.</para> - - <para>What, exactly, does <filename>paths.mk</filename> - consider a <quote>source file</quote> to be? It's based - on the file's suffix (e.g. <filename>.hs</filename>, - <filename>.lhs</filename>, <filename>.c</filename>, - <filename>.hy</filename>, etc), but this is the kind of - detail that changes, so rather than enumerate the source - suffices here the best thing to do is to look in - <filename>paths.mk</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>opts.mk</filename> - <indexterm><primary>opts.mk</primary></indexterm> - </term> - <listitem> - <para>defines <command>make</command> variables for option - strings to pass to each program. For example, it defines - <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>, - the option strings to pass to the Haskell compiler. See - <xref linkend="sec-suffix"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>suffix.mk</filename> - <indexterm><primary>suffix.mk</primary></indexterm> - </term> - <listitem> - <para>defines standard pattern rules—see <xref - linkend="sec-suffix"/>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Any of the variables and pattern rules defined by the - boilerplate file can easily be overridden in any particular - <filename>Makefile</filename>, because the boilerplate - <literal>include</literal> comes first. Definitions after this - <literal>include</literal> directive simply override the default - ones in <filename>boilerplate.mk</filename>.</para> - </sect2> - - <sect2 id="sec-platforms"> - <title>Platform settings</title> - <indexterm><primary>Platform settings</primary> - </indexterm> - - <para>There are three platforms of interest when building GHC:</para> - - <variablelist> - <varlistentry> - <term>The <emphasis>build</emphasis> platform</term> - <listitem> - <para>The platform on which we are doing this build.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The <emphasis>host</emphasis> platform</term> - <listitem> - <para>The platform on which these binaries will run.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The <emphasis>target</emphasis> platform</term> - <listitem> - <para>The platform for which this compiler will generate code.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>These platforms are set when running the - <literal>configure</literal> script, using the - <option>--build</option>, <option>--host</option>, and - <option>--target</option> options. The <filename>mk/config.mk</filename> - file defines several symbols related to the platform settings (see - <filename>mk/config.mk</filename> for details).</para> - - <para>We don't currently support build & host being different, because - the build process creates binaries that are both run during the build, - and also installed.</para> - - <para>If host and target are different, then we are building a - cross-compiler. For GHC, this means a compiler - which will generate intermediate .hc files to port to the target - architecture for bootstrapping. The libraries and stage 2 compiler - will be built as HC files for the target system (see <xref - linkend="sec-porting-ghc" /> for details.</para> - - <para>More details on when to use BUILD, HOST or TARGET can be found in - the comments in <filename>config.mk</filename>.</para> - </sect2> - - <sect2 id="sec-suffix"> - <title>Pattern rules and options</title> - <indexterm><primary>Pattern rules</primary></indexterm> - - <para>The file - <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm> - defines standard <emphasis>pattern rules</emphasis> that say how - to build one kind of file from another, for example, how to - build a <filename>.o</filename> file from a - <filename>.c</filename> file. (GNU <command>make</command>'s - <emphasis>pattern rules</emphasis> are more powerful and easier - to use than Unix <command>make</command>'s <emphasis>suffix - rules</emphasis>.)</para> - - <para>Almost all the rules look something like this:</para> - -<programlisting>%.o : %.c - $(RM) $@ - $(CC) $(CC_OPTS) -c $< -o $@</programlisting> - - <para>Here's how to understand the rule. It says that - <emphasis>something</emphasis><filename>.o</filename> (say - <filename>Foo.o</filename>) can be built from - <emphasis>something</emphasis><filename>.c</filename> - (<filename>Foo.c</filename>), by invoking the C compiler (path - name held in <constant>$(CC)</constant>), passing to it - the options <constant>$(CC_OPTS)</constant> and - the rule's dependent file of the rule - <literal>$<</literal> (<filename>Foo.c</filename> in - this case), and putting the result in the rule's target - <literal>$@</literal> (<filename>Foo.o</filename> in this - case).</para> - - <para>Every program is held in a <command>make</command> - variable defined in <filename>mk/config.mk</filename>—look - in <filename>mk/config.mk</filename> for the complete list. One - important one is the Haskell compiler, which is called - <constant>$(HC)</constant>.</para> - - <para>Every program's options are are held in a - <command>make</command> variables called - <constant><prog>_OPTS</constant>. the - <constant><prog>_OPTS</constant> variables are - defined in <filename>mk/opts.mk</filename>. Almost all of them - are defined like this:</para> - -<programlisting>CC_OPTS = \ - $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting> - - <para>The four variables from which - <constant>CC_OPTS</constant> is built have the following - meaning:</para> - - <variablelist> - <varlistentry> - <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term> - <listitem> - <para>options passed to all C compilations.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>WAY_<way>_CC_OPTS</constant>:</term> - <listitem> - <para>options passed to C compilations for way - <literal><way></literal>. For example, - <constant>WAY_mp_CC_OPTS</constant> - gives options to pass to the C compiler when compiling way - <literal>mp</literal>. The variable - <constant>WAY_CC_OPTS</constant> holds - options to pass to the C compiler when compiling the - standard way. (<xref linkend="sec-ways"/> dicusses - multi-way compilation.)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant><module>_CC_OPTS</constant>:</term> - <listitem> - <para>options to pass to the C compiler that are specific - to module <literal><module></literal>. For example, - <constant>SMap_CC_OPTS</constant> gives the - specific options to pass to the C compiler when compiling - <filename>SMap.c</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term> - <listitem> - <para>extra options to pass to all C compilations. This - is intended for command line use, thus:</para> - -<screen>$ make libHS.a EXTRA_HC_OPTS="-v"</screen> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="sec-targets"> - <title>The main <filename>mk/target.mk</filename> file</title> - <indexterm><primary>target.mk</primary></indexterm> - - <para><filename>target.mk</filename> contains canned rules for - all the standard targets described in <xref - linkend="sec-standard-targets"/>. It is complicated by the fact - that you don't want all of these rules to be active in every - <filename>Makefile</filename>. Rather than have a plethora of - tiny files which you can include selectively, there is a single - file, <filename>target.mk</filename>, which selectively includes - rules based on whether you have defined certain variables in - your <filename>Makefile</filename>. This section explains what - rules you get, what variables control them, and what the rules - do. Hopefully, you will also get enough of an idea of what is - supposed to happen that you can read and understand any weird - special cases yourself.</para> - - <variablelist> - <varlistentry> - <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term> - <listitem> - <para>If <constant>HS_PROG</constant> is defined, - you get rules with the following targets:</para> - - <variablelist> - <varlistentry> - <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term> - <listitem> - <para>itself. This rule links - <constant>$(OBJS)</constant> with the Haskell - runtime system to get an executable called - <constant>$(HS_PROG)</constant>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term> - <listitem> - <para>installs - <constant>$(HS_PROG)</constant> in - <constant>$(bindir)</constant>.</para> - </listitem> - </varlistentry> - </variablelist> - - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term> - <listitem> - <para>is similar to <constant>HS_PROG</constant>, - except that the link step links - <constant>$(C_OBJS)</constant> with the C - runtime system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term> - <listitem> - <para>is similar to <constant>HS_PROG</constant>, - except that it links - <constant>$(LIB_OBJS)</constant> to make the - library archive <constant>$(LIBRARY)</constant>, - and <literal>install</literal> installs it in - <constant>$(libdir)</constant>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Some rules are “double-colon” rules, - thus</para> - -<programlisting>install :: $(HS_PROG) - ...how to install it...</programlisting> - - <para>GNU <command>make</command> treats double-colon rules as - separate entities. If there are several double-colon rules for - the same target it takes each in turn and fires it if its - dependencies say to do so. This means that you can, for - example, define both <constant>HS_PROG</constant> and - <constant>LIBRARY</constant>, which will generate two rules for - <literal>install</literal>. When you type <command>make - install</command> both rules will be fired, and both the program - and the library will be installed, just as you wanted.</para> - </sect2> - - <sect2 id="sec-subdirs"> - <title>Recursion</title> - <indexterm><primary>recursion, in makefiles</primary></indexterm> - <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm> - - <para>In leaf <filename>Makefile</filename>s the variable - <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm> - is undefined. In non-leaf <filename>Makefile</filename>s, - <constant>SUBDIRS</constant> is set to the list of - sub-directories that contain subordinate - <filename>Makefile</filename>s. <emphasis>It is up to you to - set <constant>SUBDIRS</constant> in the - <filename>Makefile</filename>.</emphasis> There is no automation - here—<constant>SUBDIRS</constant> is too important to - automate.</para> - - <para>When <constant>SUBDIRS</constant> is defined, - <filename>target.mk</filename> includes a rather neat rule for - the standard targets (<xref linkend="sec-standard-targets"/> that - simply invokes <command>make</command> recursively in each of - the sub-directories.</para> - - <para><emphasis>These recursive invocations are guaranteed to - occur in the order in which the list of directories is specified - in <constant>SUBDIRS</constant>. </emphasis>This guarantee can - be important. For example, when you say <command>make - boot</command> it can be important that the recursive invocation - of <command>make boot</command> is done in one sub-directory - (the include files, say) before another (the source files). - Generally, put the most independent sub-directory first, and the - most dependent last.</para> - </sect2> - - <sect2 id="sec-ways"> - <title>Way management</title> - <indexterm><primary>way management</primary></indexterm> - - <para>We sometimes want to build essentially the same system in - several different “ways”. For example, we want to build GHC's - <literal>Prelude</literal> libraries with and without profiling, - so that there is an appropriately-built library archive to link - with when the user compiles his program. It would be possible - to have a completely separate build tree for each such “way”, - but it would be horribly bureaucratic, especially since often - only parts of the build tree need to be constructed in multiple - ways.</para> - - <para>Instead, the - <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm> - contains some clever magic to allow you to build several - versions of a system; and to control locally how many versions - are built and how they differ. This section explains the - magic.</para> - - <para>The files for a particular way are distinguished by - munging the suffix. The <quote>normal way</quote> is always - built, and its files have the standard suffices - <filename>.o</filename>, <filename>.hi</filename>, and so on. - In addition, you can build one or more extra ways, each - distinguished by a <emphasis>way tag</emphasis>. The object - files and interface files for one of these extra ways are - distinguished by their suffix. For example, way - <literal>mp</literal> has files - <filename>.mp_o</filename> and - <filename>.mp_hi</filename>. Library archives have their - way tag the other side of the dot, for boring reasons; thus, - <filename>libHS_mp.a</filename>.</para> - - <para>A <command>make</command> variable called - <constant>way</constant> holds the current way tag. - <emphasis><constant>way</constant> is only ever set on the - command line of <command>make</command></emphasis> (usually in - a recursive invocation of <command>make</command> by the - system). It is never set inside a - <filename>Makefile</filename>. So it is a global constant for - any one invocation of <command>make</command>. Two other - <command>make</command> variables, - <constant>way_</constant> and - <constant>_way</constant> are immediately derived from - <constant>$(way)</constant> and never altered. If - <constant>way</constant> is not set, then neither are - <constant>way_</constant> and - <constant>_way</constant>, and the invocation of - <command>make</command> will build the <quote>normal - way</quote>. If <constant>way</constant> is set, then the other - two variables are set in sympathy. For example, if - <constant>$(way)</constant> is “<literal>mp</literal>”, - then <constant>way_</constant> is set to - “<literal>mp_</literal>” and - <constant>_way</constant> is set to - “<literal>_mp</literal>”. These three variables are - then used when constructing file names.</para> - - <para>So how does <command>make</command> ever get recursively - invoked with <constant>way</constant> set? There are two ways - in which this happens:</para> - - <itemizedlist> - <listitem> - <para>For some (but not all) of the standard targets, when - in a leaf sub-directory, <command>make</command> is - recursively invoked for each way tag in - <constant>$(WAYS)</constant>. You set - <constant>WAYS</constant> in the - <filename>Makefile</filename> to the list of way tags you - want these targets built for. The mechanism here is very - much like the recursive invocation of - <command>make</command> in sub-directories (<xref - linkend="sec-subdirs"/>). It is up to you to set - <constant>WAYS</constant> in your - <filename>Makefile</filename>; this is how you control what - ways will get built.</para> - </listitem> - - <listitem> - <para>For a useful collection of targets (such as - <filename>libHS_mp.a</filename>, - <filename>Foo.mp_o</filename>) there is a rule which - recursively invokes <command>make</command> to make the - specified target, setting the <constant>way</constant> - variable. So if you say <command>make - Foo.mp_o</command> you should see a recursive - invocation <command>make Foo.mp_o way=mp</command>, - and <emphasis>in this recursive invocation the pattern rule - for compiling a Haskell file into a <filename>.o</filename> - file will match</emphasis>. The key pattern rules (in - <filename>suffix.mk</filename>) look like this: - -<programlisting>%.$(way_)o : %.lhs - $(HC) $(HC_OPTS) $< -o $@</programlisting> - - Neat, eh?</para> - </listitem> - - <listitem> - <para>You can invoke <command>make</command> with a - particular <literal>way</literal> setting yourself, in order - to build files related to a particular - <literal>way</literal> in the current directory. eg. - -<screen>$ make way=p</screen> - - will build files for the profiling way only in the current - directory. </para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>When the canned rule isn't right</title> - - <para>Sometimes the canned rule just doesn't do the right thing. - For example, in the <literal>nofib</literal> suite we want the - link step to print out timing information. The thing to do here - is <emphasis>not</emphasis> to define - <constant>HS_PROG</constant> or - <constant>C_PROG</constant>, and instead define a special - purpose rule in your own <filename>Makefile</filename>. By - using different variable names you will avoid the canned rules - being included, and conflicting with yours.</para> - </sect2> - </sect1> - - <sect1 id="building-docs"> - <title>Building the documentation</title> - - <sect2 id="pre-supposed-doc-tools"> - <title>Tools for building the Documentation</title> - - <para>The following additional tools are required if you want to - format the documentation that comes with GHC:</para> - - <variablelist> - <varlistentry> - <term>DocBook - <indexterm><primary>pre-supposed: DocBook</primary></indexterm> - <indexterm><primary>DocBook, pre-supposed</primary></indexterm> - </term> - <listitem> - <para>Much of our documentation is written in DocBook XML, instructions - on installing and configuring the DocBook tools are below.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>TeX - <indexterm><primary>pre-supposed: TeX</primary></indexterm> - <indexterm><primary>TeX, pre-supposed</primary></indexterm> - </term> - <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 - <indexterm><primary>Haddock</primary></indexterm> - </term> - <listitem> - <para>Haddock is a Haskell documentation tool that we use - for automatically generating documentation from the - library source code. To build documentation for the - libraries (<literal>$(GHC_TOP)/libraries</literal>) you - should build and install Haddock. 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 (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 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> - <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>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> - - </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>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>XMLDocWays</literal> variable - to a list of them. For example, in - <filename>build.mk</filename> you might have a line:</para> - -<screen>XMLDocWays = 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>$(XMLDocWays)</literal> - to a list of formats, the <literal>install-docs</literal> target - won't do anything for DocBook XML documentation.</para> - </sect2> - - </sect1> - - - <sect1 id="sec-porting-ghc"> - <title>Porting GHC</title> - - <para>This section describes how to port GHC to a currenly - unsupported platform. To avoid confusion, when we say - “architecture” we are referring to the processor, and - we use the term “platform” to refer to the combination - of architecture and operating system.</para> - - <para>There are two distinct porting scenarios:</para> - - <itemizedlist> - <listitem> - <para>Your platform is already supported, but you want to - compile up GHC using just a C compiler. This is a - straightforward bootstrap from HC files, and is described in - <xref linkend="sec-booting-from-hc" />.</para> - </listitem> - - <listitem> - <para>Your platform isn't supported by GHC. You will need to - do an <emphasis>unregisterised bootstrap</emphasis>, proceed - to <xref linkend="unregisterised-porting"/>.</para> - </listitem> - </itemizedlist> - - <sect2 id="sec-booting-from-hc"> - <title>Booting/porting from C (<filename>.hc</filename>) files</title> - - <indexterm><primary>building GHC from .hc files</primary></indexterm> - <indexterm><primary>booting GHC from .hc files</primary></indexterm> - <indexterm><primary>porting GHC</primary></indexterm> - - <para>Bootstrapping GHC on a system without GHC already - installed is achieved by taking the intermediate C files (known - as HC files) from 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 <emphasis>the same platform</emphasis>. - There may be some supplied on the GHC download page, otherwise - you'll have to compile some up yourself.</para> - - <para>The following steps should result in a working GHC build - with full libraries:</para> - - <itemizedlist> - <listitem> - <para>Make a set of HC files. On an identical system with - GHC already installed, get a GHC source tree and put the - following in <literal>mk/build.mk</literal>:</para> - -<programlisting> -SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files -GhcLibHcOpts = -O -GhcLibWays = -SplitObjs = NO -</programlisting> - - <para>Build GHC as normal, and then <literal>make - hc-file-bundle Project=ghc</literal> to creates the tar file - containing the hc files.</para> - </listitem> - - <listitem> - <para>On the target system, unpack the HC files on top of a - fresh source tree (make sure the source tree version matches - the version of the HC files <emphasis>exactly</emphasis>!). - This will place matching <filename>.hc</filename> files next - to the corresponding Haskell source - (<filename>.hs</filename> or <filename>.lhs</filename>) in - the compiler subdirectory <filename>ghc/compiler</filename> - and in the libraries (subdirectories of - <literal>libraries</literal>).</para> - </listitem> - - <listitem> - <para>The actual build process is fully automated by the - <filename>hc-build</filename> script located in the - <filename>distrib</filename> directory. If you eventually - want to install GHC into the directory - <replaceable>dir</replaceable>, the following - command will execute the whole build process (it won't - install yet):</para> - -<screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen> -<indexterm><primary>--hc-build</primary></indexterm> - - <para>By default, the installation directory is - <filename>/usr/local</filename>. If that is what you want, - you may omit the argument to <filename>hc-build</filename>. - Generally, any option given to <filename>hc-build</filename> - is passed through to the configuration script - <filename>configure</filename>. If - <filename>hc-build</filename> successfully completes the - build process, you can install the resulting system, as - normal, with</para> - -<screen>$ make install</screen> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="unregisterised-porting"> - <title>Porting GHC to a new platform</title> - - <para>The first step in porting to a new platform is to get an - <firstterm>unregisterised</firstterm> build working. An - unregisterised build is one that compiles via vanilla C only. - By contrast, a registerised build uses the following - architecture-specific hacks for speed:</para> - - <itemizedlist> - <listitem> - <para>Global register variables: certain abstract machine - <quote>registers</quote> are mapped to real machine - registers, depending on how many machine registers are - available (see - <filename>ghc/includes/MachRegs.h</filename>).</para> - </listitem> - - <listitem> - <para>Assembly-mangling: when compiling via C, we feed the - assembly generated by gcc though a Perl script known as the - <firstterm>mangler</firstterm> (see - <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The - mangler rearranges the assembly to support tail-calls and - various other optimisations.</para> - </listitem> - </itemizedlist> - - <para>In an unregisterised build, neither of these hacks are - used — the idea is that the C code generated by the - compiler should compile using gcc only. The lack of these - optimisations costs about a factor of two in performance, but - since unregisterised compilation is usually just a step on the - way to a full registerised port, we don't mind too much.</para> - - <para>You should go through this process even if your - architecture is already has registerised support in GHC, but - your OS currently isn't supported. In this case you probably - won't need to port any of the architecture-specific parts of the - code, and you can proceed straight from the unregisterised build - to build a registerised compiler.</para> - - <para>Notes on GHC portability in general: we've tried to stick - to writing portable code in most parts of the system, so it - should compile on any POSIXish system with gcc, but in our - experience most systems differ from the standards in one way or - another. Deal with any problems as they arise - if you get - stuck, ask the experts on - <email>glasgow-haskell-users@haskell.org</email>.</para> - - <para>Lots of useful information about the innards of GHC is - available in the <ulink - url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC - Commentary</ulink>, which might be helpful if you run into some - code which needs tweaking for your system.</para> - - <sect3> - <title>Cross-compiling to produce an unregisterised GHC</title> - - <para>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 - 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.ac</filename> to recognise the new - platform, and re-generate - <filename>configure</filename> with - <literal>autoreconf</literal>.</para> - </listitem> - - <listitem> -<screen>$ cd <replaceable>T</replaceable>/includes -$ make</screen> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>On the host machine:</para> - - <itemizedlist> - <listitem> - <para>Unpack a source tree (same released version). Call - this directory <replaceable>H</replaceable>.</para> - </listitem> - - <listitem> -<screen>$ cd <replaceable>H</replaceable> -$ ./configure</screen> - </listitem> - - <listitem> - <para>Create - <filename><replaceable>H</replaceable>/mk/build.mk</filename>, - with the following contents:</para> - -<programlisting>GhcUnregisterised = YES -GhcLibHcOpts = -O -fvia-C -keep-hc-files -GhcRtsHcOpts = -keep-hc-files -GhcLibWays = -SplitObjs = NO -GhcWithNativeCodeGen = NO -GhcWithInterpreter = NO -GhcStage1HcOpts = -O -GhcStage2HcOpts = -O -fvia-C -keep-hc-files -SRC_HC_OPTS += -H32m -GhcBootLibs = YES -GhcWithSMP = NO</programlisting> - </listitem> - - <listitem> - <para>Edit - <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para> - <itemizedlist> - <listitem> - <para>change <literal>TARGETPLATFORM</literal> - appropriately, and set the variables involving - <literal>TARGET</literal> or - <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>/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/includes/GHCConstants.h</filename> - to - <filename><replaceable>H</replaceable>/includes</filename>. - Note that we are building on the host machine, using the - target machine's configuration files. This - is so that the intermediate C files generated here will - be suitable for compiling on the target system.</para> - </listitem> - - <listitem> - <para>Touch the generated configuration files, just to make - sure they don't get replaced during the build:</para> -<screen>$ cd <filename><replaceable>H</replaceable></filename>/includes -$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c -$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen> - </listitem> - - <listitem> - <para>Now build the compiler:</para> -<screen>$ cd <replaceable>H</replaceable>/utils/mkdependC && make boot && make -$ cd <replaceable>H</replaceable>/includes && make boot && make -$ cd <replaceable>H</replaceable>/compat && make boot && make -$ cd <replaceable>H</replaceable>/utils && make boot && make -$ cd <replaceable>H</replaceable>/compiler && make boot && make -$ cd <replaceable>H</replaceable>/rts && 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>/compiler -$ make boot stage=2 && make stage=2</screen> - </listitem> - - <listitem> -<screen>$ cd <replaceable>H</replaceable>/compat -$ make clean -$ rm .depend -$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' -$ cd <replaceable>H</replaceable>/utils -$ make clean -$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen> - </listitem> - - <listitem> -<screen>$ cd <replaceable>H</replaceable> -$ make hc-file-bundle Project=Ghc</screen> - </listitem> - - <listitem> - <para>copy - <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename> - to <filename><replaceable>T</replaceable>/..</filename>.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>On the target machine:</para> - - <para>At this stage we simply need to bootstrap a compiler - from the intermediate C files we generated above. The - process of bootstrapping from C files is automated by the - script in <literal>distrib/hc-build</literal>, and is - described in <xref linkend="sec-booting-from-hc"/>.</para> - -<screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen> - - <para>However, since this is a bootstrap on a new machine, - the automated process might not run to completion the - first time. For that reason, you might want to treat the - <literal>hc-build</literal> script as a list of - instructions to follow, rather than as a fully automated - script. This way you'll be able to restart the process - part-way through if you need to fix anything on the - way.</para> - - <para>Don't bother with running - <literal>make install</literal> in the newly - bootstrapped tree; just use the compiler in that tree to - build a fresh compiler from scratch, this time without - booting from C files. Before doing this, you might want - to check that the bootstrapped compiler is generating - working binaries:</para> - -<screen>$ cat >hello.hs -main = putStrLn "Hello World!\n" -^D -$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello -$ ./hello -Hello World!</screen> - - <para>Once you have the unregisterised compiler up and - running, you can use it to start a registerised port. The - following sections describe the various parts of the - system that will need architecture-specific tweaks in - order to get a registerised build going.</para> - - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Porting the RTS</title> - - <para>The following files need architecture-specific code for a - registerised build:</para> - - <variablelist> - <varlistentry> - <term><filename>ghc/includes/MachRegs.h</filename> - <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm> - </term> - <listitem> - <para>Defines the STG-register to machine-register - mapping. You need to know your platform's C calling - convention, and which registers are generally available - for mapping to global register variables. There are - plenty of useful comments in this file.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ghc/includes/TailCalls.h</filename> - <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm> - </term> - <listitem> - <para>Macros that cooperate with the mangler (see <xref - linkend="sec-mangler"/>) to make proper tail-calls - work.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ghc/rts/Adjustor.c</filename> - <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm> - </term> - <listitem> - <para>Support for - <literal>foreign import "wrapper"</literal> - (aka - <literal>foreign export dynamic</literal>). - Not essential for getting GHC bootstrapped, so this file - can be deferred until later if necessary.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ghc/rts/StgCRun.c</filename> - <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm> - </term> - <listitem> - <para>The little assembly layer between the C world and - the Haskell world. See the comments and code for the - other architectures in this file for pointers.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ghc/rts/MBlock.h</filename> - <indexterm><primary><filename>MBlock.h</filename></primary></indexterm> - </term> - <term><filename>ghc/rts/MBlock.c</filename> - <indexterm><primary><filename>MBlock.c</filename></primary></indexterm> - </term> - <listitem> - <para>These files are really OS-specific rather than - architecture-specific. In <filename>MBlock.h</filename> - is specified the absolute location at which the RTS - should try to allocate memory on your platform (try to - find an area which doesn't conflict with code or dynamic - libraries). In <filename>Mblock.c</filename> you might - need to tweak the call to <literal>mmap()</literal> for - your OS.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3 id="sec-mangler"> - <title>The mangler</title> - - <para>The mangler is an evil Perl-script - (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that - rearranges the assembly code output from gcc to do two main - things:</para> - - <itemizedlist> - <listitem> - <para>Remove function prologues and epilogues, and all - movement of the C stack pointer. This is to support - tail-calls: every code block in Haskell code ends in an - explicit jump, so we don't want the C-stack overflowing - while we're jumping around between code blocks.</para> - </listitem> - <listitem> - <para>Move the <firstterm>info table</firstterm> for a - closure next to the entry code for that closure. In - unregisterised code, info tables contain a pointer to the - entry code, but in registerised compilation we arrange - that the info table is shoved right up against the entry - code, and addressed backwards from the entry code pointer - (this saves a word in the info table and an extra - indirection when jumping to the closure entry - code).</para> - </listitem> - </itemizedlist> - - <para>The mangler is abstracted to a certain extent over some - architecture-specific things such as the particular assembler - directives used to herald symbols. Take a look at the - definitions for other architectures and use these as a - starting point.</para> - </sect3> - - <sect3> - <title>The splitter</title> - - <para>The splitter is another evil Perl script - (<filename>ghc/driver/split/ghc-split.lprl</filename>). It - cooperates with the mangler to support object splitting. - Object splitting is what happens when the - <option>-split-objs</option> option is passed to GHC: the - object file is split into many smaller objects. This feature - is used when building libraries, so that a program statically - linked against the library will pull in less of the - library.</para> - - <para>The splitter has some platform-specific stuff; take a - look and tweak it for your system.</para> - </sect3> - - <sect3> - <title>The native code generator</title> - - <para>The native code generator isn't essential to getting a - registerised build going, but it's a desirable thing to have - because it can cut compilation times in half. The native code - generator is described in some detail in the <ulink - url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC - commentary</ulink>.</para> - </sect3> - - <sect3> - <title>GHCi</title> - - <para>To support GHCi, you need to port the dynamic linker - (<filename>$(GHC_TOP)/rts/Linker.c</filename>). The - linker currently supports the ELF and PEi386 object file - formats - if 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 and/or OS 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> - </sect3> - </sect2> - - </sect1> - -<sect1 id="sec-build-pitfalls"> -<title>Known pitfalls in building Glasgow Haskell - -<indexterm><primary>problems, building</primary></indexterm> -<indexterm><primary>pitfalls, in building</primary></indexterm> -<indexterm><primary>building pitfalls</primary></indexterm></title> - -<para> -WARNINGS about pitfalls and known “problems”: -</para> - -<para> - -<orderedlist> -<listitem> - -<para> -One difficulty that comes up from time to time is running out of space -in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to -compensate for the vagaries of different sysadmin approaches to temp -space.) -<indexterm><primary>tmp, running out of space in</primary></indexterm> - -The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or -even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell -of choice). - -The best way around it is to say - -<programlisting>export TMPDIR=<dir></programlisting> - -in your <filename>build.mk</filename> file. Then GHC and the other -tools will use the appropriate directory in all cases. - - -</para> -</listitem> -<listitem> - -<para> -In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even -in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these -are OK. - -</para> -</listitem> -<listitem> - -<para> -When compiling via C, you'll sometimes get “warning: assignment from -incompatible pointer type” out of GCC. Harmless. - -</para> -</listitem> -<listitem> - -<para> -Similarly, <command>ar</command>chiving warning messages like the following are not -a problem: - -<screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ -ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ -...</screen> - - -</para> -</listitem> -<listitem> - -<para> - In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis> -get an “Out of heap space” error message. These can vary with the -vagaries of different systems, it seems. The solution is simple: - - -<itemizedlist> -<listitem> - -<para> - If you're compiling with GHC 4.00 or later, then the -<emphasis>maximum</emphasis> heap size must have been reached. This -is somewhat unlikely, since the maximum is set to 64M by default. -Anyway, you can raise it with the -<option>-optCrts-M<size></option> flag (add this flag to -<constant><module>_HC_OPTS</constant> -<command>make</command> variable in the appropriate -<filename>Makefile</filename>). - -</para> -</listitem> -<listitem> - -<para> - For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as -above. - -</para> -</listitem> - -</itemizedlist> - - -and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about -<constant><module>_HC_OPTS</constant>.) - -Alternatively, just cut to the chase: - -<screen>$ cd ghc/compiler -$ make EXTRA_HC_OPTS=-optCrts-M128M</screen> - - -</para> -</listitem> -<listitem> - -<para> -If you try to compile some Haskell, and you get errors from GCC about -lots of things from <filename>/usr/include/math.h</filename>, then your GCC was -mis-installed. <command>fixincludes</command> wasn't run when it should've been. - -As <command>fixincludes</command> is now automagically run as part of GCC installation, -this bug also suggests that you have an old GCC. - - -</para> -</listitem> -<listitem> - -<para> -You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s). - - -<screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 -$ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... -? ranlib $i -? # or, on some machines: ar s $i -? end</screen> - - -We'd be interested to know if this is still necessary. - - -</para> -</listitem> -<listitem> - -<para> -GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies -a bit from one Unix to another. One particular gotcha is macro calls -like this: - - -<programlisting>SLIT("Hello, world")</programlisting> - - -Some <command>cpp</command>s treat the comma inside the string as separating two macro -arguments, so you get - - -<screen>:731: macro `SLIT' used with too many (2) args</screen> - - -Alas, <command>cpp</command> doesn't tell you the offending file! - -Workaround: don't put weird things in string args to <command>cpp</command> macros. -</para> -</listitem> - -</orderedlist> - -</para> - -</sect1> - - -<sect1 id="platforms"><title>Platforms, scripts, and file names</title> -<para> -GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility -gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter. -</para> - -<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title> - -<para> The build system is built around Unix-y makefiles. Because it's not native, -the Windows situation for building GHC is particularly confusing. This section -tries to clarify, and to establish terminology.</para> - -<sect3 id="ghc-mingw"><title>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 down-side of MinGW is that the MinGW libraries do not support anything like the full -Posix interface. -</para> -</sect3> - -<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title> - -<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell, -or the standard Unix commands such as <command>mv</command>, <command>rm</command>, -<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>. -For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink> -and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>: - -<itemizedlist> -<listitem><para> -Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which -compile code that has access to all of Posix. The price is that the executables must be -dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine -that doesn't have Cygwin</emphasis>. 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. </para> -</listitem> - -<listitem><para> -MSYS is a fork of the Cygwin tree, so they -are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes -through fewer layers, so MSYS is quite a bit faster too. -</para> - -<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These -compile binaries that run with no DLL support, on any Win32 system. -However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>, -<command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the -MsysDTK (Developer Tool Kit) package, as well as the base MSYS package. -</para> -<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>, -<command>ssh</command> and so on), -not by programs compiled under MSYS. -</para></listitem> - -</itemizedlist> - -</para> -</sect3> - -<sect3><title>Targeting MinGW</title> - -<para>We want GHC to compile programs that work on any Win32 system. Hence: -<itemizedlist> -<listitem><para> -GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only -invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles -will work on any system, but it also means that the programs GHC compiles do not have access -to all of Posix. In particular, they cannot import the (Haskell) Posix -library; they have to do -their input output using standard Haskell I/O libraries, or native Win32 bindings.</para> -<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para> -</listitem> - -<listitem><para> -To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>, -<command>as</command>, <command>ld</command>, and a bunch of input/output libraries. -</para></listitem> -</itemizedlist> -So <emphasis>GHC targets MinGW</emphasis>, not Cygwin. -It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>, -that targets Cygwin instead. The up-side of GHC-cygwin is -that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library. -<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis> -</para> - -<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about -how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for -GHC; both work fine, though MSYS is rather lighter weight.</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 correct <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> - -<sect3><title> File names </title> - -<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>. -However: -<itemizedlist> -<listitem><para> -MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as -<filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution. -</para> -<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename> -directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line -arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example, -if you invoke -<programlisting>foogle -B/c/tmp/baz</programlisting> -the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>. -</para></listitem> - -<listitem><para> -Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>. -</para> -<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs. -</para></listitem> -</itemizedlist> -</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> -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> - -</sect2> - -<sect2><title>Wrapper scripts</title> - -<para> -Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries. -For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use -GHC itself as an example: -<itemizedlist> - <listitem> <para> - On Unix, the command <command>ghc</command> is a shell script, generated by adding installation - paths to the front of the source file <filename>ghc.sh</filename>, - that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command> - where to find its supporting files. - </para> </listitem> - - <listitem> <para> - On vanilla Windows, it turns out to be much harder to make reliable script to be run by the - native Windows shell <command>cmd</command> (e.g. limits on the length - of the command line). So instead we invoke the GHC binary directly, with no -B flag. - GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is, - and from that figures out where the supporting files are. - </para> </listitem> -</itemizedlist> -(You can find the layout of GHC's supporting files in the - section "Layout of installed files" of Section 2 of the GHC user guide.) -</para> -<para> -Things work differently for <emphasis>in-place</emphasis> execution, where you want to -execute a program that has just been built in a build tree. The difference is that the -layout of the supporting files is different. -In this case, whether on Windows or Unix, we always use a shell script. This works OK -on Windows because the script is executed by MSYS or Cygwin, which don't have the -shortcomings of the native Windows <command>cmd</command> shell. -</para> - -</sect2> - -</sect1> - -<sect1 id="winbuild"><title>Instructions for building under Windows</title> - -<para> -This section gives detailed instructions for how to build -GHC from source on your Windows machine. Similar instructions for -installing and running GHC may be found in the user guide. In general, -Win95/Win98 behave the same, and WinNT/Win2k behave the same. -</para> -<para> -Make sure you read the preceding section on platforms (<xref linkend="platforms"/>) -before reading section. -You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC, -but you do need one or the other to <emphasis>build</emphasis> GHC.</para> - - -<sect2 id="msys-install"><title>Installing and configuring MSYS</title> - -<para> -MSYS is a lightweight alternative to Cygwin. -You don't need MSYS to <emphasis>use</emphasis> GHC, -but you do need it or Cygwin to <emphasis>build</emphasis> GHC. -Here's how to install MSYS. -<itemizedlist> -<listitem><para> -Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and -download the following (of course, the version numbers will differ): -<itemizedlist> - <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal> - </para></listitem> - <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>. - This provides <command>make</command>, <command>autoconf</command>, - <command>ssh</command> and probably more besides. - </para></listitem> -</itemizedlist> -Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal> -</para></listitem> - -<listitem><para> -Set the following environment variables -<itemizedlist> - <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>). - This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory. - </para></listitem> - - <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal> - </para></listitem> - - <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if - you are using CVS. - </para></listitem> - - <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.) - </para></listitem> - -</itemizedlist> -</para></listitem> - -<listitem><para> -Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug -that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it -causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename> -file has too-liberal permissinos. -</para></listitem> - -</itemizedlist> -</para> -<para>Here are some points to bear in mind when using MSYS: -<itemizedlist> -<listitem> <para> MSYS does some kind of special magic to binaries stored in -<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped -to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>). -Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories: -they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>, -which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem> - -<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost. -</para></listitem> - -<listitem> <para> -Win32 has a <command>find</command> command which is not the same as MSYS's find. -You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant> -before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> -environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> -variable. You can always invoke <command>find</command> with an absolute path, or rename it. -</para></listitem> - -<listitem> <para> -MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal> -will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a -bzip'd dump.</para></listitem> - -</itemizedlist> -</para> -</sect2> - -<sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title> - -<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>.</para> -<para> -You must install enough Cygwin <emphasis>packages</emphasis> to support -building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this: -<itemizedlist> -<listitem><para>The direct, but laborious way is to -select all of the following packages in the installation dialogue: - <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>. -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> -</listitem> - -<listitem><para>The clever way is to point the Cygwin installer at the -<command>ghc-depends</command> package, which is kept at <ulink -url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>. -When the Cygwin installer asks you to "Choose a Download Site", choose one of -the -offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the -"User URL" box and click "Add"; now two sites are selected. (The Cygwin -installer remembers this for next time.) -Click "Next".</para> -<para>In the "Select Packages" dialogue box that follows, click the "+" sign by -"Devel", scroll down to the end of the "Devel" packages, and choose -<command>ghc-depends</command>. -The package <command>ghc-depends</command> will not actually install anything itself, -but forces additional packages to be added by the Cygwin installer. -</para> -</listitem> -</itemizedlist> -</para> - -<para> Now set the following user environment variables: -<itemizedlist> - -<listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your -<constant>PATH</constant></para></listitem> - -<listitem> -<para> -Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you -don't do this you get very weird messages when you type -<command>make</command>, such as: -<screen>/c: /c: No such file or directory</screen> -</para> -</listitem> - -<listitem><para> Set <constant>SHELL</constant> to -<filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this -<constant>SHELL</constant> is what you get. -</para></listitem> - -<listitem><para> Set <constant>HOME</constant> to point to your -home directory. This is where, for example, -<command>bash</command> will look for your <filename>.bashrc</filename> -file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename> -</para></listitem> -</itemizedlist> -</para> - -<para>Here are some things to be aware of when using Cygwin: -<itemizedlist> -<listitem> <para>Cygwin doesn't deal well with filenames that include -spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are -common gotchas. -</para></listitem> - -<listitem> <para> Cygwin implements a symbolic link as a text file with some -magical text in it. So other programs that don't use Cygwin's -I/O libraries won't recognise such files as symlinks. -In particular, programs compiled by GHC are meant to be runnable -without having Cygwin, so they don't use the Cygwin library, so -they don't recognise symlinks. -</para></listitem> - -<listitem> <para> -See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>, -which apply to Cygwin too. -</para></listitem> - -<listitem> -<para> -Some script files used in the make system start with "<command>#!/bin/perl</command>", -(and similarly for <command>sh</command>). Notice the hardwired path! -So you need to ensure that your <filename>/bin</filename> directory has at least -<command>sh</command>, <command>perl</command>, and <command>cat</command> in it. -All these come in Cygwin's <filename>bin</filename> directory, which you probably have -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>.) -Provided <filename>/bin</filename> points to the Cygwin <filename>bin</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> - -<listitem> -<para> -By default, cygwin provides the command shell <filename>ash</filename> -as <filename>sh.exe</filename>. It seems to be fine now, but in the past we -saw build-system problems that turned 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. -If this happens to you (which it shouldn't), 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> -</itemizedlist> -</para> - -</sect2> - - -<sect2 id="configure-ssh"><title>Configuring SSH</title> - -<para><command>ssh</command> comes with both Cygwin and MSYS. -(Cygwin note: you need to ask for package <command>openssh</command> (not ssh) -in the Cygwin list of packages; or use the <command>ghc-depends</command> -package -- see <xref linkend="install-cygwin"/>.)</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> (Cygwin-only problem, I think.) -<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 -<screen>ssh -v cvs.haskell.org</screen> -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, listed below.</para> - -<para>On Windows you often install executables in directories with spaces, such as -"<filename>Program Files</filename>". However, the <literal>make</literal> system doesn't -deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised -to put binaries for all tools in places with no spaces in their path. -On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places, -<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter, -provided they are in your path. -<itemizedlist> -<listitem> -<para> -Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>. -This is what you will use to compile GHC. Add it in your -<constant>PATH</constant>: the installer tells you the path element -you need to add upon completion. -</para> -</listitem> - -<listitem> -<para> -Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>. -Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily -build it from the source distribution using -<screen>$ ./configure -$ make -$ make install</screen> -This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename> -on MSYS). -Make sure the installation directory is in your -<constant>PATH</constant>. -</para> -</listitem> - - <listitem> - <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> - </listitem> - -<listitem> -<para>GHC uses the <emphasis>mingw</emphasis> C compiler to -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><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. -On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command> -(and perhaps one or two other things) in your path. The Cygwin ones are fine, -but you must have them; hence needing the Cygwin binutils package. -</para> -</listitem> - - -<listitem> -<para>We use <command>emacs</command> a lot, so we install that too. -When you are in <filename>$(GHC_TOP)/compiler</filename>, you can use -"<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility -<filename>$(GHC_TOP)/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>$(GHC_TOP)/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>You might want to install GLUT in your MSYS/Cygwin - installation, otherwise the GLUT package will not be built with - GHC.</para> - </listitem> - -<listitem> -<para> Finally, check out a copy of GHC sources from -the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para> -</listitem> -</itemizedlist> -</para> -</sect2> - -<sect2><title>Building GHC</title> - -<para>OK! -Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>); -the bullets below only tell -you about Windows-specific wrinkles.</para> -<itemizedlist> -<listitem> -<para> -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 -mk/config.h is unchanged -configuring in ghc -running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. -./configure: ./configure: No such file or directory -configure: error: ./configure failed for ghc</screen> -</para> -</listitem> - -<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</screen> -Solution: delete <filename>configure</filename> first. -</para></listitem> - -<listitem> - <para> - After <command>autoreconf</command> run <command>./configure</command> in - <filename>$(GHC_TOP)/</filename> thus: - -<screen>$ ./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> - -<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: -<screen>make[4]: Leaving directory `/cygdrive/e/ghc-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/ghc-stage1/ghc' -make: *** [all] Error 1</screen> -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> -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> 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> -</itemizedlist> -</sect2> - - -<sect2><title>A Windows build log using Cygwin</title> - -<para>Here is a complete, from-scratch, log of all you need to build GHC using -Cygwin, kindly provided by Claus Reinke. It does not discuss alternative -choices, but it gives a single path that works.</para> -<programlisting>- Install some editor (vim, emacs, whatever) - -- Install cygwin (http://www.cygwin.com) - ; i used 1.5.16-1, installed in c:\cygwin - - run 'setup.exe' - Choose a Download Source: - select 'download from internet'; - Select Root Install Directory: - root dir: c:\cygwin; - install for: all users; - default file type: unix - Select Local Package Directory - choose a spare temporary home - Select Your Internet Connection - Use IE5 settings - Choose a Download Site - Choose your preferred main mirror and - Add 'http://www.haskell.org/ghc/cygwin' - Select Packages - In addition to 'Base' (default install), - select 'Devel->ghc-depends' - -- Install mingw (http://www.mingw.org/) - ; i used MinGW-3.1.0-1.exe - ; installed in c:\mingw - - you probably want to add GLUT - ; (http://www.xmission.com/~nate/glut.html) - ; i used glut-3.7.3-mingw32.tar - -- Get recent binary snapshot of ghc-6.4.1 for mingw - ; (http://www.haskell.org/ghc/dist/stable/dist/) - - unpack in c:/ghc - - add C:\ghc\ghc-6.4.1\bin to %PATH% - (Start->Control Panel->System->Advanced->Environment Variables) - -- Get darcs version of ghc - ; also, subscribe to cvs-all@haskell.org, or follow the mailing list - ; archive, in case you checkout a version with problems - ; http://www.haskell.org//pipermail/cvs-all/ - - mkdir c:/ghc-build; cd c:/ghc-build - ; (or whereever you want your darcs tree to be) - - darcs get http://darcs.haskell.org/ghc - - cd ghc - - chmod +x darcs-all - - ./darcs-all get - -- Build ghc, using cygwin and mingw, targetting mingw - - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH - ; for haddock, alex, happy (*) - - export PATH=/cygdrive/c/mingw/bin:$PATH - ; without, we pick up some cygwin tools at best! - - cd c:/ghc-build - ; (if you aren't there already) - - autoreconf - - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe - ; we use cygwin, but build for windows - - cp mk/build.mk.sample mk/build.mk - - in mk/build.mk: - add line: SplitObjs = NO - (MSYS seems slow when there are zillions of object files) - uncomment line: BuildFlavour = perf - (or BuildFlavour = devel, if you are doing development) - add line: BIN_DIST=1 - - make 2>&1 | tee make.log - ; always useful to have a log around - -- Package up binary distribution - - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log - ; always useful to have a log around - - cd ghc-6.5 - - chmod +x ../distrib/prep-bin-dist-mingw - ; if you're happy with the script's contents (*) - - ../distrib/prep-bin-dist-mingw - ; then tar up, unpack where wanted, and enjoy</programlisting> -</sect2> -</sect1> - -<index/> - -</article> diff --git a/docs/index.html b/docs/index.html index 204e20a378..cadd6f5df0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -44,13 +44,13 @@ <P>An infrastructure for building and distributing Haskell software.</P> </LI> - - <LI> - <P> - <B><A HREF="building/index.html">Building Guide</A></B> - </P> - <P>Information on buiding GHC from source, and porting GHC to a new platform.</P> - </LI> </UL> + + <P>For more information, see the following:</p> + <ul> + <li><p><a href="http://www.haskell.org/ghc">GHC Home Page</a></p></li> + <li><p><a href="http://hackage.haskell.org/trac/ghc/"> + GHC Developers Home</a></p></li> + </ul> </BODY> </HTML> diff --git a/docs/users_guide/installing.xml b/docs/users_guide/installing.xml index 9f8e4c9eb8..9b1a1e128d 100644 --- a/docs/users_guide/installing.xml +++ b/docs/users_guide/installing.xml @@ -92,7 +92,7 @@ having a Haskell compiler.) <para> Binary distributions come in “bundles,” one bundle per file called -<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: +<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>. (See the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink> for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: </para> <para> @@ -378,7 +378,7 @@ stuff in your bin directory. option, so you can see exactly what pathnames it's using. If things don't work as expected, check the list of known pitfalls in -the building guide. +the <ulink url="http://hackage.haskell.org/trac/ghc/wiki/Building">building guide</ulink>. </para> </listitem> diff --git a/ghc.spec.in b/ghc.spec.in index 2f66261abf..0d714b70e1 100644 --- a/ghc.spec.in +++ b/ghc.spec.in @@ -119,8 +119,11 @@ rm -rf ${RPM_BUILD_ROOT} %doc ANNOUNCE %doc LICENSE %doc README +v v v v v v v +************* %doc docs/building/building %doc docs/comm +^ ^ ^ ^ ^ ^ ^ %doc docs/ext-core/core.ps %doc docs/storage-mgt/ldv.ps %doc docs/storage-mgt/rp.ps |