1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY hacking SYSTEM "../../HACKING">
7 <article id="building-guide">
11 <title>Building and developing GHC</title>
12 <author><othername>The GHC Team</othername></author>
13 <address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address>
16 <para>This Guide is primarily aimed at those who want to build and/or
17 hack on GHC. It describes how to get started with building GHC on your
18 machine, and how to tweak the settings to get the kind of build you
19 want. It also describes the inner workings of the build system, so you
20 can extend it, modify it, and use it to build your code.</para>
22 <para>The bulk of this guide applies to building on Unix
23 systems; see <xref linkend="winbuild"/> for Windows notes.</para>
29 <sect1 id="sec-getting">
30 <title>Getting the sources</title>
32 <para>You can get your hands on the GHC sources in two ways:</para>
37 <term><indexterm><primary>Source
38 distributions</primary></indexterm>Source distributions</term>
40 <para>You have a supported platform, but (a) you like
41 the warm fuzzy feeling of compiling things yourself;
42 (b) you want to build something ``extra”—e.g., a
43 set of libraries with strictness-analysis turned off; or
44 (c) you want to hack on GHC yourself.</para>
46 <para>A source distribution contains complete sources for
47 GHC. Not only that, but the more awkward
48 machine-independent steps are done for you. For example, if
50 <command>happy</command><indexterm><primary>happy</primary></indexterm>
51 you'll find it convenient that the source distribution
52 contains the result of running <command>happy</command> on
53 the parser specifications. If you don't want to alter the
54 parser then this saves you having to find and install
55 <command>happy</command>. You will still need a working
56 version of GHC (version 5.x or later) on your machine in
57 order to compile (most of) the sources, however.</para>
62 <term>The darcs repository.<indexterm><primary>darcs repository</primary></indexterm></term>
64 <para>We make releases infrequently. If you want more
65 up-to-the minute (but less tested) source code then you need
66 to get access to our darcs repository.</para>
68 <para>Information on accessing the darcs repository is on
70 url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs"
73 <para>The repository holds source code only. It holds no
74 mechanically generated files at all. So if you check out a
75 source tree from darcs you will need to install every utility
76 so that you can build all the derived files from
83 <sect1 id="sec-build-checks">
84 <title>Things to check before you start</title>
86 <para>Here's a list of things to check before you get
91 <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
92 space needed: from about 100Mb for a basic GHC
93 build, up to probably 500Mb for a GHC build with everything
94 included (libraries built several different ways,
99 <para>Use an appropriate machine / operating system. <ulink
100 url="http://hackage.haskell.org/trac/ghc/wiki/Platforms">GHC
101 Platform Support</ulink> lists the currently supported
102 platforms; if yours isn't amongst these then you can try
103 porting GHC (see <xref linkend="sec-porting-ghc"/>).</para>
107 <para>Be sure that the “pre-supposed” utilities are
108 installed. <xref linkend="sec-pre-supposed"/>
113 <para>If you have any problem when building or installing the
114 Glasgow tools, please check the “known pitfalls” (<xref
115 linkend="sec-build-pitfalls"/>). Also check the FAQ for the
116 version you're building, which is part of the User's Guide and
117 available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
120 <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
122 <para>If you feel there is still some shortcoming in our
123 procedure or instructions, please report it.</para>
125 <para>For GHC, please see the <ulink
126 url="http://www.haskell.org/ghc/docs/latest/set/bug-reporting.html">bug-reporting
127 section of the GHC Users' Guide</ulink>, to maximise the
128 usefulness of your report.</para>
130 <indexterm><primary>bugs</primary><secondary>seporting</secondary></indexterm>
131 <para>If in doubt, please send a message to
132 <email>glasgow-haskell-bugs@haskell.org</email>.
133 <indexterm><primary>bugs</primary><secondary>mailing
134 list</secondary></indexterm></para>
139 <sect1 id="sec-pre-supposed">
140 <title>Installing pre-supposed utilities</title>
142 <indexterm><primary>pre-supposed utilities</primary></indexterm>
143 <indexterm><primary>utilities, pre-supposed</primary></indexterm>
145 <para>Here are the gory details about some utility programs you
146 may need; <command>perl</command>, <command>gcc</command> and
147 <command>happy</command> are the only important
148 ones. (PVM<indexterm><primary>PVM</primary></indexterm> is
149 important if you're going for Parallel Haskell.) The
150 <command>configure</command><indexterm><primary>configure</primary></indexterm>
151 script will tell you if you are missing something.</para>
157 <indexterm><primary>pre-supposed: GHC</primary></indexterm>
158 <indexterm><primary>GHC, pre-supposed</primary></indexterm>
161 <para>GHC is required to build GHC, because GHC itself is
162 written in Haskell, and uses GHC extensions. It is possible
163 to build GHC using just a C compiler, and indeed some
164 distributions of GHC do just that, but it isn't the best
165 supported method, and you may encounter difficulties. Full
166 instructions are in <xref linkend="sec-porting-ghc"/>.</para>
168 <para>GHC can be built using either an earlier released
169 version of GHC (currently 5.04 and later are supported), or
170 bootstrapped using a GHC built from exactly the same
171 sources. Note that this means you cannot in general build
172 GHC using an arbitrary development snapshot, or a build from
173 say last week. It might work, it might not - we don't
174 guarantee anything. To be on the safe side, start your
175 build using the most recently released stable version of
182 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
183 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
186 <para><emphasis>You have to have Perl to proceed!</emphasis>
187 Perl version 5 at least is required. GHC has been known to
188 tickle bugs in Perl, so if you find that Perl crashes when
189 running GHC try updating (or downgrading) your Perl
190 installation. Versions of Perl before 5.6 have been known to have
191 various bugs tickled by GHC, so the configure script
192 will look for version 5.6 or later.</para>
194 <para>For Win32 platforms, you should use the binary
195 supplied in the InstallShield (copy it to
196 <filename>/bin</filename>). The Cygwin-supplied Perl seems
199 <para>Perl should be put somewhere so that it can be invoked
200 by the <literal>#!</literal> script-invoking
201 mechanism. The full pathname may need to be less than 32
202 characters long on some systems.</para>
207 <term>GNU C (<command>gcc</command>)
208 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
209 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
212 <para>Most GCC versions should work with the most recent GHC
213 sources. Expect trouble if you use a recent GCC with
214 an older GHC, though (trouble in the form of mis-compiled code,
215 link errors, and errors from the <literal>ghc-asm</literal>
218 <para>If your GCC dies with “internal error” on
219 some GHC source file, please let us know, so we can report
220 it and get things improved. (Exception: on x86
221 boxes—you may need to fiddle with GHC's
222 <option>-monly-N-regs</option> option; see the User's
229 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
232 <para>The GHC build system makes heavy use of features
233 specific to GNU <command>make</command>, so you must have
234 this installed in order to build GHC.</para>
236 <para>NB. it has been reported that version 3.79 no longer
237 works to build GHC, and 3.80 is required.</para>
242 <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
243 <indexterm><primary>Happy</primary></indexterm>
246 <para>Happy is a parser generator tool for Haskell, and is
247 used to generate GHC's parsers.</para>
249 <para>If you start from a source tarball of GHC (i.e. not a darcs
250 checkout), then you don't need Happy, because we supply the
251 pre-processed versions of the Happy parsers. If you intend to
252 modify the compiler and/or you're using a darcs checkout, then you
255 <para>Happy version 1.15 is currently required to build GHC.
256 Grab a copy from <ulink
257 url="http://www.haskell.org/happy/">Happy's Web
264 <indexterm><primary>Alex</primary></indexterm>
267 <para>Alex is a lexical-analyser generator for Haskell,
268 which GHC uses to generate its lexer.</para>
270 <para>Like Happy, you don't need Alex if you're building GHC from a
271 source tarball, but you do need it if you're modifying GHC and/or
272 building a darcs checkout.</para>
275 written in Haskell and is a project in the darcs repository.
276 Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
283 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
284 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
287 <para>GNU autoconf is needed if you intend to build from the
288 darcs sources, it is <emphasis>not</emphasis> needed if you
289 just intend to build a standard source distribution.</para>
291 <para>Version 2.52 or later of the autoconf package is required.
292 NB. version 2.13 will no longer work, as of GHC version
295 <para><command>autoreconf</command> (from the autoconf package)
296 recursively builds <command>configure</command> scripts from
297 the corresponding <filename>configure.ac</filename> and
298 <filename>aclocal.m4</filename> files. If you modify one of
299 the latter files, you'll need <command>autoreconf</command> to
300 rebuild the corresponding <filename>configure</filename>.</para>
305 <term><command>sed</command>
306 <indexterm><primary>pre-supposed: sed</primary></indexterm>
307 <indexterm><primary>sed, pre-supposed</primary></indexterm>
310 <para>You need a working <command>sed</command> if you are
311 going to build from sources. The build-configuration stuff
312 needs it. GNU sed version 2.0.4 is no good! It has a bug
313 in it that is tickled by the build-configuration. 2.0.5 is
314 OK. Others are probably OK too (assuming we don't create too
315 elaborate configure scripts.)</para>
320 <sect2 id="pre-supposed-gph-tools">
321 <title>Tools for building parallel GHC (GPH)</title>
326 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
327 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
330 <para>PVM is the Parallel Virtual Machine on which
331 Parallel Haskell programs run. (You only need this if you
332 plan to run Parallel Haskell. Concurrent Haskell, which
333 runs concurrent threads on a uniprocessor doesn't need
334 it.) Underneath PVM, you can have (for example) a network
335 of workstations (slow) or a multiprocessor box
338 <para>The current version of PVM is 3.3.11; we use 3.3.7.
339 It is readily available on the net; I think I got it from
340 <literal>research.att.com</literal>, in
341 <filename>netlib</filename>.</para>
343 <para>A PVM installation is slightly quirky, but easy to
344 do. Just follow the <filename>Readme</filename>
350 <term><command>bash</command>:
351 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
354 <para>Sadly, the <command>gr2ps</command> script, used to
355 convert “parallelism profiles” to PostScript,
356 is written in Bash (GNU's Bourne Again shell). This bug
357 will be fixed (someday).</para>
362 <para>More tools are required if you want to format the
363 documentation that comes with GHC. See <xref
364 linkend="building-docs"/>.</para>
368 <sect1 id="sec-building-from-source">
369 <title>Building from source</title>
371 <indexterm><primary>Building from source</primary></indexterm>
372 <indexterm><primary>Source, building from</primary></indexterm>
374 <para>“I just want to build it!”</para>
376 <para>No problem. This recipe should build and install a working GHC with
377 all the default settings. (unless you're
378 on Windows, in which case go to <xref linkend="winbuild" />).</para>
380 <screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
384 $ make install</screen>
386 <para>For GHC, this will do a 2-stage bootstrap build of the
387 compiler, with profiling libraries, and install the
388 results in the default location (under <filename>/usr/local</filename> on
389 Unix, for example).</para>
391 <para>The <literal>configure</literal> script is a standard GNU
392 <literal>autoconf</literal> script, and accepts the usual options for
393 changing install locations and the like. Run
394 <literal>./configure --help</literal> for a list of options.</para>
396 <para>If you want to do anything at all non-standard, or you
397 want to do some development, read on...</para>
400 <sect1 id="quick-start">
401 <title>Quick start for GHC developers</title>
403 <para>This section is a copy of the file
404 <literal>HACKING</literal> from the GHC source tree. It describes
405 how to get started with setting up your build tree for developing GHC
406 or its libraries, and how to start building.</para>
413 <sect1 id="sec-working-with-the-build-system">
414 <title>Working with the build system</title>
416 <para>This rest of this guide is intended for duffers like me, who
417 aren't really interested in Makefiles and systems configurations,
418 but who need a mental model of the interlocking pieces so that
419 they can make them work, extend them consistently when adding new
420 software, and lay hands on them gently when they don't
424 <title>History</title>
426 <para>First, a historical note. The GHC build system used to be
427 called "fptools": a generic build system used to build multiple
428 projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a
429 concept of the generic project-independent parts, and
430 project-specific parts that resided in a project
433 <para>Nowadays, most of these other projects are using <ulink
434 url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded
435 away, and GHC is the only regular user of the fptools build
436 system. We decided therefore to simplify the situation for
437 developers, and specialise the build system for GHC. This
438 resulted in a simpler organisation of the source tree and the
439 build system, which hopefully makes the whole thing easier to
442 <para>You might find old comments that refer to "projects" or
443 "fptools" in the documentation and/or source; please let us know
448 <title>Build trees</title>
449 <indexterm><primary>build trees</primary></indexterm>
450 <indexterm><primary>link trees, for building</primary></indexterm>
452 <para>If you just want to build the software once on a single
453 platform, then your source tree can also be your build tree, and
454 you can skip the rest of this section.</para>
456 <para>We often want to build multiple versions of our software
457 for different architectures, or with different options
458 (e.g. profiling). It's very desirable to share a single copy of
459 the source code among all these builds.</para>
461 <para>So for every source tree we have zero or more
462 <emphasis>build trees</emphasis>. Each build tree is initially
463 an exact copy of the source tree, except that each file is a
464 symbolic link to the source file, rather than being a copy of
465 the source file. There are “standard” Unix
466 utilities that make such copies, so standard that they go by
468 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
469 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
470 are two (If you don't have either, the source distribution
471 includes sources for the X11
472 <command>lndir</command>—check out
473 <filename>utils/lndir</filename>). See <xref
474 linkend="sec-storysofar"/> for a typical invocation.</para>
476 <para>The build tree does not need to be anywhere near the
477 source tree in the file system. Indeed, one advantage of
478 separating the build tree from the source is that the build tree
479 can be placed in a non-backed-up partition, saving your systems
480 support people from backing up untold megabytes of
481 easily-regenerated, and rapidly-changing, gubbins. The golden
482 rule is that (with a single exception—<xref
483 linkend="sec-build-config"/>) <emphasis>absolutely everything in
484 the build tree is either a symbolic link to the source tree, or
485 else is mechanically generated</emphasis>. It should be
486 perfectly OK for your build tree to vanish overnight; an hour or
487 two compiling and you're on the road again.</para>
489 <para>You need to be a bit careful, though, that any new files
490 you create (if you do any development work) are in the source
491 tree, not a build tree!</para>
493 <para>Remember, that the source files in the build tree are
494 <emphasis>symbolic links</emphasis> to the files in the source
495 tree. (The build tree soon accumulates lots of built files like
496 <filename>Foo.o</filename>, as well.) You can
497 <emphasis>delete</emphasis> a source file from the build tree
498 without affecting the source tree (though it's an odd thing to
499 do). On the other hand, if you <emphasis>edit</emphasis> a
500 source file from the build tree, you'll edit the source-tree
501 file directly. (You can set up Emacs so that if you edit a
502 source file from the build tree, Emacs will silently create an
503 edited copy of the source file in the build tree, leaving the
504 source file unchanged; but the danger is that you think you've
505 edited the source file whereas actually all you've done is edit
506 the build-tree copy. More commonly you do want to edit the
509 <para>Like the source tree, the top level of your build tree
510 must be (a linked copy of) the root directory of the GHC source
511 tree.. Inside Makefiles, the root of your build tree is called
512 <constant>$(GHC_TOP)</constant><indexterm><primary>GHC_TOP</primary></indexterm>.
513 In the rest of this document path names are relative to
514 <constant>$(GHC_TOP)</constant> unless
515 otherwise stated. For example, the file
516 <filename>mk/target.mk</filename> is actually
517 <filename>$(GHC_TOP)/mk/target.mk</filename>.</para>
520 <sect2 id="sec-build-config">
521 <title>Getting the build you want</title>
523 <para>When you build GHC you will be compiling code on a
524 particular <emphasis>host platform</emphasis>, to run on a
525 particular <emphasis>target platform</emphasis> (usually the
527 platform)<indexterm><primary>platform</primary></indexterm>.
528 The difficulty is that there are minor differences between
529 different platforms; minor, but enough that the code needs to be
530 a bit different for each. There are some big differences too:
531 for a different architecture we need to build GHC with a
532 different native-code generator.</para>
534 <para>There are also knobs you can turn to control how the
535 software is built. For example, you might want to build GHC
536 optimised (so that it runs fast) or unoptimised (so that you can
537 compile it fast after you've modified it. Or, you might want to
538 compile it with debugging on (so that extra consistency-checking
539 code gets included) or off. And so on.</para>
541 <para>All of this stuff is called the
542 <emphasis>configuration</emphasis> of your build. You set the
543 configuration using a three-step process.</para>
547 <term>Step 1: get ready for configuration.</term>
549 <para>NOTE: if you're starting from a source distribution,
550 rather than darcs sources, you can skip this step.</para>
552 <para>Change directory to
553 <constant>$(GHC_TOP)</constant> and
554 issue the command</para>
555 <screen>$ autoreconf</screen>
556 <indexterm><primary>autoreconf</primary></indexterm>
557 <para>(with no arguments). This GNU program (recursively) converts
558 <filename>$(GHC_TOP)/configure.ac</filename> and
559 <filename>$(GHC_TOP)/aclocal.m4</filename>
560 to a shell script called
561 <filename>$(GHC_TOP)/configure</filename>.
562 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
563 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
564 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
565 a message like "No rule to make target 'mk/config.h.in'".
568 <para>Some parts of the source tree, particularly
569 libraries, have their own configure script.
570 <command>autoreconf</command> takes care of that, too, so all you have
571 to do is calling <command>autoreconf</command> in the top-level directory
572 <filename>$(GHC_TOP)</filename>.</para>
574 <para>These steps are completely platform-independent; they just mean
575 that the human-written files (<filename>configure.ac</filename> and
576 <filename>aclocal.m4</filename>) can be short, although the resulting
577 files (the <command>configure</command> shell scripts and the C header
578 template <filename>mk/config.h.in</filename>) are long.</para>
583 <term>Step 2: system configuration.</term>
585 <para>Runs the newly-created <command>configure</command>
588 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
590 <para><command>configure</command>'s mission is to scurry
591 round your computer working out what architecture it has,
592 what operating system, whether it has the
593 <function>vfork</function> system call, where
594 <command>tar</command> is kept, whether
595 <command>gcc</command> is available, where various obscure
596 <literal>#include</literal> files are, whether it's a
597 leap year, and what the systems manager had for lunch. It
598 communicates these snippets of information in two
605 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
607 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
608 substituting for things between
609 “<literal>@</literal>” brackets. So,
610 “<literal>@HaveGcc@</literal>” will be
611 replaced by “<literal>YES</literal>” or
612 “<literal>NO</literal>” depending on what
613 <command>configure</command> finds.
614 <filename>mk/config.mk</filename> is included by every
615 Makefile (directly or indirectly), so the
616 configuration information is thereby communicated to
617 all Makefiles.</para>
622 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
624 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
625 The latter is <literal>#include</literal>d by
626 various C programs, which can thereby make use of
627 configuration information.</para>
631 <para><command>configure</command> takes some optional
632 arguments. Use <literal>./configure --help</literal> to
633 get a list of the available arguments. Here are some of
634 the ones you might need:</para>
638 <term><literal>--with-ghc=<parameter>path</parameter></literal>
639 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
642 <para>Specifies the path to an installed GHC which
643 you would like to use. This compiler will be used
644 for compiling GHC-specific code (eg. GHC itself).
645 This option <emphasis>cannot</emphasis> be specified
646 using <filename>build.mk</filename> (see later),
647 because <command>configure</command> needs to
648 auto-detect the version of GHC you're using. The
649 default is to look for a compiler named
650 <literal>ghc</literal> in your path.</para>
655 <term><literal>--with-hc=<parameter>path</parameter></literal>
656 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
659 <para>Specifies the path to any installed Haskell
660 compiler. This compiler will be used for compiling
661 generic Haskell code. The default is to use
662 <literal>ghc</literal>. (NOTE: I'm not sure it
663 actually works to specify a compiler other than GHC
664 here; unless you really know what you're doing I
665 suggest not using this option at all.)</para>
670 <term><literal>--with-gcc=<parameter>path</parameter></literal>
671 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
674 <para>Specifies the path to the installed GCC. This
675 compiler will be used to compile all C files,
676 <emphasis>except</emphasis> any generated by the
677 installed Haskell compiler, which will have its own
678 idea of which C compiler (if any) to use. The
679 default is to use <literal>gcc</literal>.</para>
687 <term>Step 3: build configuration.</term>
689 <para>Next, you say how this build of
690 GHC is to differ from the standard
691 defaults by creating a new file
692 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
693 <emphasis>in the build tree</emphasis>. This file is the
694 one and only file you edit in the build tree, precisely
695 because it says how this build differs from the source.
696 (Just in case your build tree does die, you might want to
697 keep a private directory of <filename>build.mk</filename>
698 files, and use a symbolic link in each build tree to point
699 to the appropriate one.) So
700 <filename>mk/build.mk</filename> never exists in the
701 source tree—you create one in each build tree from
702 the template. We'll discuss what to put in it
708 <para>And that's it for configuration. Simple, eh?</para>
710 <para>What do you put in your build-specific configuration file
711 <filename>mk/build.mk</filename>? <emphasis>For almost all
712 purposes all you will do is put make variable definitions that
713 override those in</emphasis>
714 <filename>mk/config.mk.in</filename>. The whole point of
715 <filename>mk/config.mk.in</filename>—and its derived
716 counterpart <filename>mk/config.mk</filename>—is to define
717 the build configuration. It is heavily commented, as you will
718 see if you look at it. So generally, what you do is look at
719 <filename>mk/config.mk.in</filename>, and add definitions in
720 <filename>mk/build.mk</filename> that override any of the
721 <filename>config.mk</filename> definitions that you want to
722 change. (The override occurs because the main boilerplate file,
723 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
724 includes <filename>build.mk</filename> after
725 <filename>config.mk</filename>.)</para>
727 <para>For your convenience, there's a file called
728 <filename>build.mk.sample</filename> that can serve as a starting
729 point for your <filename>build.mk</filename>.</para>
731 <para>For example, <filename>config.mk.in</filename> contains
732 the definition:</para>
734 <programlisting>GhcHcOpts=-Rghc-timing</programlisting>
736 <para>The accompanying comment explains that this is the list of
737 flags passed to GHC when building GHC itself. For doing
738 development, it is wise to add <literal>-DDEBUG</literal>, to
739 enable debugging code. So you would add the following to
740 <filename>build.mk</filename>:</para>
742 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
744 <para>GNU <command>make</command> allows existing definitions to
745 have new text appended using the “<literal>+=</literal>”
746 operator, which is quite a convenient feature.</para>
748 <para>Haskell compilations by default have <literal>-O</literal>
749 turned on, by virtue of this setting from
750 <filename>config.mk</filename>:</para>
752 <programlisting>SRC_HC_OPTS += -H16m -O</programlisting>
754 <para><literal>SRC_HC_OPTS</literal> means "options for HC from
755 the source tree", where HC stands for Haskell Compiler.
756 <literal>SRC_HC_OPTS</literal> are added to every Haskell
757 compilation. To turn off optimisation, you could add this to
758 <filename>build.mk</filename>:</para>
760 <programlisting>SRC_HC_OPTS = -H16m -O0</programlisting>
762 <para>Or you could just add <literal>-O0</literal> to
763 <literal>GhcHcOpts</literal> to turn off optimisation for the
764 compiler. See <xref linkend="quick-start" /> for some more
767 <para>When reading <filename>config.mk.in</filename>, remember
768 that anything between “@...@” signs is going to be substituted
769 by <command>configure</command> later. You
770 <emphasis>can</emphasis> override the resulting definition if
771 you want, but you need to be a bit surer what you are doing.
772 For example, there's a line that says:</para>
774 <programlisting>TAR = @TarCmd@</programlisting>
776 <para>This defines the Make variables <constant>TAR</constant>
777 to the pathname for a <command>tar</command> that
778 <command>configure</command> finds somewhere. If you have your
779 own pet <command>tar</command> you want to use instead, that's
780 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
782 <programlisting>TAR = mytar</programlisting>
784 <para>You do not <emphasis>have</emphasis> to have a
785 <filename>mk/build.mk</filename> file at all; if you don't,
786 you'll get all the default settings from
787 <filename>mk/config.mk.in</filename>.</para>
789 <para>You can also use <filename>build.mk</filename> to override
790 anything that <command>configure</command> got wrong. One place
791 where this happens often is with the definition of
792 <constant>GHC_TOP_ABS</constant>: this
793 variable is supposed to be the canonical path to the top of your
794 source tree, but if your system uses an automounter then the
795 correct directory is hard to find automatically. If you find
796 that <command>configure</command> has got it wrong, just put the
797 correct definition in <filename>build.mk</filename>.</para>
800 <sect2 id="sec-storysofar">
801 <title>The story so far</title>
803 <para>Let's summarise the steps you need to carry to get
804 yourself a fully-configured build tree from scratch.</para>
808 <para> Get your source tree from somewhere (darcs repository
809 or source distribution). Say you call the root directory
810 <filename>myghc</filename> (it does not have to be
811 called <filename>ghc</filename>).</para>
815 <para>(Optional) Use <command>lndir</command> or
816 <command>mkshadowdir</command> to create a build tree.</para>
819 $ mkshadowdir . /scratch/joe-bloggs/myghc-x86</screen>
821 <para>(N.B. <command>mkshadowdir</command>'s first argument
822 is taken relative to its second.) You probably want to give
823 the build tree a name that suggests its main defining
824 characteristic (in your mind at least), in case you later
829 <para>Change directory to the build tree. Everything is
830 going to happen there now.</para>
832 <screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
837 <para>Prepare for system configuration:</para>
839 <screen>$ autoreconf</screen>
841 <para>(You can skip this step if you are starting from a
842 source distribution, and you already have
843 <filename>configure</filename> and
844 <filename>mk/config.h.in</filename>.)</para>
848 <para>Do system configuration:</para>
850 <screen>$ ./configure</screen>
852 <para>Don't forget to check whether you need to add any
853 arguments to <literal>configure</literal>; for example, a
854 common requirement is to specify which GHC to use with
855 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
859 <para>Create the file <filename>mk/build.mk</filename>,
860 adding definitions for your desired configuration
865 <para>You can make subsequent changes to
866 <filename>mk/build.mk</filename> as often as you like. You do
867 not have to run any further configuration programs to make these
868 changes take effect. In theory you should, however, say
869 <command>make clean; make</command>, because configuration
870 option changes could affect anything—but in practice you
871 are likely to know what's affected.</para>
875 <title>Making things</title>
877 <para>At this point you have made yourself a fully-configured
878 build tree, so you are ready to start building real
881 <para>The first thing you need to know is that <emphasis>you
882 must use GNU <command>make</command></emphasis>. On some
883 systems (eg. FreeBSD) this is called <command>gmake</command>,
884 whereas on others it is the standard <command>make</command>
885 command. In this document we will always refer to it as
886 <command>make</command>; please substitute with
887 <command>gmake</command> if your system requires it. If you use
888 a the wrong <command>make</command> you will get all sorts of
889 error messages (but no damage) because the GHC
890 <command>Makefiles</command> use GNU <command>make</command>'s
891 facilities extensively.</para>
893 <para>To just build the whole thing, <command>cd</command> to
894 the top of your build tree and type <command>make</command>.
895 This will prepare the tree and build the various parts in the
896 correct order, resulting in a complete build of GHC that can
897 even be used directly from the tree, without being installed
901 <sect2 id="sec-bootstrapping">
902 <title>Bootstrapping GHC</title>
904 <para>GHC requires a 2-stage bootstrap in order to provide
905 full functionality, including GHCi. By a 2-stage bootstrap, we
906 mean that the compiler is built once using the installed GHC,
907 and then again using the compiler built in the first stage. You
908 can also build a stage 3 compiler, but this normally isn't
909 necessary except to verify that the stage 2 compiler is working
912 <para>Note that when doing a bootstrap, the stage 1 compiler
913 must be built, followed by the runtime system and libraries, and
914 then the stage 2 compiler. The correct ordering is implemented
915 by the top-level <filename>Makefile</filename>, so if you want
916 everything to work automatically it's best to start
917 <command>make</command> from the top of the tree. The top-level
918 <filename>Makefile</filename> is set up to do a 2-stage
919 bootstrap by default (when you say <command>make</command>).
920 Some other targets it supports are:</para>
926 <para>Build everything as normal, including the stage 1
934 <para>Build the stage 2 compiler only.</para>
941 <para>Build the stage 3 compiler only.</para>
946 <term>bootstrap</term> <term>bootstrap2</term>
948 <para>Build stage 1 followed by stage 2.</para>
953 <term>bootstrap3</term>
955 <para>Build stages 1, 2 and 3.</para>
962 <para>Install everything, including the compiler built in
963 stage 2. To override the stage, say <literal>make install
964 stage=<replaceable>n</replaceable></literal> where
965 <replaceable>n</replaceable> is the stage to install.</para>
970 <term><literal>binary-dist</literal></term>
972 <para>make a binary distribution. This is the target we
973 use to build the binary distributions of GHC.</para>
978 <term><literal>dist</literal></term>
980 <para>make a source distribution. Note that this target
981 does “make distclean” as part of its work;
982 don't use it if you want to keep what you've built.</para>
987 <para>The top-level <filename>Makefile</filename> also arranges
988 to do the appropriate <literal>make boot</literal> steps (see
989 below) before actually building anything.</para>
991 <para>The <literal>stage1</literal>, <literal>stage2</literal>
992 and <literal>stage3</literal> targets also work in the
993 <literal>compiler</literal> directory, but don't forget that
994 each stage requires its own <literal>make boot</literal> step:
995 for example, you must do</para>
997 <screen>$ make boot stage=2</screen>
999 <para>before <literal>make stage2</literal> in
1000 <literal>compiler</literal>.</para>
1003 <sect2 id="sec-standard-targets">
1004 <title>Standard Targets</title>
1005 <indexterm><primary>targets, standard makefile</primary></indexterm>
1006 <indexterm><primary>makefile targets</primary></indexterm>
1008 <para>In any directory you should be able to make the following:</para>
1012 <term><literal>boot</literal></term>
1014 <para>does the one-off preparation required to get ready
1015 for the real work. Notably, it does <command>make
1016 depend</command> in all directories that contain programs.
1017 It also builds the necessary tools for compilation to
1020 <para>Invoking the <literal>boot</literal> target
1021 explicitly is not normally necessary. From the top-level
1022 directory, invoking <literal>make</literal> causes
1023 <literal>make boot</literal> to be invoked in various
1024 subdirectories first, in the right order. Unless you
1025 really know what you are doing, it is best to always say
1026 <literal>make</literal> from the top level first.</para>
1028 <para>If you're working in a subdirectory somewhere and
1029 need to update the dependencies, <literal>make
1030 boot</literal> is a good way to do it.</para>
1035 <term><literal>all</literal></term>
1037 <para>makes all the final target(s) for this Makefile.
1038 Depending on which directory you are in a “final
1039 target” may be an executable program, a library
1040 archive, a shell script, or a Postscript file. Typing
1041 <command>make</command> alone is generally the same as
1042 typing <command>make all</command>.</para>
1047 <term><literal>install</literal></term>
1049 <para>installs the things built by <literal>all</literal>
1050 (except for the documentation). Where does it install
1051 them? That is specified by
1052 <filename>mk/config.mk.in</filename>; you can override it
1053 in <filename>mk/build.mk</filename>, or by running
1054 <command>configure</command> with command-line arguments
1055 like <literal>--bindir=/home/simonpj/bin</literal>; see
1056 <literal>./configure --help</literal> for the full
1062 <term><literal>install-docs</literal></term>
1064 <para>installs the documentation. Otherwise behaves just
1065 like <literal>install</literal>.</para>
1070 <term><literal>uninstall</literal></term>
1072 <para>reverses the effect of
1073 <literal>install</literal> (WARNING: probably doesn't work).</para>
1078 <term><literal>clean</literal></term>
1080 <para>Delete all files from the current directory that are
1081 normally created by building the program. Don't delete
1082 the files that record the configuration, or files
1083 generated by <command>make boot</command>. Also preserve
1084 files that could be made by building, but normally aren't
1085 because the distribution comes with them.</para>
1090 <term><literal>distclean</literal></term>
1092 <para>Delete all files from the current directory that are
1093 created by configuring or building the program. If you
1094 have unpacked the source and built the program without
1095 creating any other files, <literal>make
1096 distclean</literal> should leave only the files that were
1097 in the distribution.</para>
1102 <term><literal>mostlyclean</literal></term>
1104 <para>Like <literal>clean</literal>, but may refrain from
1105 deleting a few files that people normally don't want to
1111 <term><literal>maintainer-clean</literal></term>
1113 <para>Delete everything from the current directory that
1114 can be reconstructed with this Makefile. This typically
1115 includes everything deleted by
1116 <literal>distclean</literal>, plus more: C source files
1117 produced by Bison, tags tables, Info files, and so
1120 <para>One exception, however: <literal>make
1121 maintainer-clean</literal> should not delete
1122 <filename>configure</filename> even if
1123 <filename>configure</filename> can be remade using a rule
1124 in the <filename>Makefile</filename>. More generally,
1125 <literal>make maintainer-clean</literal> should not delete
1126 anything that needs to exist in order to run
1127 <filename>configure</filename> and then begin to build the
1130 <para>After a <literal>maintainer-clean</literal>, a
1131 <literal>configure</literal> will be necessary before
1132 building again.</para>
1137 <para>All of these standard targets automatically recurse into
1138 sub-directories. Certain other standard targets do not:</para>
1142 <term><literal>depend</literal></term>
1144 <para>make a <filename>.depend</filename> file in each
1145 directory that needs it. This <filename>.depend</filename>
1146 file contains mechanically-generated dependency
1147 information; for example, suppose a directory contains a
1148 Haskell source module <filename>Foo.lhs</filename> which
1149 imports another module <literal>Baz</literal>. Then the
1150 generated <filename>.depend</filename> file will contain
1151 the dependency:</para>
1153 <programlisting>Foo.o : Baz.hi</programlisting>
1155 <para>which says that the object file
1156 <filename>Foo.o</filename> depends on the interface file
1157 <filename>Baz.hi</filename> generated by compiling module
1158 <literal>Baz</literal>. The <filename>.depend</filename>
1159 file is automatically included by every Makefile.</para>
1164 <para>Some <filename>Makefile</filename>s have targets other
1165 than these. You can discover them by looking in the
1166 <filename>Makefile</filename> itself.</para>
1170 <title>Using GHC from the build tree</title>
1172 <para>If you want to build GHC and just use it direct from the
1173 build tree without doing <literal>make install</literal> first,
1174 you can run the in-place driver script. To run the stage 1
1175 compiler, use <filename>compiler/stage1/ghc-inplace</filename>,
1176 stage 2 is <filename>compiler/stage2/ghc-inplace</filename>, and
1179 <para> Do <emphasis>NOT</emphasis> use
1180 <filename>compiler/stage1/ghc</filename>, or
1181 <filename>compiler/stage1/ghc-6.xx</filename>, as these are the
1182 scripts intended for installation, and contain hard-wired paths
1183 to the installed libraries, rather than the libraries in the
1188 <title>Fast Making</title>
1190 <indexterm><primary>fastmake</primary></indexterm>
1191 <indexterm><primary>dependencies, omitting</primary></indexterm>
1192 <indexterm><primary>FAST, makefile variable</primary></indexterm>
1194 <para>Sometimes the dependencies get in the way: if you've made
1195 a small change to one file, and you're absolutely sure that it
1196 won't affect anything else, but you know that
1197 <command>make</command> is going to rebuild everything anyway,
1198 the following hack may be useful:</para>
1200 <screen>$ make FAST=YES</screen>
1202 <para>This tells the make system to ignore dependencies and just
1203 build what you tell it to. In other words, it's equivalent to
1204 temporarily removing the <filename>.depend</filename> file in
1205 the current directory (where <command>mkdependHS</command> and
1206 friends store their dependency information).</para>
1208 <para>A bit of history: GHC used to come with a
1209 <command>fastmake</command> script that did the above job, but
1210 GNU make provides the features we need to do it without
1211 resorting to a script. Also, we've found that fastmaking is
1212 less useful since the advent of GHC's recompilation checker (see
1213 the User's Guide section on "Separate Compilation").</para>
1217 <sect1 id="sec-makefile-arch">
1218 <title>The <filename>Makefile</filename> architecture</title>
1219 <indexterm><primary>makefile architecture</primary></indexterm>
1221 <para><command>make</command> is great if everything
1222 works—you type <command>make install</command> and lo! the
1223 right things get compiled and installed in the right places. Our
1224 goal is to make this happen often, but somehow it often doesn't;
1225 instead some weird error message eventually emerges from the
1226 bowels of a directory you didn't know existed.</para>
1228 <para>The purpose of this section is to give you a road-map to
1229 help you figure out what is going right and what is going
1233 <title>Debugging</title>
1235 <para>Debugging <filename>Makefile</filename>s is something of a
1236 black art, but here's a couple of tricks that we find
1237 particularly useful. The following command allows you to see
1238 the contents of any make variable in the context of the current
1239 <filename>Makefile</filename>:</para>
1241 <screen>$ make show VALUE=HS_SRCS</screen>
1243 <para>where you can replace <literal>HS_SRCS</literal> with the
1244 name of any variable you wish to see the value of.</para>
1246 <para>GNU make has a <option>-d</option> option which generates
1247 a dump of the decision procedure used to arrive at a conclusion
1248 about which files should be recompiled. Sometimes useful for
1249 tracking down problems with superfluous or missing
1250 recompilations.</para>
1254 <title>A small example</title>
1256 <para>To get started, let us look at the
1257 <filename>Makefile</filename> for an imaginary small program,
1258 <literal>small</literal>. Each program or library in the GHC
1259 source tree typically has its own directory, in this case we'll
1260 use <filename>$(GHC_TOP)/small</filename>.
1261 Inside the <filename>small/</filename> directory there will be a
1262 <filename>Makefile</filename>, looking something like
1265 <indexterm><primary>Makefile, minimal</primary></indexterm>
1267 <programlisting># Makefile for program "small"
1269 include $(TOP)/mk/boilerplate.mk
1273 include $(TOP)/target.mk</programlisting>
1275 <para>this <filename>Makefile</filename> has three
1280 <para>The first section includes
1283 One of the most important
1284 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
1285 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
1290 a file of “boilerplate” code from the top level
1291 <indexterm><primary>boilerplate.mk</primary></indexterm>).
1292 As its name suggests, <filename>boilerplate.mk</filename>
1293 consists of a large quantity of standard
1294 <filename>Makefile</filename> code. We discuss this
1295 boilerplate in more detail in <xref linkend="sec-boiler"/>.
1296 <indexterm><primary>include, directive in
1297 Makefiles</primary></indexterm> <indexterm><primary>Makefile
1298 inclusion</primary></indexterm></para>
1300 <para>Before the <literal>include</literal> statement, you
1301 must define the <command>make</command> variable
1302 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
1303 to be the top-level directory of the source tree, containing
1304 the <filename>mk</filename>
1305 directory in which the <filename>boilerplate.mk</filename>
1306 file is. It is <emphasis>not</emphasis> OK to simply say</para>
1308 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
1310 <para>Why? Because the <filename>boilerplate.mk</filename>
1311 file needs to know where it is, so that it can, in turn,
1312 <literal>include</literal> other files. (Unfortunately,
1313 when an <literal>include</literal>d file does an
1314 <literal>include</literal>, the filename is treated relative
1315 to the directory in which <command>make</command> is being
1316 run, not the directory in which the
1317 <literal>include</literal>d sits.) In general,
1318 <emphasis>every file <filename>foo.mk</filename> assumes
1320 <filename>$(TOP)/mk/foo.mk</filename>
1321 refers to itself.</emphasis> It is up to the
1322 <filename>Makefile</filename> doing the
1323 <literal>include</literal> to ensure this is the case.</para>
1327 <para> The second section defines the standard
1328 <command>make</command> variable
1329 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
1330 (the executable binary to be built). We will discuss in
1331 more detail what the “standard variables” are,
1332 and how they affect what happens, in <xref
1333 linkend="sec-targets"/>.</para>
1337 <para>The last section includes a second file of standard
1339 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
1340 It contains the rules that tell <command>make</command> how
1341 to make the standard targets (<xref
1342 linkend="sec-standard-targets"/>). Why, you ask, can't this
1343 standard code be part of
1344 <filename>boilerplate.mk</filename>? Good question. We
1345 discuss the reason later, in <xref
1346 linkend="sec-boiler-arch"/>.</para>
1348 <para>You do not <emphasis>have</emphasis> to
1349 <literal>include</literal> the
1350 <filename>target.mk</filename> file. Instead, you can write
1351 rules of your own for all the standard targets. Usually,
1352 though, you will find quite a big payoff from using the
1353 canned rules in <filename>target.mk</filename>; the price
1354 tag is that you have to understand what canned rules get
1355 enabled, and what they do (<xref
1356 linkend="sec-targets"/>).</para>
1360 <para>In our example <filename>Makefile</filename>, most of the
1361 work is done by the two <literal>include</literal>d files. When
1362 you say <command>make all</command>, the following things
1367 <para><command>make</command> looks in the current directory
1368 to see what source files it can find
1369 (eg. <filename>Foo.hs</filename>,
1370 <filename>Baz.c</filename>), and from that it figures out
1371 what object files need to be built
1372 (eg. <filename>Foo.o</filename>,
1373 <filename>Baz.o</filename>). Because source files are found
1374 and used automatically, omitting them from a program or
1375 library has to be done manually (see
1376 <literal>EXCLUDED_SRCS</literal> in <xref
1377 linkend="sec-boiler" />).</para>
1381 <para>It uses a boilerplate pattern rule to compile
1382 <filename>Foo.hs</filename> to <filename>Foo.o</filename>
1383 using a Haskell compiler. (Which one? That is set in the
1384 build configuration.)</para>
1388 <para>It uses another standard pattern rule to compile
1389 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
1390 using a C compiler. (Ditto.)</para>
1394 <para>It links the resulting <filename>.o</filename> files
1395 together to make <literal>small</literal>, using the Haskell
1396 compiler to do the link step. (Why not use
1397 <command>ld</command>? Because the Haskell compiler knows
1398 what standard libraries to link in. How did
1399 <command>make</command> know to use the Haskell compiler to
1400 do the link, rather than the C compiler? Because we set the
1401 variable <constant>HS_PROG</constant> rather than
1402 <constant>C_PROG</constant>.)</para>
1406 <para>All <filename>Makefile</filename>s should follow the above
1407 three-section format.</para>
1410 <sect2 id="sec-boiler-arch">
1411 <title>Boilerplate architecture</title>
1412 <indexterm><primary>boilerplate architecture</primary></indexterm>
1414 <para>Every <filename>Makefile</filename> includes a
1415 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
1416 file at the top, and
1417 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
1418 file at the bottom. In this section we discuss what is in these
1419 files, and why there have to be two of them. In general:</para>
1423 <para><filename>boilerplate.mk</filename> consists of:</para>
1427 <para><emphasis>Definitions of millions of
1428 <command>make</command> variables</emphasis> that
1429 collectively specify the build configuration. Examples:
1430 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1431 the options to feed to the Haskell compiler;
1432 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
1433 the sub-directories to enable within the
1434 <literal>nofib</literal> project;
1435 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
1436 the name of the Haskell compiler to use when compiling
1437 GHC in the <literal>ghc</literal> project.</para>
1441 <para><emphasis>Standard pattern rules</emphasis> that
1442 tell <command>make</command> how to construct one file
1443 from another.</para>
1447 <para><filename>boilerplate.mk</filename> needs to be
1448 <literal>include</literal>d at the <emphasis>top</emphasis>
1449 of each <filename>Makefile</filename>, so that the user can
1450 replace the boilerplate definitions or pattern rules by
1451 simply giving a new definition or pattern rule in the
1452 <filename>Makefile</filename>. <command>make</command>
1453 simply takes the last definition as the definitive one.</para>
1455 <para>Instead of <emphasis>replacing</emphasis> boilerplate
1456 definitions, it is also quite common to
1457 <emphasis>augment</emphasis> them. For example, a
1458 <filename>Makefile</filename> might say:</para>
1460 <programlisting>SRC_HC_OPTS += -O</programlisting>
1462 <para>thereby adding “<option>-O</option>” to
1464 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
1468 <para><filename>target.mk</filename> contains
1469 <command>make</command> rules for the standard targets
1470 described in <xref linkend="sec-standard-targets"/>. These
1471 rules are selectively included, depending on the setting of
1472 certain <command>make</command> variables. These variables
1473 are usually set in the middle section of the
1474 <filename>Makefile</filename> between the two
1475 <literal>include</literal>s.</para>
1477 <para><filename>target.mk</filename> must be included at the
1478 end (rather than being part of
1479 <filename>boilerplate.mk</filename>) for several tiresome
1485 <para><command>make</command> commits target and
1486 dependency lists earlier than it should. For example,
1487 <filename>target.mk</filename> has a rule that looks
1490 <programlisting>$(HS_PROG) : $(OBJS)
1491 $(HC) $(LD_OPTS) $< -o $@</programlisting>
1493 <para>If this rule was in
1494 <filename>boilerplate.mk</filename> then
1495 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
1497 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
1498 would not have their final values at the moment
1499 <command>make</command> encountered the rule. Alas,
1500 <command>make</command> takes a snapshot of their
1501 current values, and wires that snapshot into the rule.
1502 (In contrast, the commands executed when the rule
1503 “fires” are only substituted at the moment
1504 of firing.) So, the rule must follow the definitions
1505 given in the <filename>Makefile</filename> itself.</para>
1509 <para>Unlike pattern rules, ordinary rules cannot be
1510 overriden or replaced by subsequent rules for the same
1511 target (at least, not without an error message).
1512 Including ordinary rules in
1513 <filename>boilerplate.mk</filename> would prevent the
1514 user from writing rules for specific targets in specific
1519 <para>There are a couple of other reasons I've
1520 forgotten, but it doesn't matter too much.</para>
1527 <sect2 id="sec-boiler">
1528 <title>The <filename>mk/boilerplate.mk</filename> file</title>
1529 <indexterm><primary>boilerplate.mk</primary></indexterm>
1531 <para>If you look at
1532 <filename>$(GHC_TOP)/mk/boilerplate.mk</filename>
1533 you will find that it consists of the following sections, each
1534 held in a separate file:</para>
1538 <term><filename>config.mk</filename>
1539 <indexterm><primary>config.mk</primary></indexterm>
1542 <para>is the build configuration file we discussed at
1543 length in <xref linkend="sec-build-config"/>.</para>
1548 <term><filename>paths.mk</filename>
1549 <indexterm><primary>paths.mk</primary></indexterm>
1552 <para>defines <command>make</command> variables for
1553 pathnames and file lists. This file contains code for
1554 automatically compiling lists of source files and deriving
1555 lists of object files from those. The results can be
1556 overriden in the <filename>Makefile</filename>, but in
1557 most cases the automatic setup should do the right
1560 <para>The following variables may be set in the
1561 <filename>Makefile</filename> to affect how the automatic
1562 source file search is done:</para>
1566 <term><literal>ALL_DIRS</literal>
1567 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
1570 <para>Set to a list of directories to search in
1571 addition to the current directory for source
1577 <term><literal>EXCLUDED_SRCS</literal>
1578 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
1581 <para>Set to a list of source files (relative to the
1582 current directory) to omit from the automatic
1583 search. The source searching machinery is clever
1584 enough to know that if you exclude a source file
1585 from which other sources are derived, then the
1586 derived sources should also be excluded. For
1587 example, if you set <literal>EXCLUDED_SRCS</literal>
1588 to include <filename>Foo.y</filename>, then
1589 <filename>Foo.hs</filename> will also be
1595 <term><literal>EXTRA_SRCS</literal>
1596 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
1599 <para>Set to a list of extra source files (perhaps
1600 in directories not listed in
1601 <literal>ALL_DIRS</literal>) that should be
1607 <para>The results of the automatic source file search are
1608 placed in the following make variables:</para>
1612 <term><literal>SRCS</literal>
1613 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
1616 <para>All source files found, sorted and without
1617 duplicates, including those which might not exist
1618 yet but will be derived from other existing sources.
1619 <literal>SRCS</literal> <emphasis>can</emphasis> be
1620 overriden if necessary, in which case the variables
1621 below will follow suit.</para>
1626 <term><literal>HS_SRCS</literal>
1627 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
1630 <para>all Haskell source files in the current
1631 directory, including those derived from other source
1632 files (eg. Happy sources also give rise to Haskell
1638 <term><literal>HS_OBJS</literal>
1639 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
1642 <para>Object files derived from
1643 <literal>HS_SRCS</literal>.</para>
1648 <term><literal>HS_IFACES</literal>
1649 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
1652 <para>Interface files (<literal>.hi</literal> files)
1653 derived from <literal>HS_SRCS</literal>.</para>
1658 <term><literal>C_SRCS</literal>
1659 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
1662 <para>All C source files found.</para>
1667 <term><literal>C_OBJS</literal>
1668 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
1671 <para>Object files derived from
1672 <literal>C_SRCS</literal>.</para>
1677 <term><literal>SCRIPT_SRCS</literal>
1678 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
1681 <para>All script source files found
1682 (<literal>.lprl</literal> files).</para>
1687 <term><literal>SCRIPT_OBJS</literal>
1688 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
1691 <para><quote>object</quote> files derived from
1692 <literal>SCRIPT_SRCS</literal>
1693 (<literal>.prl</literal> files).</para>
1698 <term><literal>HSC_SRCS</literal>
1699 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
1702 <para>All <literal>hsc2hs</literal> source files
1703 (<literal>.hsc</literal> files).</para>
1708 <term><literal>HAPPY_SRCS</literal>
1709 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
1712 <para>All <literal>happy</literal> source files
1713 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
1718 <term><literal>OBJS</literal>
1719 <indexterm><primary>OBJS</primary></indexterm>
1722 <para>the concatenation of
1723 <literal>$(HS_OBJS)</literal>,
1724 <literal>$(C_OBJS)</literal>, and
1725 <literal>$(SCRIPT_OBJS)</literal>.</para>
1730 <para>Any or all of these definitions can easily be
1731 overriden by giving new definitions in your
1732 <filename>Makefile</filename>.</para>
1734 <para>What, exactly, does <filename>paths.mk</filename>
1735 consider a <quote>source file</quote> to be? It's based
1736 on the file's suffix (e.g. <filename>.hs</filename>,
1737 <filename>.lhs</filename>, <filename>.c</filename>,
1738 <filename>.hy</filename>, etc), but this is the kind of
1739 detail that changes, so rather than enumerate the source
1740 suffices here the best thing to do is to look in
1741 <filename>paths.mk</filename>.</para>
1746 <term><filename>opts.mk</filename>
1747 <indexterm><primary>opts.mk</primary></indexterm>
1750 <para>defines <command>make</command> variables for option
1751 strings to pass to each program. For example, it defines
1752 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1753 the option strings to pass to the Haskell compiler. See
1754 <xref linkend="sec-suffix"/>.</para>
1759 <term><filename>suffix.mk</filename>
1760 <indexterm><primary>suffix.mk</primary></indexterm>
1763 <para>defines standard pattern rules—see <xref
1764 linkend="sec-suffix"/>.</para>
1769 <para>Any of the variables and pattern rules defined by the
1770 boilerplate file can easily be overridden in any particular
1771 <filename>Makefile</filename>, because the boilerplate
1772 <literal>include</literal> comes first. Definitions after this
1773 <literal>include</literal> directive simply override the default
1774 ones in <filename>boilerplate.mk</filename>.</para>
1777 <sect2 id="sec-platforms">
1778 <title>Platform settings</title>
1779 <indexterm><primary>Platform settings</primary>
1782 <para>There are three platforms of interest when building GHC:</para>
1786 <term>The <emphasis>build</emphasis> platform</term>
1788 <para>The platform on which we are doing this build.</para>
1793 <term>The <emphasis>host</emphasis> platform</term>
1795 <para>The platform on which these binaries will run.</para>
1800 <term>The <emphasis>target</emphasis> platform</term>
1802 <para>The platform for which this compiler will generate code.</para>
1807 <para>These platforms are set when running the
1808 <literal>configure</literal> script, using the
1809 <option>--build</option>, <option>--host</option>, and
1810 <option>--target</option> options. The <filename>mk/config.mk</filename>
1811 file defines several symbols related to the platform settings (see
1812 <filename>mk/config.mk</filename> for details).</para>
1814 <para>We don't currently support build & host being different, because
1815 the build process creates binaries that are both run during the build,
1816 and also installed.</para>
1818 <para>If host and target are different, then we are building a
1819 cross-compiler. For GHC, this means a compiler
1820 which will generate intermediate .hc files to port to the target
1821 architecture for bootstrapping. The libraries and stage 2 compiler
1822 will be built as HC files for the target system (see <xref
1823 linkend="sec-porting-ghc" /> for details.</para>
1825 <para>More details on when to use BUILD, HOST or TARGET can be found in
1826 the comments in <filename>config.mk</filename>.</para>
1829 <sect2 id="sec-suffix">
1830 <title>Pattern rules and options</title>
1831 <indexterm><primary>Pattern rules</primary></indexterm>
1834 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
1835 defines standard <emphasis>pattern rules</emphasis> that say how
1836 to build one kind of file from another, for example, how to
1837 build a <filename>.o</filename> file from a
1838 <filename>.c</filename> file. (GNU <command>make</command>'s
1839 <emphasis>pattern rules</emphasis> are more powerful and easier
1840 to use than Unix <command>make</command>'s <emphasis>suffix
1841 rules</emphasis>.)</para>
1843 <para>Almost all the rules look something like this:</para>
1845 <programlisting>%.o : %.c
1847 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
1849 <para>Here's how to understand the rule. It says that
1850 <emphasis>something</emphasis><filename>.o</filename> (say
1851 <filename>Foo.o</filename>) can be built from
1852 <emphasis>something</emphasis><filename>.c</filename>
1853 (<filename>Foo.c</filename>), by invoking the C compiler (path
1854 name held in <constant>$(CC)</constant>), passing to it
1855 the options <constant>$(CC_OPTS)</constant> and
1856 the rule's dependent file of the rule
1857 <literal>$<</literal> (<filename>Foo.c</filename> in
1858 this case), and putting the result in the rule's target
1859 <literal>$@</literal> (<filename>Foo.o</filename> in this
1862 <para>Every program is held in a <command>make</command>
1863 variable defined in <filename>mk/config.mk</filename>—look
1864 in <filename>mk/config.mk</filename> for the complete list. One
1865 important one is the Haskell compiler, which is called
1866 <constant>$(HC)</constant>.</para>
1868 <para>Every program's options are are held in a
1869 <command>make</command> variables called
1870 <constant><prog>_OPTS</constant>. the
1871 <constant><prog>_OPTS</constant> variables are
1872 defined in <filename>mk/opts.mk</filename>. Almost all of them
1873 are defined like this:</para>
1875 <programlisting>CC_OPTS = \
1876 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
1878 <para>The four variables from which
1879 <constant>CC_OPTS</constant> is built have the following
1884 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
1886 <para>options passed to all C compilations.</para>
1891 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
1893 <para>options passed to C compilations for way
1894 <literal><way></literal>. For example,
1895 <constant>WAY_mp_CC_OPTS</constant>
1896 gives options to pass to the C compiler when compiling way
1897 <literal>mp</literal>. The variable
1898 <constant>WAY_CC_OPTS</constant> holds
1899 options to pass to the C compiler when compiling the
1900 standard way. (<xref linkend="sec-ways"/> dicusses
1901 multi-way compilation.)</para>
1906 <term><constant><module>_CC_OPTS</constant>:</term>
1908 <para>options to pass to the C compiler that are specific
1909 to module <literal><module></literal>. For example,
1910 <constant>SMap_CC_OPTS</constant> gives the
1911 specific options to pass to the C compiler when compiling
1912 <filename>SMap.c</filename>.</para>
1917 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
1919 <para>extra options to pass to all C compilations. This
1920 is intended for command line use, thus:</para>
1922 <screen>$ make libHS.a EXTRA_HC_OPTS="-v"</screen>
1928 <sect2 id="sec-targets">
1929 <title>The main <filename>mk/target.mk</filename> file</title>
1930 <indexterm><primary>target.mk</primary></indexterm>
1932 <para><filename>target.mk</filename> contains canned rules for
1933 all the standard targets described in <xref
1934 linkend="sec-standard-targets"/>. It is complicated by the fact
1935 that you don't want all of these rules to be active in every
1936 <filename>Makefile</filename>. Rather than have a plethora of
1937 tiny files which you can include selectively, there is a single
1938 file, <filename>target.mk</filename>, which selectively includes
1939 rules based on whether you have defined certain variables in
1940 your <filename>Makefile</filename>. This section explains what
1941 rules you get, what variables control them, and what the rules
1942 do. Hopefully, you will also get enough of an idea of what is
1943 supposed to happen that you can read and understand any weird
1944 special cases yourself.</para>
1948 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
1950 <para>If <constant>HS_PROG</constant> is defined,
1951 you get rules with the following targets:</para>
1955 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
1957 <para>itself. This rule links
1958 <constant>$(OBJS)</constant> with the Haskell
1959 runtime system to get an executable called
1960 <constant>$(HS_PROG)</constant>.</para>
1965 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
1968 <constant>$(HS_PROG)</constant> in
1969 <constant>$(bindir)</constant>.</para>
1978 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
1980 <para>is similar to <constant>HS_PROG</constant>,
1981 except that the link step links
1982 <constant>$(C_OBJS)</constant> with the C
1983 runtime system.</para>
1988 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
1990 <para>is similar to <constant>HS_PROG</constant>,
1991 except that it links
1992 <constant>$(LIB_OBJS)</constant> to make the
1993 library archive <constant>$(LIBRARY)</constant>,
1994 and <literal>install</literal> installs it in
1995 <constant>$(libdir)</constant>.</para>
2000 <para>Some rules are “double-colon” rules,
2003 <programlisting>install :: $(HS_PROG)
2004 ...how to install it...</programlisting>
2006 <para>GNU <command>make</command> treats double-colon rules as
2007 separate entities. If there are several double-colon rules for
2008 the same target it takes each in turn and fires it if its
2009 dependencies say to do so. This means that you can, for
2010 example, define both <constant>HS_PROG</constant> and
2011 <constant>LIBRARY</constant>, which will generate two rules for
2012 <literal>install</literal>. When you type <command>make
2013 install</command> both rules will be fired, and both the program
2014 and the library will be installed, just as you wanted.</para>
2017 <sect2 id="sec-subdirs">
2018 <title>Recursion</title>
2019 <indexterm><primary>recursion, in makefiles</primary></indexterm>
2020 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
2022 <para>In leaf <filename>Makefile</filename>s the variable
2023 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
2024 is undefined. In non-leaf <filename>Makefile</filename>s,
2025 <constant>SUBDIRS</constant> is set to the list of
2026 sub-directories that contain subordinate
2027 <filename>Makefile</filename>s. <emphasis>It is up to you to
2028 set <constant>SUBDIRS</constant> in the
2029 <filename>Makefile</filename>.</emphasis> There is no automation
2030 here—<constant>SUBDIRS</constant> is too important to
2033 <para>When <constant>SUBDIRS</constant> is defined,
2034 <filename>target.mk</filename> includes a rather neat rule for
2035 the standard targets (<xref linkend="sec-standard-targets"/> that
2036 simply invokes <command>make</command> recursively in each of
2037 the sub-directories.</para>
2039 <para><emphasis>These recursive invocations are guaranteed to
2040 occur in the order in which the list of directories is specified
2041 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
2042 be important. For example, when you say <command>make
2043 boot</command> it can be important that the recursive invocation
2044 of <command>make boot</command> is done in one sub-directory
2045 (the include files, say) before another (the source files).
2046 Generally, put the most independent sub-directory first, and the
2047 most dependent last.</para>
2050 <sect2 id="sec-ways">
2051 <title>Way management</title>
2052 <indexterm><primary>way management</primary></indexterm>
2054 <para>We sometimes want to build essentially the same system in
2055 several different “ways”. For example, we want to build GHC's
2056 <literal>Prelude</literal> libraries with and without profiling,
2057 so that there is an appropriately-built library archive to link
2058 with when the user compiles his program. It would be possible
2059 to have a completely separate build tree for each such “way”,
2060 but it would be horribly bureaucratic, especially since often
2061 only parts of the build tree need to be constructed in multiple
2065 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2066 contains some clever magic to allow you to build several
2067 versions of a system; and to control locally how many versions
2068 are built and how they differ. This section explains the
2071 <para>The files for a particular way are distinguished by
2072 munging the suffix. The <quote>normal way</quote> is always
2073 built, and its files have the standard suffices
2074 <filename>.o</filename>, <filename>.hi</filename>, and so on.
2075 In addition, you can build one or more extra ways, each
2076 distinguished by a <emphasis>way tag</emphasis>. The object
2077 files and interface files for one of these extra ways are
2078 distinguished by their suffix. For example, way
2079 <literal>mp</literal> has files
2080 <filename>.mp_o</filename> and
2081 <filename>.mp_hi</filename>. Library archives have their
2082 way tag the other side of the dot, for boring reasons; thus,
2083 <filename>libHS_mp.a</filename>.</para>
2085 <para>A <command>make</command> variable called
2086 <constant>way</constant> holds the current way tag.
2087 <emphasis><constant>way</constant> is only ever set on the
2088 command line of <command>make</command></emphasis> (usually in
2089 a recursive invocation of <command>make</command> by the
2090 system). It is never set inside a
2091 <filename>Makefile</filename>. So it is a global constant for
2092 any one invocation of <command>make</command>. Two other
2093 <command>make</command> variables,
2094 <constant>way_</constant> and
2095 <constant>_way</constant> are immediately derived from
2096 <constant>$(way)</constant> and never altered. If
2097 <constant>way</constant> is not set, then neither are
2098 <constant>way_</constant> and
2099 <constant>_way</constant>, and the invocation of
2100 <command>make</command> will build the <quote>normal
2101 way</quote>. If <constant>way</constant> is set, then the other
2102 two variables are set in sympathy. For example, if
2103 <constant>$(way)</constant> is “<literal>mp</literal>”,
2104 then <constant>way_</constant> is set to
2105 “<literal>mp_</literal>” and
2106 <constant>_way</constant> is set to
2107 “<literal>_mp</literal>”. These three variables are
2108 then used when constructing file names.</para>
2110 <para>So how does <command>make</command> ever get recursively
2111 invoked with <constant>way</constant> set? There are two ways
2112 in which this happens:</para>
2116 <para>For some (but not all) of the standard targets, when
2117 in a leaf sub-directory, <command>make</command> is
2118 recursively invoked for each way tag in
2119 <constant>$(WAYS)</constant>. You set
2120 <constant>WAYS</constant> in the
2121 <filename>Makefile</filename> to the list of way tags you
2122 want these targets built for. The mechanism here is very
2123 much like the recursive invocation of
2124 <command>make</command> in sub-directories (<xref
2125 linkend="sec-subdirs"/>). It is up to you to set
2126 <constant>WAYS</constant> in your
2127 <filename>Makefile</filename>; this is how you control what
2128 ways will get built.</para>
2132 <para>For a useful collection of targets (such as
2133 <filename>libHS_mp.a</filename>,
2134 <filename>Foo.mp_o</filename>) there is a rule which
2135 recursively invokes <command>make</command> to make the
2136 specified target, setting the <constant>way</constant>
2137 variable. So if you say <command>make
2138 Foo.mp_o</command> you should see a recursive
2139 invocation <command>make Foo.mp_o way=mp</command>,
2140 and <emphasis>in this recursive invocation the pattern rule
2141 for compiling a Haskell file into a <filename>.o</filename>
2142 file will match</emphasis>. The key pattern rules (in
2143 <filename>suffix.mk</filename>) look like this:
2145 <programlisting>%.$(way_)o : %.lhs
2146 $(HC) $(HC_OPTS) $< -o $@</programlisting>
2152 <para>You can invoke <command>make</command> with a
2153 particular <literal>way</literal> setting yourself, in order
2154 to build files related to a particular
2155 <literal>way</literal> in the current directory. eg.
2157 <screen>$ make way=p</screen>
2159 will build files for the profiling way only in the current
2166 <title>When the canned rule isn't right</title>
2168 <para>Sometimes the canned rule just doesn't do the right thing.
2169 For example, in the <literal>nofib</literal> suite we want the
2170 link step to print out timing information. The thing to do here
2171 is <emphasis>not</emphasis> to define
2172 <constant>HS_PROG</constant> or
2173 <constant>C_PROG</constant>, and instead define a special
2174 purpose rule in your own <filename>Makefile</filename>. By
2175 using different variable names you will avoid the canned rules
2176 being included, and conflicting with yours.</para>
2180 <sect1 id="building-docs">
2181 <title>Building the documentation</title>
2183 <sect2 id="pre-supposed-doc-tools">
2184 <title>Tools for building the Documentation</title>
2186 <para>The following additional tools are required if you want to
2187 format the documentation that comes with GHC:</para>
2192 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
2193 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
2196 <para>Much of our documentation is written in DocBook XML, instructions
2197 on installing and configuring the DocBook tools are below.</para>
2203 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
2204 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
2207 <para>A decent TeX distribution is required if you want to
2208 produce printable documentation. We recomment teTeX,
2209 which includes just about everything you need.</para>
2215 <indexterm><primary>Haddock</primary></indexterm>
2218 <para>Haddock is a Haskell documentation tool that we use
2219 for automatically generating documentation from the
2220 library source code. To build documentation for the
2221 libraries (<literal>$(GHC_TOP)/libraries</literal>) you
2222 should build and install Haddock. Haddock requires GHC
2230 <title>Installing the DocBook tools</title>
2233 <title>Installing the DocBook tools on Linux</title>
2235 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
2236 you probably have working DocBook tools already installed. The
2237 configure script should detect your setup and you're away.</para>
2239 <para>If you don't have DocBook tools installed, and you are
2240 using a system that can handle RPM packages, you can use <ulink
2241 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
2242 packages for your system. Search for the packages
2243 <literal>docbook-dtd</literal>,
2244 <literal>docbook-xsl-stylesheets</literal>,
2245 <literal>libxslt</literal>,
2246 <literal>libxml2</literal>,
2247 <literal>fop</literal>,
2248 <literal>xmltex</literal>, and
2249 <literal>dvips</literal>.</para>
2253 <title>Installing DocBook on FreeBSD</title>
2255 <para>On FreeBSD systems, the easiest way to get DocBook up
2256 and running is to install it from the ports tree or a
2257 pre-compiled package (packages are available from your local
2258 FreeBSD mirror site).</para>
2260 <para>To use the ports tree, do this:
2261 <screen>$ cd /usr/ports/textproc/docproj
2262 $ make install</screen>
2263 This installs the FreeBSD documentation project tools, which
2264 includes everything needed to format the GHC
2265 documentation.</para>
2269 <title>Installing from binaries on Windows</title>
2271 <para>Probably the fastest route to a working DocBook environment on
2272 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
2273 with the complete <literal>Doc</literal> category. If you are using
2274 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
2275 have to help <command>configure</command> a little bit: Set the
2276 environment variables <envar>XmllintCmd</envar> and
2277 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
2278 <command>xmllint</command> and <command>xsltproc</command>,
2279 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
2280 of the directory where the XSL stylesheets are installed,
2281 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
2284 <para>If you want to build HTML Help, you have to install the
2285 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
2286 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
2292 <title>Configuring the DocBook tools</title>
2294 <para>Once the DocBook tools are installed, the configure script
2295 will detect them and set up the build system accordingly. If you
2296 have a system that isn't supported, let us know, and we'll try
2301 <title>Building the documentation</title>
2303 <para>To build documentation in a certain format, you can
2304 say, for example,</para>
2306 <screen>$ make html</screen>
2308 <para>to build HTML documentation below the current directory.
2309 The available formats are: <literal>dvi</literal>,
2310 <literal>ps</literal>, <literal>pdf</literal>,
2311 <literal>html</literal>, and <literal>rtf</literal>. Note that
2312 not all documentation can be built in all of these formats: HTML
2313 documentation is generally supported everywhere, and DocBook
2314 documentation might support the other formats (depending on what
2315 other tools you have installed).</para>
2317 <para>All of these targets are recursive; that is, saying
2318 <literal>make html</literal> will make HTML docs for all the
2319 documents recursively below the current directory.</para>
2321 <para>Because there are many different formats that the DocBook
2322 documentation can be generated in, you have to select which ones
2323 you want by setting the <literal>XMLDocWays</literal> variable
2324 to a list of them. For example, in
2325 <filename>build.mk</filename> you might have a line:</para>
2327 <screen>XMLDocWays = html ps</screen>
2329 <para>This will cause the documentation to be built in the requested
2330 formats as part of the main build (the default is not to build
2331 any documentation at all).</para>
2335 <title>Installing the documentation</title>
2337 <para>To install the documentation, use:</para>
2339 <screen>$ make install-docs</screen>
2341 <para>This will install the documentation into
2342 <literal>$(datadir)</literal> (which defaults to
2343 <literal>$(prefix)/share</literal>). The exception is HTML
2344 documentation, which goes into
2345 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
2347 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
2348 to a list of formats, the <literal>install-docs</literal> target
2349 won't do anything for DocBook XML documentation.</para>
2355 <sect1 id="sec-porting-ghc">
2356 <title>Porting GHC</title>
2358 <para>This section describes how to port GHC to a currenly
2359 unsupported platform. To avoid confusion, when we say
2360 “architecture” we are referring to the processor, and
2361 we use the term “platform” to refer to the combination
2362 of architecture and operating system.</para>
2364 <para>There are two distinct porting scenarios:</para>
2368 <para>Your platform is already supported, but you want to
2369 compile up GHC using just a C compiler. This is a
2370 straightforward bootstrap from HC files, and is described in
2371 <xref linkend="sec-booting-from-hc" />.</para>
2375 <para>Your platform isn't supported by GHC. You will need to
2376 do an <emphasis>unregisterised bootstrap</emphasis>, proceed
2377 to <xref linkend="unregisterised-porting"/>.</para>
2381 <sect2 id="sec-booting-from-hc">
2382 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
2384 <indexterm><primary>building GHC from .hc files</primary></indexterm>
2385 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
2386 <indexterm><primary>porting GHC</primary></indexterm>
2388 <para>Bootstrapping GHC on a system without GHC already
2389 installed is achieved by taking the intermediate C files (known
2390 as HC files) from another GHC compilation, compiling them using gcc to
2391 get a working GHC.</para>
2393 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
2394 from C. We recommend using GHC 6.0.1 or
2395 later.</emphasis></para>
2397 <para>HC files are platform-dependent, so you have to get a set
2398 that were generated on <emphasis>the same platform</emphasis>.
2399 There may be some supplied on the GHC download page, otherwise
2400 you'll have to compile some up yourself.</para>
2402 <para>The following steps should result in a working GHC build
2403 with full libraries:</para>
2407 <para>Make a set of HC files. On an identical system with
2408 GHC already installed, get a GHC source tree and put the
2409 following in <literal>mk/build.mk</literal>:</para>
2412 SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files
2418 <para>Build GHC as normal, and then <literal>make
2419 hc-file-bundle Project=ghc</literal> to creates the tar file
2420 containing the hc files.</para>
2424 <para>On the target system, unpack the HC files on top of a
2425 fresh source tree (make sure the source tree version matches
2426 the version of the HC files <emphasis>exactly</emphasis>!).
2427 This will place matching <filename>.hc</filename> files next
2428 to the corresponding Haskell source
2429 (<filename>.hs</filename> or <filename>.lhs</filename>) in
2430 the compiler subdirectory <filename>ghc/compiler</filename>
2431 and in the libraries (subdirectories of
2432 <literal>libraries</literal>).</para>
2436 <para>The actual build process is fully automated by the
2437 <filename>hc-build</filename> script located in the
2438 <filename>distrib</filename> directory. If you eventually
2439 want to install GHC into the directory
2440 <replaceable>dir</replaceable>, the following
2441 command will execute the whole build process (it won't
2442 install yet):</para>
2444 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
2445 <indexterm><primary>--hc-build</primary></indexterm>
2447 <para>By default, the installation directory is
2448 <filename>/usr/local</filename>. If that is what you want,
2449 you may omit the argument to <filename>hc-build</filename>.
2450 Generally, any option given to <filename>hc-build</filename>
2451 is passed through to the configuration script
2452 <filename>configure</filename>. If
2453 <filename>hc-build</filename> successfully completes the
2454 build process, you can install the resulting system, as
2457 <screen>$ make install</screen>
2462 <sect2 id="unregisterised-porting">
2463 <title>Porting GHC to a new platform</title>
2465 <para>The first step in porting to a new platform is to get an
2466 <firstterm>unregisterised</firstterm> build working. An
2467 unregisterised build is one that compiles via vanilla C only.
2468 By contrast, a registerised build uses the following
2469 architecture-specific hacks for speed:</para>
2473 <para>Global register variables: certain abstract machine
2474 <quote>registers</quote> are mapped to real machine
2475 registers, depending on how many machine registers are
2477 <filename>ghc/includes/MachRegs.h</filename>).</para>
2481 <para>Assembly-mangling: when compiling via C, we feed the
2482 assembly generated by gcc though a Perl script known as the
2483 <firstterm>mangler</firstterm> (see
2484 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
2485 mangler rearranges the assembly to support tail-calls and
2486 various other optimisations.</para>
2490 <para>In an unregisterised build, neither of these hacks are
2491 used — the idea is that the C code generated by the
2492 compiler should compile using gcc only. The lack of these
2493 optimisations costs about a factor of two in performance, but
2494 since unregisterised compilation is usually just a step on the
2495 way to a full registerised port, we don't mind too much.</para>
2497 <para>You should go through this process even if your
2498 architecture is already has registerised support in GHC, but
2499 your OS currently isn't supported. In this case you probably
2500 won't need to port any of the architecture-specific parts of the
2501 code, and you can proceed straight from the unregisterised build
2502 to build a registerised compiler.</para>
2504 <para>Notes on GHC portability in general: we've tried to stick
2505 to writing portable code in most parts of the system, so it
2506 should compile on any POSIXish system with gcc, but in our
2507 experience most systems differ from the standards in one way or
2508 another. Deal with any problems as they arise - if you get
2509 stuck, ask the experts on
2510 <email>glasgow-haskell-users@haskell.org</email>.</para>
2512 <para>Lots of useful information about the innards of GHC is
2513 available in the <ulink
2514 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2515 Commentary</ulink>, which might be helpful if you run into some
2516 code which needs tweaking for your system.</para>
2519 <title>Cross-compiling to produce an unregisterised GHC</title>
2521 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
2522 later. If you need instructions for an earlier version of GHC, try
2523 to get hold of the version of this document that was current at the
2524 time. It should be available from the appropriate download page on
2526 url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
2528 <para>In this section, we explain how to bootstrap GHC on a
2529 new platform, using unregisterised intermediate C files. We
2530 haven't put a great deal of effort into automating this
2531 process, for two reasons: it is done very rarely, and the
2532 process usually requires human intervention to cope with minor
2533 porting issues anyway.</para>
2535 <para>The following step-by-step instructions should result in
2536 a fully working, albeit unregisterised, GHC. Firstly, you
2537 need a machine that already has a working GHC (we'll call this
2538 the <firstterm>host</firstterm> machine), in order to
2539 cross-compile the intermediate C files that we will use to
2540 bootstrap the compiler on the <firstterm>target</firstterm>
2545 <para>On the target machine:</para>
2549 <para>Unpack a source tree (preferably a released
2550 version). We will call the path to the root of this
2551 tree <replaceable>T</replaceable>.</para>
2555 <screen>$ cd <replaceable>T</replaceable>
2556 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
2558 <para>You might need to update
2559 <filename>configure.ac</filename> to recognise the new
2560 platform, and re-generate
2561 <filename>configure</filename> with
2562 <literal>autoreconf</literal>.</para>
2566 <screen>$ cd <replaceable>T</replaceable>/includes
2573 <para>On the host machine:</para>
2577 <para>Unpack a source tree (same released version). Call
2578 this directory <replaceable>H</replaceable>.</para>
2582 <screen>$ cd <replaceable>H</replaceable>
2583 $ ./configure</screen>
2588 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
2589 with the following contents:</para>
2591 <programlisting>GhcUnregisterised = YES
2592 GhcLibHcOpts = -O -fvia-C -keep-hc-files
2593 GhcRtsHcOpts = -keep-hc-files
2596 GhcWithNativeCodeGen = NO
2597 GhcWithInterpreter = NO
2598 GhcStage1HcOpts = -O
2599 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
2600 SRC_HC_OPTS += -H32m
2602 GhcWithSMP = NO</programlisting>
2607 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
2610 <para>change <literal>TARGETPLATFORM</literal>
2611 appropriately, and set the variables involving
2612 <literal>TARGET</literal> or
2613 <literal>Target</literal> to the correct values for
2614 the target platform. This step is necessary because
2615 currently <literal>configure</literal> doesn't cope
2616 with specifying different values for the
2617 <literal>--host</literal> and
2618 <literal>--target</literal> flags.</para>
2621 <para>copy <literal>LeadingUnderscore</literal>
2622 setting from target.</para>
2629 <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>
2631 <filename><replaceable>H</replaceable>/includes</filename>.
2632 Note that we are building on the host machine, using the
2633 target machine's configuration files. This
2634 is so that the intermediate C files generated here will
2635 be suitable for compiling on the target system.</para>
2639 <para>Touch the generated configuration files, just to make
2640 sure they don't get replaced during the build:</para>
2641 <screen>$ cd <filename><replaceable>H</replaceable></filename>/includes
2642 $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
2643 $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
2647 <para>Now build the compiler:</para>
2648 <screen>$ cd <replaceable>H</replaceable>/utils/mkdependC && make boot && make
2649 $ cd <replaceable>H</replaceable>/includes && make boot && make
2650 $ cd <replaceable>H</replaceable>/compat && make boot && make
2651 $ cd <replaceable>H</replaceable>/utils && make boot && make
2652 $ cd <replaceable>H</replaceable>/compiler && make boot && make
2653 $ cd <replaceable>H</replaceable>/rts && make boot && make</screen>
2654 <para>Don't worry if the build falls over in the RTS, we
2655 don't need the RTS yet.</para>
2659 <screen>$ cd <replaceable>H</replaceable>/libraries
2660 $ make boot && make</screen>
2664 <screen>$ cd <replaceable>H</replaceable>/compiler
2665 $ make boot stage=2 && make stage=2</screen>
2669 <screen>$ cd <replaceable>H</replaceable>/compat
2672 $ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
2673 $ cd <replaceable>H</replaceable>/utils
2675 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
2679 <screen>$ cd <replaceable>H</replaceable>
2680 $ make hc-file-bundle Project=Ghc</screen>
2685 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
2686 to <filename><replaceable>T</replaceable>/..</filename>.</para>
2692 <para>On the target machine:</para>
2694 <para>At this stage we simply need to bootstrap a compiler
2695 from the intermediate C files we generated above. The
2696 process of bootstrapping from C files is automated by the
2697 script in <literal>distrib/hc-build</literal>, and is
2698 described in <xref linkend="sec-booting-from-hc"/>.</para>
2700 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
2702 <para>However, since this is a bootstrap on a new machine,
2703 the automated process might not run to completion the
2704 first time. For that reason, you might want to treat the
2705 <literal>hc-build</literal> script as a list of
2706 instructions to follow, rather than as a fully automated
2707 script. This way you'll be able to restart the process
2708 part-way through if you need to fix anything on the
2711 <para>Don't bother with running
2712 <literal>make install</literal> in the newly
2713 bootstrapped tree; just use the compiler in that tree to
2714 build a fresh compiler from scratch, this time without
2715 booting from C files. Before doing this, you might want
2716 to check that the bootstrapped compiler is generating
2717 working binaries:</para>
2719 <screen>$ cat >hello.hs
2720 main = putStrLn "Hello World!\n"
2722 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
2724 Hello World!</screen>
2726 <para>Once you have the unregisterised compiler up and
2727 running, you can use it to start a registerised port. The
2728 following sections describe the various parts of the
2729 system that will need architecture-specific tweaks in
2730 order to get a registerised build going.</para>
2737 <title>Porting the RTS</title>
2739 <para>The following files need architecture-specific code for a
2740 registerised build:</para>
2744 <term><filename>ghc/includes/MachRegs.h</filename>
2745 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
2748 <para>Defines the STG-register to machine-register
2749 mapping. You need to know your platform's C calling
2750 convention, and which registers are generally available
2751 for mapping to global register variables. There are
2752 plenty of useful comments in this file.</para>
2756 <term><filename>ghc/includes/TailCalls.h</filename>
2757 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
2760 <para>Macros that cooperate with the mangler (see <xref
2761 linkend="sec-mangler"/>) to make proper tail-calls
2766 <term><filename>ghc/rts/Adjustor.c</filename>
2767 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
2771 <literal>foreign import "wrapper"</literal>
2773 <literal>foreign export dynamic</literal>).
2774 Not essential for getting GHC bootstrapped, so this file
2775 can be deferred until later if necessary.</para>
2779 <term><filename>ghc/rts/StgCRun.c</filename>
2780 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
2783 <para>The little assembly layer between the C world and
2784 the Haskell world. See the comments and code for the
2785 other architectures in this file for pointers.</para>
2789 <term><filename>ghc/rts/MBlock.h</filename>
2790 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
2792 <term><filename>ghc/rts/MBlock.c</filename>
2793 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
2796 <para>These files are really OS-specific rather than
2797 architecture-specific. In <filename>MBlock.h</filename>
2798 is specified the absolute location at which the RTS
2799 should try to allocate memory on your platform (try to
2800 find an area which doesn't conflict with code or dynamic
2801 libraries). In <filename>Mblock.c</filename> you might
2802 need to tweak the call to <literal>mmap()</literal> for
2809 <sect3 id="sec-mangler">
2810 <title>The mangler</title>
2812 <para>The mangler is an evil Perl-script
2813 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
2814 rearranges the assembly code output from gcc to do two main
2819 <para>Remove function prologues and epilogues, and all
2820 movement of the C stack pointer. This is to support
2821 tail-calls: every code block in Haskell code ends in an
2822 explicit jump, so we don't want the C-stack overflowing
2823 while we're jumping around between code blocks.</para>
2826 <para>Move the <firstterm>info table</firstterm> for a
2827 closure next to the entry code for that closure. In
2828 unregisterised code, info tables contain a pointer to the
2829 entry code, but in registerised compilation we arrange
2830 that the info table is shoved right up against the entry
2831 code, and addressed backwards from the entry code pointer
2832 (this saves a word in the info table and an extra
2833 indirection when jumping to the closure entry
2838 <para>The mangler is abstracted to a certain extent over some
2839 architecture-specific things such as the particular assembler
2840 directives used to herald symbols. Take a look at the
2841 definitions for other architectures and use these as a
2842 starting point.</para>
2846 <title>The splitter</title>
2848 <para>The splitter is another evil Perl script
2849 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
2850 cooperates with the mangler to support object splitting.
2851 Object splitting is what happens when the
2852 <option>-split-objs</option> option is passed to GHC: the
2853 object file is split into many smaller objects. This feature
2854 is used when building libraries, so that a program statically
2855 linked against the library will pull in less of the
2858 <para>The splitter has some platform-specific stuff; take a
2859 look and tweak it for your system.</para>
2863 <title>The native code generator</title>
2865 <para>The native code generator isn't essential to getting a
2866 registerised build going, but it's a desirable thing to have
2867 because it can cut compilation times in half. The native code
2868 generator is described in some detail in the <ulink
2869 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2870 commentary</ulink>.</para>
2876 <para>To support GHCi, you need to port the dynamic linker
2877 (<filename>$(GHC_TOP)/rts/Linker.c</filename>). The
2878 linker currently supports the ELF and PEi386 object file
2879 formats - if your platform uses one of these then things will
2880 be significantly easier. The majority of Unix platforms use
2881 the ELF format these days. Even so, there are some
2882 machine-specific parts of the ELF linker: for example, the
2883 code for resolving particular relocation types is
2884 machine-specific, so some porting of this code to your
2885 architecture and/or OS will probaly be necessary.</para>
2887 <para>If your system uses a different object file format, then
2888 you have to write a linker — good luck!</para>
2894 <sect1 id="sec-build-pitfalls">
2895 <title>Known pitfalls in building Glasgow Haskell
2897 <indexterm><primary>problems, building</primary></indexterm>
2898 <indexterm><primary>pitfalls, in building</primary></indexterm>
2899 <indexterm><primary>building pitfalls</primary></indexterm></title>
2902 WARNINGS about pitfalls and known “problems”:
2911 One difficulty that comes up from time to time is running out of space
2912 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
2913 compensate for the vagaries of different sysadmin approaches to temp
2915 <indexterm><primary>tmp, running out of space in</primary></indexterm>
2917 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
2918 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
2921 The best way around it is to say
2923 <programlisting>export TMPDIR=<dir></programlisting>
2925 in your <filename>build.mk</filename> file. Then GHC and the other
2926 tools will use the appropriate directory in all cases.
2934 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
2935 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
2943 When compiling via C, you'll sometimes get “warning: assignment from
2944 incompatible pointer type” out of GCC. Harmless.
2951 Similarly, <command>ar</command>chiving warning messages like the following are not
2954 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
2955 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
2964 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
2965 get an “Out of heap space” error message. These can vary with the
2966 vagaries of different systems, it seems. The solution is simple:
2973 If you're compiling with GHC 4.00 or later, then the
2974 <emphasis>maximum</emphasis> heap size must have been reached. This
2975 is somewhat unlikely, since the maximum is set to 64M by default.
2976 Anyway, you can raise it with the
2977 <option>-optCrts-M<size></option> flag (add this flag to
2978 <constant><module>_HC_OPTS</constant>
2979 <command>make</command> variable in the appropriate
2980 <filename>Makefile</filename>).
2987 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
2996 and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about
2997 <constant><module>_HC_OPTS</constant>.)
2999 Alternatively, just cut to the chase:
3001 <screen>$ cd ghc/compiler
3002 $ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
3010 If you try to compile some Haskell, and you get errors from GCC about
3011 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3012 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3014 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3015 this bug also suggests that you have an old GCC.
3023 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3026 <screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3027 $ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3029 ? # or, on some machines: ar s $i
3033 We'd be interested to know if this is still necessary.
3041 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3042 a bit from one Unix to another. One particular gotcha is macro calls
3046 <programlisting>SLIT("Hello, world")</programlisting>
3049 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3050 arguments, so you get
3053 <screen>:731: macro `SLIT' used with too many (2) args</screen>
3056 Alas, <command>cpp</command> doesn't tell you the offending file!
3058 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3069 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
3071 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
3072 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
3075 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
3077 <para> The build system is built around Unix-y makefiles. Because it's not native,
3078 the Windows situation for building GHC is particularly confusing. This section
3079 tries to clarify, and to establish terminology.</para>
3081 <sect3 id="ghc-mingw"><title>MinGW</title>
3083 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
3084 is a collection of header
3085 files and import libraries that allow one to use <command>gcc</command> and produce
3086 native Win32 programs that do not rely on any third-party DLLs. The
3087 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
3088 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
3092 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
3097 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
3099 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
3100 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
3101 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>.
3102 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
3103 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
3107 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
3108 compile code that has access to all of Posix. The price is that the executables must be
3109 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
3110 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
3111 does not change, but the implementation certainly does. Even the interfaces to functions
3112 it exports seem to change occasionally. </para>
3116 MSYS is a fork of the Cygwin tree, so they
3117 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
3118 through fewer layers, so MSYS is quite a bit faster too.
3121 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
3122 compile binaries that run with no DLL support, on any Win32 system.
3123 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
3124 <command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the
3125 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
3127 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
3128 <command>ssh</command> and so on),
3129 not by programs compiled under MSYS.
3137 <sect3><title>Targeting MinGW</title>
3139 <para>We want GHC to compile programs that work on any Win32 system. Hence:
3142 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
3143 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
3144 will work on any system, but it also means that the programs GHC compiles do not have access
3145 to all of Posix. In particular, they cannot import the (Haskell) Posix
3146 library; they have to do
3147 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
3148 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
3152 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
3153 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
3156 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
3157 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
3158 that targets Cygwin instead. The up-side of GHC-cygwin is
3159 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
3160 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
3163 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
3164 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
3165 GHC; both work fine, though MSYS is rather lighter weight.</para>
3167 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
3168 uses the <command>gcc</command> that you specify using the
3169 <option>--with-gcc</option> flag when you run
3170 <command>configure</command> (see below).
3171 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
3172 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
3173 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
3174 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
3175 used to glom together .o files into a bigger .o file, or a .a file,
3176 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
3177 Cygwin and MinGW use the same .o file format. So its ok.
3181 <sect3><title> File names </title>
3183 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
3187 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
3188 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
3190 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
3191 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
3192 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
3194 <programlisting>foogle -B/c/tmp/baz</programlisting>
3195 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
3199 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
3201 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
3207 <sect3><title>Crippled <command>ld</command></title>
3210 It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
3211 limit of 32kbytes on its command line. Especially when using split object
3212 files, the make system can emit calls to <command>ld</command> with thousands
3213 of files on it. Then you may see something like this:
3215 (cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
3216 /bin/sh: /mingw/bin/ld: Invalid argument
3218 The solution is either to switch off object file splitting (set
3219 <option>SplitObjs</option> to <literal>NO</literal> in your
3220 <filename>build.mk</filename>),
3221 or to make the module smaller.
3225 <sect3><title>Host System vs Target System</title>
3228 In the source code you'll find various ifdefs looking like:
3229 <programlisting>#ifdef mingw32_HOST_OS
3231 #endif</programlisting>
3233 <programlisting>#ifdef mingw32_TARGET_OS
3235 #endif</programlisting>
3236 These macros are set by the configure script (via the file config.h).
3237 Which is which? The criterion is this. In the ifdefs in GHC's source code:
3240 <para>The "host" system is the one on which GHC itself will be run.</para>
3243 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
3246 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
3247 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
3254 <sect2><title>Wrapper scripts</title>
3257 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
3258 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
3259 GHC itself as an example:
3262 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
3263 paths to the front of the source file <filename>ghc.sh</filename>,
3264 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
3265 where to find its supporting files.
3269 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
3270 native Windows shell <command>cmd</command> (e.g. limits on the length
3271 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
3272 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
3273 and from that figures out where the supporting files are.
3276 (You can find the layout of GHC's supporting files in the
3277 section "Layout of installed files" of Section 2 of the GHC user guide.)
3280 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
3281 execute a program that has just been built in a build tree. The difference is that the
3282 layout of the supporting files is different.
3283 In this case, whether on Windows or Unix, we always use a shell script. This works OK
3284 on Windows because the script is executed by MSYS or Cygwin, which don't have the
3285 shortcomings of the native Windows <command>cmd</command> shell.
3292 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
3295 This section gives detailed instructions for how to build
3296 GHC from source on your Windows machine. Similar instructions for
3297 installing and running GHC may be found in the user guide. In general,
3298 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3301 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
3302 before reading section.
3303 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
3304 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
3307 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
3310 MSYS is a lightweight alternative to Cygwin.
3311 You don't need MSYS to <emphasis>use</emphasis> GHC,
3312 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
3313 Here's how to install MSYS.
3316 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
3317 download the following (of course, the version numbers will differ):
3319 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
3321 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
3322 This provides <command>make</command>, <command>autoconf</command>,
3323 <command>ssh</command> and probably more besides.
3326 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
3330 Set the following environment variables
3332 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
3333 <literal>c:/msys/1.0/local/bin</literal>
3334 to your path. (Of course, the version number may differ.)
3335 MSYS mounts the former as both <literal>/bin</literal> and
3336 <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
3339 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
3340 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
3343 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
3346 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
3350 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
3357 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
3358 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
3359 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
3360 file has too-liberal permissinos.
3365 <para>Here are some points to bear in mind when using MSYS:
3367 <listitem> <para> MSYS does some kind of special magic to binaries stored in
3368 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
3369 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
3370 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
3371 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
3372 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
3374 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
3378 Win32 has a <command>find</command> command which is not the same as MSYS's find.
3379 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
3380 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
3381 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
3382 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
3386 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
3387 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
3388 bzip'd dump.</para></listitem>
3394 <sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
3396 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
3397 The installation process is straightforward; we install it in
3398 <filename>c:/cygwin</filename>.</para>
3400 You must install enough Cygwin <emphasis>packages</emphasis> to support
3401 building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
3403 <listitem><para>The direct, but laborious way is to
3404 select all of the following packages in the installation dialogue:
3405 <command>cvs</command>,
3406 <command>openssh</command>,
3407 <command>autoconf</command>,
3408 <command>binutils</command> (includes ld and (I think) ar),
3409 <command>gcc</command>,
3410 <command>flex</command>,
3411 <command>make</command>.
3412 To see thse packages,
3413 click on the "View" button in the "Select Packages"
3414 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
3415 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
3419 <listitem><para>The clever way is to point the Cygwin installer at the
3420 <command>ghc-depends</command> package, which is kept at <ulink
3421 url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
3422 When the Cygwin installer asks you to "Choose a Download Site", choose one of
3424 offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
3425 "User URL" box and click "Add"; now two sites are selected. (The Cygwin
3426 installer remembers this for next time.)
3427 Click "Next".</para>
3428 <para>In the "Select Packages" dialogue box that follows, click the "+" sign by
3429 "Devel", scroll down to the end of the "Devel" packages, and choose
3430 <command>ghc-depends</command>.
3431 The package <command>ghc-depends</command> will not actually install anything itself,
3432 but forces additional packages to be added by the Cygwin installer.
3438 <para> Now set the following user environment variables:
3441 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
3442 <constant>PATH</constant></para></listitem>
3446 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
3447 don't do this you get very weird messages when you type
3448 <command>make</command>, such as:
3449 <screen>/c: /c: No such file or directory</screen>
3453 <listitem><para> Set <constant>SHELL</constant> to
3454 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
3455 <constant>SHELL</constant> is what you get.
3458 <listitem><para> Set <constant>HOME</constant> to point to your
3459 home directory. This is where, for example,
3460 <command>bash</command> will look for your <filename>.bashrc</filename>
3461 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
3466 <para>Here are some things to be aware of when using Cygwin:
3468 <listitem> <para>Cygwin doesn't deal well with filenames that include
3469 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
3473 <listitem> <para> Cygwin implements a symbolic link as a text file with some
3474 magical text in it. So other programs that don't use Cygwin's
3475 I/O libraries won't recognise such files as symlinks.
3476 In particular, programs compiled by GHC are meant to be runnable
3477 without having Cygwin, so they don't use the Cygwin library, so
3478 they don't recognise symlinks.
3482 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
3483 which apply to Cygwin too.
3488 Some script files used in the make system start with "<command>#!/bin/perl</command>",
3489 (and similarly for <command>sh</command>). Notice the hardwired path!
3490 So you need to ensure that your <filename>/bin</filename> directory has at least
3491 <command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
3492 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
3493 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
3494 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
3495 (You can discover where your Cygwin
3496 root directory <filename>/</filename> is by typing <command>mount</command>.)
3497 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
3498 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
3499 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
3505 By default, cygwin provides the command shell <filename>ash</filename>
3506 as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
3507 saw build-system problems that turned out to be due to bugs in <filename>ash</filename>
3508 (to do with quoting and length of command lines). On the other hand <filename>bash</filename> seems
3510 If this happens to you (which it shouldn't), in <filename>cygwin/bin</filename>
3511 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
3512 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
3513 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
3514 you can't rename a running program!
3523 <sect2 id="configure-ssh"><title>Configuring SSH</title>
3525 <para><command>ssh</command> comes with both Cygwin and MSYS.
3526 (Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
3527 in the Cygwin list of packages; or use the <command>ghc-depends</command>
3528 package -- see <xref linkend="install-cygwin"/>.)</para>
3530 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
3534 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
3535 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
3536 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
3537 and run it as follows:
3538 <screen>c:\tmp> set CYGWIN32=tty
3539 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
3542 <listitem><para> (Cygwin-only problem, I think.)
3543 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
3544 To determine your home directory <command>ssh</command> first looks in
3545 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
3546 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
3547 the setting of the environment variable $HOME</emphasis>. If the home directory is
3548 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
3549 <screen>ssh -v cvs.haskell.org</screen>
3550 which makes <command>ssh</command> print out information about its activity.
3552 <para> You can fix this problem, either by correcting the home-directory field in
3553 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
3554 you do that, <command>ssh</command> uses the $HOME environment variable instead.
3560 <para>To protect your
3561 <literal>.ssh</literal> from access by anyone else,
3562 right-click your <literal>.ssh</literal> directory, and
3563 select <literal>Properties</literal>. If you are not on
3564 the access control list, add yourself, and give yourself
3565 full permissions (the second panel). Remove everyone else
3566 from the access control list. Don't leave them there but
3567 deny them access, because 'they' may be a list that
3568 includes you!</para>
3572 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
3573 you to have Unix permissions 600 (read/write for owner only)
3574 on the <literal>.ssh/identity</literal> file, else it
3575 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
3576 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
3577 The solution seems to be to set the $CYGWIN environment
3578 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
3579 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
3580 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
3587 <sect2><title>Other things you need to install</title>
3589 <para>You have to install the following other things to build GHC, listed below.</para>
3591 <para>On Windows you often install executables in directories with spaces, such as
3592 "<filename>Program Files</filename>". However, the <literal>make</literal> system doesn't
3593 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
3594 to put binaries for all tools in places with no spaces in their path.
3595 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
3596 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
3597 provided they are in your path.
3601 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
3602 This is what you will use to compile GHC. Add it in your
3603 <constant>PATH</constant>: the installer tells you the path element
3604 you need to add upon completion.
3610 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
3611 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
3612 build it from the source distribution using
3613 <screen>$ ./configure
3615 $ make install</screen>
3616 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
3618 Make sure the installation directory is in your
3619 <constant>PATH</constant>.
3624 <para>Install an executable Alex. This can be done by building from the
3625 source distribution in the same way as Happy. Sources are
3626 available from <ulink
3627 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
3631 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
3632 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
3633 Just pick up a mingw bundle at
3634 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
3635 We install it in <filename>c:/mingw</filename>.
3638 <para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
3639 <command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
3643 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
3644 They are only going to get used by explicit access (via the --with-gcc flag you
3645 give to <command>configure</command> later). If you do add them to your path
3646 you are likely to get into a mess because their names overlap with Cygwin
3648 On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
3649 (and perhaps one or two other things) in your path. The Cygwin ones are fine,
3650 but you must have them; hence needing the Cygwin binutils package.
3656 <para>We use <command>emacs</command> a lot, so we install that too.
3657 When you are in <filename>$(GHC_TOP)/compiler</filename>, you can use
3658 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
3659 <filename>$(GHC_TOP)/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
3660 The most convenient way to do this is by going <literal>make boot</literal> in <filename>$(GHC_TOP)/ghc</filename>.
3661 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
3662 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
3667 <para>You might want to install GLUT in your MSYS/Cygwin
3668 installation, otherwise the GLUT package will not be built with
3673 <para> Finally, check out a copy of GHC sources from
3674 the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
3680 <sect2><title>Building GHC</title>
3683 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
3684 the bullets below only tell
3685 you about Windows-specific wrinkles.</para>
3689 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
3690 you'll get an error when you run <filename>./configure</filename>:
3693 creating mk/config.h
3694 mk/config.h is unchanged
3696 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
3697 ./configure: ./configure: No such file or directory
3698 configure: error: ./configure failed for ghc</screen>
3702 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
3703 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
3705 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
3706 Solution: delete <filename>configure</filename> first.
3711 After <command>autoreconf</command> run <command>./configure</command> in
3712 <filename>$(GHC_TOP)/</filename> thus:
3714 <screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
3715 This is the point at which you specify that you are building GHC-mingw
3716 (see <xref linkend="ghc-mingw"/>). </para>
3718 <para> Both these options are important! It's possible to get into
3719 trouble using the wrong C compiler!</para>
3721 Furthermore, it's <emphasis>very important</emphasis> that you specify a
3722 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
3723 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
3724 understand a Cygwin path. For example, if you
3725 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
3726 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
3727 time it tries to invoke it. Worse, the failure comes with
3728 no error message whatsoever. GHC simply fails silently when first invoked,
3729 typically leaving you with this:
3730 <screen>make[4]: Leaving directory `/cygdrive/e/ghc-stage1/ghc/rts/gmp'
3731 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
3732 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
3733 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
3734 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
3735 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
3736 -optc-fomit-frame-pointer -O2 -static
3737 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
3738 make[2]: *** [Adjustor.o] Error 1
3739 make[1]: *** [all] Error 1
3740 make[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc'
3741 make: *** [all] Error 1</screen>
3746 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
3747 you'll have to do something more like:
3748 <screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
3753 If you are paranoid, delete <filename>config.cache</filename> if it exists.
3754 This file occasionally remembers out-of-date configuration information, which
3755 can be really confusing.
3759 <listitem><para> You almost certainly want to set
3760 <programlisting>SplitObjs = NO</programlisting>
3761 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
3762 This tells the build system not to split each library into a myriad of little object files, one
3763 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
3764 it dramatically increases the time taken to build the libraries in the first place.
3768 <listitem><para> Do not attempt to build the documentation.
3769 It needs all kinds of wierd Jade stuff that we haven't worked out for
3770 Win32.</para></listitem>
3775 <sect2><title>A Windows build log using Cygwin</title>
3777 <para>Here is a complete, from-scratch, log of all you need to build GHC using
3778 Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
3779 choices, but it gives a single path that works.</para>
3780 <programlisting>- Install some editor (vim, emacs, whatever)
3782 - Install cygwin (http://www.cygwin.com)
3783 ; i used 1.5.16-1, installed in c:\cygwin
3785 Choose a Download Source:
3786 select 'download from internet';
3787 Select Root Install Directory:
3788 root dir: c:\cygwin;
3789 install for: all users;
3790 default file type: unix
3791 Select Local Package Directory
3792 choose a spare temporary home
3793 Select Your Internet Connection
3795 Choose a Download Site
3796 Choose your preferred main mirror and
3797 Add 'http://www.haskell.org/ghc/cygwin'
3799 In addition to 'Base' (default install),
3800 select 'Devel->ghc-depends'
3802 - Install mingw (http://www.mingw.org/)
3803 ; i used MinGW-3.1.0-1.exe
3804 ; installed in c:\mingw
3805 - you probably want to add GLUT
3806 ; (http://www.xmission.com/~nate/glut.html)
3807 ; i used glut-3.7.3-mingw32.tar
3809 - Get recent binary snapshot of ghc-6.4.1 for mingw
3810 ; (http://www.haskell.org/ghc/dist/stable/dist/)
3812 - add C:\ghc\ghc-6.4.1\bin to %PATH%
3813 (Start->Control Panel->System->Advanced->Environment Variables)
3815 - Get darcs version of ghc
3816 ; also, subscribe to cvs-all@haskell.org, or follow the mailing list
3817 ; archive, in case you checkout a version with problems
3818 ; http://www.haskell.org//pipermail/cvs-all/
3819 - mkdir c:/ghc-build; cd c:/ghc-build
3820 ; (or whereever you want your darcs tree to be)
3821 - darcs get http://darcs.haskell.org/ghc
3823 - chmod +x darcs-all
3826 - Build ghc, using cygwin and mingw, targetting mingw
3827 - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
3828 ; for haddock, alex, happy (*)
3829 - export PATH=/cygdrive/c/mingw/bin:$PATH
3830 ; without, we pick up some cygwin tools at best!
3832 ; (if you aren't there already)
3834 - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
3835 ; we use cygwin, but build for windows
3836 - cp mk/build.mk.sample mk/build.mk
3838 add line: SplitObjs = NO
3839 (MSYS seems slow when there are zillions of object files)
3840 uncomment line: BuildFlavour = perf
3841 (or BuildFlavour = devel, if you are doing development)
3842 add line: BIN_DIST=1
3843 - make 2>&1 | tee make.log
3844 ; always useful to have a log around
3846 - Package up binary distribution
3847 - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
3848 ; always useful to have a log around
3850 - chmod +x ../distrib/prep-bin-dist-mingw
3851 ; if you're happy with the script's contents (*)
3852 - ../distrib/prep-bin-dist-mingw
3853 ; then tar up, unpack where wanted, and enjoy</programlisting>
projects / ghc-hetmet.git / blob