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>Which version of GHC you need will depend on the
169 packages you intend to build. GHC itself will normally
170 build using one of several older versions of itself - check
171 the announcement or release notes for details.</para>
177 <indexterm><primary>pre-supposed: Perl</primary></indexterm>
178 <indexterm><primary>Perl, pre-supposed</primary></indexterm>
181 <para><emphasis>You have to have Perl to proceed!</emphasis>
182 Perl version 5 at least is required. GHC has been known to
183 tickle bugs in Perl, so if you find that Perl crashes when
184 running GHC try updating (or downgrading) your Perl
185 installation. Versions of Perl before 5.6 have been known to have
186 various bugs tickled by GHC, so the configure script
187 will look for version 5.6 or later.</para>
189 <para>For Win32 platforms, you should use the binary
190 supplied in the InstallShield (copy it to
191 <filename>/bin</filename>). The Cygwin-supplied Perl seems
194 <para>Perl should be put somewhere so that it can be invoked
195 by the <literal>#!</literal> script-invoking
196 mechanism. The full pathname may need to be less than 32
197 characters long on some systems.</para>
202 <term>GNU C (<command>gcc</command>)
203 <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
204 <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
207 <para>Most GCC versions should work with the most recent GHC
208 sources. Expect trouble if you use a recent GCC with
209 an older GHC, though (trouble in the form of mis-compiled code,
210 link errors, and errors from the <literal>ghc-asm</literal>
213 <para>If your GCC dies with “internal error” on
214 some GHC source file, please let us know, so we can report
215 it and get things improved. (Exception: on x86
216 boxes—you may need to fiddle with GHC's
217 <option>-monly-N-regs</option> option; see the User's
224 <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
227 <para>The GHC build system makes heavy use of features
228 specific to GNU <command>make</command>, so you must have
229 this installed in order to build GHC.</para>
231 <para>NB. it has been reported that version 3.79 no longer
232 works to build GHC, and 3.80 is required.</para>
237 <term><ulink url="http://www.haskell.org/happy">Happy</ulink>
238 <indexterm><primary>Happy</primary></indexterm>
241 <para>Happy is a parser generator tool for Haskell, and is
242 used to generate GHC's parsers.</para>
244 <para>If you start from a source tarball of GHC (i.e. not a darcs
245 checkout), then you don't need Happy, because we supply the
246 pre-processed versions of the Happy parsers. If you intend to
247 modify the compiler and/or you're using a darcs checkout, then you
250 <para>Happy version 1.15 is currently required to build GHC.
251 Grab a copy from <ulink
252 url="http://www.haskell.org/happy/">Happy's Web
259 <indexterm><primary>Alex</primary></indexterm>
262 <para>Alex is a lexical-analyser generator for Haskell,
263 which GHC uses to generate its lexer.</para>
265 <para>Like Happy, you don't need Alex if you're building GHC from a
266 source tarball, but you do need it if you're modifying GHC and/or
267 building a darcs checkout.</para>
270 written in Haskell and is a project in the darcs repository.
271 Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
278 <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
279 <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
282 <para>GNU autoconf is needed if you intend to build from the
283 darcs sources, it is <emphasis>not</emphasis> needed if you
284 just intend to build a standard source distribution.</para>
286 <para>Version 2.52 or later of the autoconf package is required.
287 NB. version 2.13 will no longer work, as of GHC version
290 <para><command>autoreconf</command> (from the autoconf package)
291 recursively builds <command>configure</command> scripts from
292 the corresponding <filename>configure.ac</filename> and
293 <filename>aclocal.m4</filename> files. If you modify one of
294 the latter files, you'll need <command>autoreconf</command> to
295 rebuild the corresponding <filename>configure</filename>.</para>
300 <term><command>sed</command>
301 <indexterm><primary>pre-supposed: sed</primary></indexterm>
302 <indexterm><primary>sed, pre-supposed</primary></indexterm>
305 <para>You need a working <command>sed</command> if you are
306 going to build from sources. The build-configuration stuff
307 needs it. GNU sed version 2.0.4 is no good! It has a bug
308 in it that is tickled by the build-configuration. 2.0.5 is
309 OK. Others are probably OK too (assuming we don't create too
310 elaborate configure scripts.)</para>
315 <sect2 id="pre-supposed-gph-tools">
316 <title>Tools for building parallel GHC (GPH)</title>
321 <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
322 <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
325 <para>PVM is the Parallel Virtual Machine on which
326 Parallel Haskell programs run. (You only need this if you
327 plan to run Parallel Haskell. Concurrent Haskell, which
328 runs concurrent threads on a uniprocessor doesn't need
329 it.) Underneath PVM, you can have (for example) a network
330 of workstations (slow) or a multiprocessor box
333 <para>The current version of PVM is 3.3.11; we use 3.3.7.
334 It is readily available on the net; I think I got it from
335 <literal>research.att.com</literal>, in
336 <filename>netlib</filename>.</para>
338 <para>A PVM installation is slightly quirky, but easy to
339 do. Just follow the <filename>Readme</filename>
345 <term><command>bash</command>:
346 <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
349 <para>Sadly, the <command>gr2ps</command> script, used to
350 convert “parallelism profiles” to PostScript,
351 is written in Bash (GNU's Bourne Again shell). This bug
352 will be fixed (someday).</para>
357 <para>More tools are required if you want to format the
358 documentation that comes with GHC. See <xref
359 linkend="building-docs"/>.</para>
363 <sect1 id="sec-building-from-source">
364 <title>Building from source</title>
366 <indexterm><primary>Building from source</primary></indexterm>
367 <indexterm><primary>Source, building from</primary></indexterm>
369 <para>“I just want to build it!”</para>
371 <para>No problem. This recipe should build and install a working GHC with
372 all the default settings. (unless you're
373 on Windows, in which case go to <xref linkend="winbuild" />).</para>
375 <screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
379 $ make install</screen>
381 <para>For GHC, this will do a 2-stage bootstrap build of the
382 compiler, with profiling libraries, and install the
383 results in the default location (under <filename>/usr/local</filename> on
384 Unix, for example).</para>
386 <para>The <literal>configure</literal> script is a standard GNU
387 <literal>autoconf</literal> script, and accepts the usual options for
388 changing install locations and the like. Run
389 <literal>./configure --help</literal> for a list of options.</para>
391 <para>If you want to do anything at all non-standard, or you
392 want to do some development, read on...</para>
395 <sect1 id="quick-start">
396 <title>Quick start for GHC developers</title>
398 <para>This section is a copy of the file
399 <literal>HACKING</literal> from the GHC source tree. It describes
400 how to get started with setting up your build tree for developing GHC
401 or its libraries, and how to start building.</para>
408 <sect1 id="sec-working-with-the-build-system">
409 <title>Working with the build system</title>
411 <para>This rest of this guide is intended for duffers like me, who
412 aren't really interested in Makefiles and systems configurations,
413 but who need a mental model of the interlocking pieces so that
414 they can make them work, extend them consistently when adding new
415 software, and lay hands on them gently when they don't
419 <title>History</title>
421 <para>First, a historical note. The GHC build system used to be
422 called "fptools": a generic build system used to build multiple
423 projects (GHC, Happy, GreenCard, H/Direct, etc.). It had a
424 concept of the generic project-independent parts, and
425 project-specific parts that resided in a project
428 <para>Nowadays, most of these other projects are using <ulink
429 url="http://www.haskell.org/cabal/">Cabal</ulink>, or have faded
430 away, and GHC is the only regular user of the fptools build
431 system. We decided therefore to simplify the situation for
432 developers, and specialise the build system for GHC. This
433 resulted in a simpler organisation of the source tree and the
434 build system, which hopefully makes the whole thing easier to
437 <para>You might find old comments that refer to "projects" or
438 "fptools" in the documentation and/or source; please let us know
443 <title>Build trees</title>
444 <indexterm><primary>build trees</primary></indexterm>
445 <indexterm><primary>link trees, for building</primary></indexterm>
447 <para>If you just want to build the software once on a single
448 platform, then your source tree can also be your build tree, and
449 you can skip the rest of this section.</para>
451 <para>We often want to build multiple versions of our software
452 for different architectures, or with different options
453 (e.g. profiling). It's very desirable to share a single copy of
454 the source code among all these builds.</para>
456 <para>So for every source tree we have zero or more
457 <emphasis>build trees</emphasis>. Each build tree is initially
458 an exact copy of the source tree, except that each file is a
459 symbolic link to the source file, rather than being a copy of
460 the source file. There are “standard” Unix
461 utilities that make such copies, so standard that they go by
463 <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
464 <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
465 are two (If you don't have either, the source distribution
466 includes sources for the X11
467 <command>lndir</command>—check out
468 <filename>utils/lndir</filename>). See <xref
469 linkend="sec-storysofar"/> for a typical invocation.</para>
471 <para>The build tree does not need to be anywhere near the
472 source tree in the file system. Indeed, one advantage of
473 separating the build tree from the source is that the build tree
474 can be placed in a non-backed-up partition, saving your systems
475 support people from backing up untold megabytes of
476 easily-regenerated, and rapidly-changing, gubbins. The golden
477 rule is that (with a single exception—<xref
478 linkend="sec-build-config"/>) <emphasis>absolutely everything in
479 the build tree is either a symbolic link to the source tree, or
480 else is mechanically generated</emphasis>. It should be
481 perfectly OK for your build tree to vanish overnight; an hour or
482 two compiling and you're on the road again.</para>
484 <para>You need to be a bit careful, though, that any new files
485 you create (if you do any development work) are in the source
486 tree, not a build tree!</para>
488 <para>Remember, that the source files in the build tree are
489 <emphasis>symbolic links</emphasis> to the files in the source
490 tree. (The build tree soon accumulates lots of built files like
491 <filename>Foo.o</filename>, as well.) You can
492 <emphasis>delete</emphasis> a source file from the build tree
493 without affecting the source tree (though it's an odd thing to
494 do). On the other hand, if you <emphasis>edit</emphasis> a
495 source file from the build tree, you'll edit the source-tree
496 file directly. (You can set up Emacs so that if you edit a
497 source file from the build tree, Emacs will silently create an
498 edited copy of the source file in the build tree, leaving the
499 source file unchanged; but the danger is that you think you've
500 edited the source file whereas actually all you've done is edit
501 the build-tree copy. More commonly you do want to edit the
504 <para>Like the source tree, the top level of your build tree
505 must be (a linked copy of) the root directory of the GHC source
506 tree.. Inside Makefiles, the root of your build tree is called
507 <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
508 In the rest of this document path names are relative to
509 <constant>$(FPTOOLS_TOP)</constant> unless
510 otherwise stated. For example, the file
511 <filename>mk/target.mk</filename> is actually
512 <filename>$(FPTOOLS_TOP)/mk/target.mk</filename>.</para>
515 <sect2 id="sec-build-config">
516 <title>Getting the build you want</title>
518 <para>When you build GHC you will be compiling code on a
519 particular <emphasis>host platform</emphasis>, to run on a
520 particular <emphasis>target platform</emphasis> (usually the
522 platform)<indexterm><primary>platform</primary></indexterm>.
523 The difficulty is that there are minor differences between
524 different platforms; minor, but enough that the code needs to be
525 a bit different for each. There are some big differences too:
526 for a different architecture we need to build GHC with a
527 different native-code generator.</para>
529 <para>There are also knobs you can turn to control how the
530 software is built. For example, you might want to build GHC
531 optimised (so that it runs fast) or unoptimised (so that you can
532 compile it fast after you've modified it. Or, you might want to
533 compile it with debugging on (so that extra consistency-checking
534 code gets included) or off. And so on.</para>
536 <para>All of this stuff is called the
537 <emphasis>configuration</emphasis> of your build. You set the
538 configuration using a three-step process.</para>
542 <term>Step 1: get ready for configuration.</term>
544 <para>NOTE: if you're starting from a source distribution,
545 rather than darcs sources, you can skip this step.</para>
547 <para>Change directory to
548 <constant>$(FPTOOLS_TOP)</constant> and
549 issue the command</para>
550 <screen>$ autoreconf</screen>
551 <indexterm><primary>autoreconf</primary></indexterm>
552 <para>(with no arguments). This GNU program (recursively) converts
553 <filename>$(FPTOOLS_TOP)/configure.ac</filename> and
554 <filename>$(FPTOOLS_TOP)/aclocal.m4</filename>
555 to a shell script called
556 <filename>$(FPTOOLS_TOP)/configure</filename>.
557 If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
558 then delete the latter and try again. Note that you must use <command>autoreconf</command>,
559 and not the old <command>autoconf</command>! If you erroneously use the latter, you'll get
560 a message like "No rule to make target 'mk/config.h.in'".
563 <para>Some parts of the source tree, particularly
564 libraries, have their own configure script.
565 <command>autoreconf</command> takes care of that, too, so all you have
566 to do is calling <command>autoreconf</command> in the top-level directory
567 <filename>$(FPTOOLS_TOP)</filename>.</para>
569 <para>These steps are completely platform-independent; they just mean
570 that the human-written files (<filename>configure.ac</filename> and
571 <filename>aclocal.m4</filename>) can be short, although the resulting
572 files (the <command>configure</command> shell scripts and the C header
573 template <filename>mk/config.h.in</filename>) are long.</para>
578 <term>Step 2: system configuration.</term>
580 <para>Runs the newly-created <command>configure</command>
583 <screen>$ ./configure <optional><parameter>args</parameter></optional></screen>
585 <para><command>configure</command>'s mission is to scurry
586 round your computer working out what architecture it has,
587 what operating system, whether it has the
588 <function>vfork</function> system call, where
589 <command>tar</command> is kept, whether
590 <command>gcc</command> is available, where various obscure
591 <literal>#include</literal> files are, whether it's a
592 leap year, and what the systems manager had for lunch. It
593 communicates these snippets of information in two
600 <filename>mk/config.mk.in</filename><indexterm><primary>config.mk.in</primary></indexterm>
602 <filename>mk/config.mk</filename><indexterm><primary>config.mk</primary></indexterm>,
603 substituting for things between
604 “<literal>@</literal>” brackets. So,
605 “<literal>@HaveGcc@</literal>” will be
606 replaced by “<literal>YES</literal>” or
607 “<literal>NO</literal>” depending on what
608 <command>configure</command> finds.
609 <filename>mk/config.mk</filename> is included by every
610 Makefile (directly or indirectly), so the
611 configuration information is thereby communicated to
612 all Makefiles.</para>
617 <filename>mk/config.h.in</filename><indexterm><primary>config.h.in</primary></indexterm>
619 <filename>mk/config.h</filename><indexterm><primary>config.h</primary></indexterm>.
620 The latter is <literal>#include</literal>d by
621 various C programs, which can thereby make use of
622 configuration information.</para>
626 <para><command>configure</command> takes some optional
627 arguments. Use <literal>./configure --help</literal> to
628 get a list of the available arguments. Here are some of
629 the ones you might need:</para>
633 <term><literal>--with-ghc=<parameter>path</parameter></literal>
634 <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
637 <para>Specifies the path to an installed GHC which
638 you would like to use. This compiler will be used
639 for compiling GHC-specific code (eg. GHC itself).
640 This option <emphasis>cannot</emphasis> be specified
641 using <filename>build.mk</filename> (see later),
642 because <command>configure</command> needs to
643 auto-detect the version of GHC you're using. The
644 default is to look for a compiler named
645 <literal>ghc</literal> in your path.</para>
650 <term><literal>--with-hc=<parameter>path</parameter></literal>
651 <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
654 <para>Specifies the path to any installed Haskell
655 compiler. This compiler will be used for compiling
656 generic Haskell code. The default is to use
657 <literal>ghc</literal>. (NOTE: I'm not sure it
658 actually works to specify a compiler other than GHC
659 here; unless you really know what you're doing I
660 suggest not using this option at all.)</para>
665 <term><literal>--with-gcc=<parameter>path</parameter></literal>
666 <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
669 <para>Specifies the path to the installed GCC. This
670 compiler will be used to compile all C files,
671 <emphasis>except</emphasis> any generated by the
672 installed Haskell compiler, which will have its own
673 idea of which C compiler (if any) to use. The
674 default is to use <literal>gcc</literal>.</para>
682 <term>Step 3: build configuration.</term>
684 <para>Next, you say how this build of
685 GHC is to differ from the standard
686 defaults by creating a new file
687 <filename>mk/build.mk</filename><indexterm><primary>build.mk</primary></indexterm>
688 <emphasis>in the build tree</emphasis>. This file is the
689 one and only file you edit in the build tree, precisely
690 because it says how this build differs from the source.
691 (Just in case your build tree does die, you might want to
692 keep a private directory of <filename>build.mk</filename>
693 files, and use a symbolic link in each build tree to point
694 to the appropriate one.) So
695 <filename>mk/build.mk</filename> never exists in the
696 source tree—you create one in each build tree from
697 the template. We'll discuss what to put in it
703 <para>And that's it for configuration. Simple, eh?</para>
705 <para>What do you put in your build-specific configuration file
706 <filename>mk/build.mk</filename>? <emphasis>For almost all
707 purposes all you will do is put make variable definitions that
708 override those in</emphasis>
709 <filename>mk/config.mk.in</filename>. The whole point of
710 <filename>mk/config.mk.in</filename>—and its derived
711 counterpart <filename>mk/config.mk</filename>—is to define
712 the build configuration. It is heavily commented, as you will
713 see if you look at it. So generally, what you do is look at
714 <filename>mk/config.mk.in</filename>, and add definitions in
715 <filename>mk/build.mk</filename> that override any of the
716 <filename>config.mk</filename> definitions that you want to
717 change. (The override occurs because the main boilerplate file,
718 <filename>mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>,
719 includes <filename>build.mk</filename> after
720 <filename>config.mk</filename>.)</para>
722 <para>For your convenience, there's a file called
723 <filename>build.mk.sample</filename> that can serve as a starting
724 point for your <filename>build.mk</filename>.</para>
726 <para>For example, <filename>config.mk.in</filename> contains
727 the definition:</para>
729 <programlisting>GhcHcOpts=-Rghc-timing</programlisting>
731 <para>The accompanying comment explains that this is the list of
732 flags passed to GHC when building GHC itself. For doing
733 development, it is wise to add <literal>-DDEBUG</literal>, to
734 enable debugging code. So you would add the following to
735 <filename>build.mk</filename>:</para>
737 <programlisting>GhcHcOpts += -DDEBUG</programlisting>
739 <para>GNU <command>make</command> allows existing definitions to
740 have new text appended using the “<literal>+=</literal>”
741 operator, which is quite a convenient feature.</para>
743 <para>Haskell compilations by default have <literal>-O</literal>
744 turned on, by virtue of this setting from
745 <filename>config.mk</filename>:</para>
747 <programlisting>SRC_HC_OPTS += -H16m -O</programlisting>
749 <para><literal>SRC_HC_OPTS</literal> means "options for HC from
750 the source tree", where HC stands for Haskell Compiler.
751 <literal>SRC_HC_OPTS</literal> are added to every Haskell
752 compilation. To turn off optimisation, you could add this to
753 <filename>build.mk</filename>:</para>
755 <programlisting>SRC_HC_OPTS = -H16m -O0</programlisting>
757 <para>Or you could just add <literal>-O0</literal> to
758 <literal>GhcHcOpts</literal> to turn off optimisation for the
759 compiler. See <xref linkend="quick-start" /> for some more
762 <para>When reading <filename>config.mk.in</filename>, remember
763 that anything between “@...@” signs is going to be substituted
764 by <command>configure</command> later. You
765 <emphasis>can</emphasis> override the resulting definition if
766 you want, but you need to be a bit surer what you are doing.
767 For example, there's a line that says:</para>
769 <programlisting>TAR = @TarCmd@</programlisting>
771 <para>This defines the Make variables <constant>TAR</constant>
772 to the pathname for a <command>tar</command> that
773 <command>configure</command> finds somewhere. If you have your
774 own pet <command>tar</command> you want to use instead, that's
775 fine. Just add this line to <filename>mk/build.mk</filename>:</para>
777 <programlisting>TAR = mytar</programlisting>
779 <para>You do not <emphasis>have</emphasis> to have a
780 <filename>mk/build.mk</filename> file at all; if you don't,
781 you'll get all the default settings from
782 <filename>mk/config.mk.in</filename>.</para>
784 <para>You can also use <filename>build.mk</filename> to override
785 anything that <command>configure</command> got wrong. One place
786 where this happens often is with the definition of
787 <constant>FPTOOLS_TOP_ABS</constant>: this
788 variable is supposed to be the canonical path to the top of your
789 source tree, but if your system uses an automounter then the
790 correct directory is hard to find automatically. If you find
791 that <command>configure</command> has got it wrong, just put the
792 correct definition in <filename>build.mk</filename>.</para>
795 <sect2 id="sec-storysofar">
796 <title>The story so far</title>
798 <para>Let's summarise the steps you need to carry to get
799 yourself a fully-configured build tree from scratch.</para>
803 <para> Get your source tree from somewhere (darcs repository
804 or source distribution). Say you call the root directory
805 <filename>myghc</filename> (it does not have to be
806 called <filename>ghc</filename>).</para>
810 <para>(Optional) Use <command>lndir</command> or
811 <command>mkshadowdir</command> to create a build tree.</para>
814 $ mkshadowdir . /scratch/joe-bloggs/myghc-x86</screen>
816 <para>(N.B. <command>mkshadowdir</command>'s first argument
817 is taken relative to its second.) You probably want to give
818 the build tree a name that suggests its main defining
819 characteristic (in your mind at least), in case you later
824 <para>Change directory to the build tree. Everything is
825 going to happen there now.</para>
827 <screen>$ cd /scratch/joe-bloggs/myghc-x86</screen>
832 <para>Prepare for system configuration:</para>
834 <screen>$ autoreconf</screen>
836 <para>(You can skip this step if you are starting from a
837 source distribution, and you already have
838 <filename>configure</filename> and
839 <filename>mk/config.h.in</filename>.)</para>
843 <para>Do system configuration:</para>
845 <screen>$ ./configure</screen>
847 <para>Don't forget to check whether you need to add any
848 arguments to <literal>configure</literal>; for example, a
849 common requirement is to specify which GHC to use with
850 <option>--with-ghc=<replaceable>ghc</replaceable></option>.</para>
854 <para>Create the file <filename>mk/build.mk</filename>,
855 adding definitions for your desired configuration
860 <para>You can make subsequent changes to
861 <filename>mk/build.mk</filename> as often as you like. You do
862 not have to run any further configuration programs to make these
863 changes take effect. In theory you should, however, say
864 <command>make clean; make</command>, because configuration
865 option changes could affect anything—but in practice you
866 are likely to know what's affected.</para>
870 <title>Making things</title>
872 <para>At this point you have made yourself a fully-configured
873 build tree, so you are ready to start building real
876 <para>The first thing you need to know is that <emphasis>you
877 must use GNU <command>make</command></emphasis>. On some
878 systems this is called <command>gmake</command>, whereas on
879 others it is the standard <command>make</command> command. In
880 this document we will always refer to it as
881 <command>make</command>; please substitute with
882 <command>gmake</command> if your system requires it. If you use
883 a the wrong <command>make</command> you will get all sorts of
884 error messages (but no damage) because the GHC
885 <command>Makefiles</command> use GNU <command>make</command>'s
886 facilities extensively.</para>
888 <para>To just build the whole thing, <command>cd</command> to
889 the top of your build tree and type <command>make</command>.
890 This will prepare the tree and build the various parts in the
891 correct order, resulting in a complete build of GHC that can
892 even be used directly from the tree, without being installed
896 <sect2 id="sec-bootstrapping">
897 <title>Bootstrapping GHC</title>
899 <para>GHC requires a 2-stage bootstrap in order to provide
900 full functionality, including GHCi. By a 2-stage bootstrap, we
901 mean that the compiler is built once using the installed GHC,
902 and then again using the compiler built in the first stage. You
903 can also build a stage 3 compiler, but this normally isn't
904 necessary except to verify that the stage 2 compiler is working
907 <para>Note that when doing a bootstrap, the stage 1 compiler
908 must be built, followed by the runtime system and libraries, and
909 then the stage 2 compiler. The correct ordering is implemented
910 by the top-level <filename>Makefile</filename>, so if you want
911 everything to work automatically it's best to start
912 <command>make</command> from the top of the tree. The top-level
913 <filename>Makefile</filename> is set up to do a 2-stage
914 bootstrap by default (when you say <command>make</command>).
915 Some other targets it supports are:</para>
921 <para>Build everything as normal, including the stage 1
929 <para>Build the stage 2 compiler only.</para>
936 <para>Build the stage 3 compiler only.</para>
941 <term>bootstrap</term> <term>bootstrap2</term>
943 <para>Build stage 1 followed by stage 2.</para>
948 <term>bootstrap3</term>
950 <para>Build stages 1, 2 and 3.</para>
957 <para>Install everything, including the compiler built in
958 stage 2. To override the stage, say <literal>make install
959 stage=<replaceable>n</replaceable></literal> where
960 <replaceable>n</replaceable> is the stage to install.</para>
965 <para>The top-level <filename>Makefile</filename> also arranges
966 to do the appropriate <literal>make boot</literal> steps (see
967 below) before actually building anything.</para>
969 <para>The <literal>stage1</literal>, <literal>stage2</literal>
970 and <literal>stage3</literal> targets also work in the
971 <literal>compiler</literal> directory, but don't forget that
972 each stage requires its own <literal>make boot</literal> step:
973 for example, you must do</para>
975 <screen>$ make boot stage=2</screen>
977 <para>before <literal>make stage2</literal> in
978 <literal>compiler</literal>.</para>
981 <sect2 id="sec-standard-targets">
982 <title>Standard Targets</title>
983 <indexterm><primary>targets, standard makefile</primary></indexterm>
984 <indexterm><primary>makefile targets</primary></indexterm>
986 <para>In any directory you should be able to make the following:</para>
990 <term><literal>boot</literal></term>
992 <para>does the one-off preparation required to get ready
993 for the real work. Notably, it does <command>make
994 depend</command> in all directories that contain programs.
995 It also builds the necessary tools for compilation to
998 <para>Invoking the <literal>boot</literal> target
999 explicitly is not normally necessary. From the top-level
1000 <literal>fptools</literal> directory, invoking
1001 <literal>make</literal> causes <literal>make boot
1002 all</literal> to be invoked in each of the project
1003 subdirectories, in the order specified by
1004 <literal>$(AllTargets)</literal> in
1005 <literal>config.mk</literal>.</para>
1007 <para>If you're working in a subdirectory somewhere and
1008 need to update the dependencies, <literal>make
1009 boot</literal> is a good way to do it.</para>
1014 <term><literal>all</literal></term>
1016 <para>makes all the final target(s) for this Makefile.
1017 Depending on which directory you are in a “final
1018 target” may be an executable program, a library
1019 archive, a shell script, or a Postscript file. Typing
1020 <command>make</command> alone is generally the same as
1021 typing <command>make all</command>.</para>
1026 <term><literal>install</literal></term>
1028 <para>installs the things built by <literal>all</literal>
1029 (except for the documentation). Where does it install
1030 them? That is specified by
1031 <filename>mk/config.mk.in</filename>; you can override it
1032 in <filename>mk/build.mk</filename>, or by running
1033 <command>configure</command> with command-line arguments
1034 like <literal>--bindir=/home/simonpj/bin</literal>; see
1035 <literal>./configure --help</literal> for the full
1041 <term><literal>install-docs</literal></term>
1043 <para>installs the documentation. Otherwise behaves just
1044 like <literal>install</literal>.</para>
1049 <term><literal>uninstall</literal></term>
1051 <para>reverses the effect of
1052 <literal>install</literal>.</para>
1057 <term><literal>clean</literal></term>
1059 <para>Delete all files from the current directory that are
1060 normally created by building the program. Don't delete
1061 the files that record the configuration, or files
1062 generated by <command>make boot</command>. Also preserve
1063 files that could be made by building, but normally aren't
1064 because the distribution comes with them.</para>
1069 <term><literal>distclean</literal></term>
1071 <para>Delete all files from the current directory that are
1072 created by configuring or building the program. If you
1073 have unpacked the source and built the program without
1074 creating any other files, <literal>make
1075 distclean</literal> should leave only the files that were
1076 in the distribution.</para>
1081 <term><literal>mostlyclean</literal></term>
1083 <para>Like <literal>clean</literal>, but may refrain from
1084 deleting a few files that people normally don't want to
1090 <term><literal>maintainer-clean</literal></term>
1092 <para>Delete everything from the current directory that
1093 can be reconstructed with this Makefile. This typically
1094 includes everything deleted by
1095 <literal>distclean</literal>, plus more: C source files
1096 produced by Bison, tags tables, Info files, and so
1099 <para>One exception, however: <literal>make
1100 maintainer-clean</literal> should not delete
1101 <filename>configure</filename> even if
1102 <filename>configure</filename> can be remade using a rule
1103 in the <filename>Makefile</filename>. More generally,
1104 <literal>make maintainer-clean</literal> should not delete
1105 anything that needs to exist in order to run
1106 <filename>configure</filename> and then begin to build the
1112 <term><literal>check</literal></term>
1114 <para>run the test suite.</para>
1119 <para>All of these standard targets automatically recurse into
1120 sub-directories. Certain other standard targets do not:</para>
1124 <term><literal>configure</literal></term>
1126 <para>is only available in the root directory
1127 <constant>$(FPTOOLS_TOP)</constant>; it has
1128 been discussed in <xref
1129 linkend="sec-build-config"/>.</para>
1134 <term><literal>depend</literal></term>
1136 <para>make a <filename>.depend</filename> file in each
1137 directory that needs it. This <filename>.depend</filename>
1138 file contains mechanically-generated dependency
1139 information; for example, suppose a directory contains a
1140 Haskell source module <filename>Foo.lhs</filename> which
1141 imports another module <literal>Baz</literal>. Then the
1142 generated <filename>.depend</filename> file will contain
1143 the dependency:</para>
1145 <programlisting>Foo.o : Baz.hi</programlisting>
1147 <para>which says that the object file
1148 <filename>Foo.o</filename> depends on the interface file
1149 <filename>Baz.hi</filename> generated by compiling module
1150 <literal>Baz</literal>. The <filename>.depend</filename>
1151 file is automatically included by every Makefile.</para>
1156 <term><literal>binary-dist</literal></term>
1158 <para>make a binary distribution. This is the target we
1159 use to build the binary distributions of GHC and
1165 <term><literal>dist</literal></term>
1167 <para>make a source distribution. Note that this target
1168 does “make distclean” as part of its work;
1169 don't use it if you want to keep what you've built.</para>
1174 <para>Most <filename>Makefile</filename>s have targets other
1175 than these. You can discover them by looking in the
1176 <filename>Makefile</filename> itself.</para>
1180 <title>Using a project from the build tree</title>
1182 <para>If you want to build GHC (say) and just use it direct from
1183 the build tree without doing <literal>make install</literal>
1184 first, you can run the in-place driver script:
1185 <filename>compiler/ghc-inplace</filename>.</para>
1187 <para> Do <emphasis>NOT</emphasis> use
1188 <filename>compiler/ghc</filename>, or
1189 <filename>compiler/ghc-6.xx</filename>, as these are the
1190 scripts intended for installation, and contain hard-wired paths
1191 to the installed libraries, rather than the libraries in the
1194 <para>Happy can similarly be run from the build tree, using
1195 <filename>happy/src/happy-inplace</filename>, and similarly for
1196 Alex and Haddock.</para>
1200 <title>Fast Making</title>
1202 <indexterm><primary>fastmake</primary></indexterm>
1203 <indexterm><primary>dependencies, omitting</primary></indexterm>
1204 <indexterm><primary>FAST, makefile variable</primary></indexterm>
1206 <para>Sometimes the dependencies get in the way: if you've made
1207 a small change to one file, and you're absolutely sure that it
1208 won't affect anything else, but you know that
1209 <command>make</command> is going to rebuild everything anyway,
1210 the following hack may be useful:</para>
1212 <screen>$ make FAST=YES</screen>
1214 <para>This tells the make system to ignore dependencies and just
1215 build what you tell it to. In other words, it's equivalent to
1216 temporarily removing the <filename>.depend</filename> file in
1217 the current directory (where <command>mkdependHS</command> and
1218 friends store their dependency information).</para>
1220 <para>A bit of history: GHC used to come with a
1221 <command>fastmake</command> script that did the above job, but
1222 GNU make provides the features we need to do it without
1223 resorting to a script. Also, we've found that fastmaking is
1224 less useful since the advent of GHC's recompilation checker (see
1225 the User's Guide section on "Separate Compilation").</para>
1229 <sect1 id="sec-makefile-arch">
1230 <title>The <filename>Makefile</filename> architecture</title>
1231 <indexterm><primary>makefile architecture</primary></indexterm>
1233 <para><command>make</command> is great if everything
1234 works—you type <command>make install</command> and lo! the
1235 right things get compiled and installed in the right places. Our
1236 goal is to make this happen often, but somehow it often doesn't;
1237 instead some weird error message eventually emerges from the
1238 bowels of a directory you didn't know existed.</para>
1240 <para>The purpose of this section is to give you a road-map to
1241 help you figure out what is going right and what is going
1245 <title>Debugging</title>
1247 <para>Debugging <filename>Makefile</filename>s is something of a
1248 black art, but here's a couple of tricks that we find
1249 particularly useful. The following command allows you to see
1250 the contents of any make variable in the context of the current
1251 <filename>Makefile</filename>:</para>
1253 <screen>$ make show VALUE=HS_SRCS</screen>
1255 <para>where you can replace <literal>HS_SRCS</literal> with the
1256 name of any variable you wish to see the value of.</para>
1258 <para>GNU make has a <option>-d</option> option which generates
1259 a dump of the decision procedure used to arrive at a conclusion
1260 about which files should be recompiled. Sometimes useful for
1261 tracking down problems with superfluous or missing
1262 recompilations.</para>
1266 <title>A small project</title>
1268 <para>To get started, let us look at the
1269 <filename>Makefile</filename> for an imaginary small
1270 <literal>fptools</literal> project, <literal>small</literal>.
1271 Each project in <literal>fptools</literal> has its own directory
1272 in <constant>FPTOOLS_TOP</constant>, so the
1273 <literal>small</literal> project will have its own directory
1274 <constant>FPOOLS_TOP/small/</constant>. Inside the
1275 <filename>small/</filename> directory there will be a
1276 <filename>Makefile</filename>, looking something like
1279 <indexterm><primary>Makefile, minimal</primary></indexterm>
1281 <programlisting># Makefile for fptools project "small"
1284 include $(TOP)/mk/boilerplate.mk
1286 SRCS = $(wildcard *.lhs) $(wildcard *.c)
1289 include $(TOP)/target.mk</programlisting>
1291 <para>this <filename>Makefile</filename> has three
1296 <para>The first section includes
1299 One of the most important
1300 features of GNU <command>make</command> that we use is the ability for a <filename>Makefile</filename> to
1301 include another named file, very like <command>cpp</command>'s <literal>#include</literal>
1306 a file of “boilerplate” code from the level
1307 above (which in this case will be
1308 <filename>FPTOOLS_TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
1309 As its name suggests, <filename>boilerplate.mk</filename>
1310 consists of a large quantity of standard
1311 <filename>Makefile</filename> code. We discuss this
1312 boilerplate in more detail in <xref linkend="sec-boiler"/>.
1313 <indexterm><primary>include, directive in
1314 Makefiles</primary></indexterm> <indexterm><primary>Makefile
1315 inclusion</primary></indexterm></para>
1317 <para>Before the <literal>include</literal> statement, you
1318 must define the <command>make</command> variable
1319 <constant>TOP</constant><indexterm><primary>TOP</primary></indexterm>
1320 to be the directory containing the <filename>mk</filename>
1321 directory in which the <filename>boilerplate.mk</filename>
1322 file is. It is <emphasis>not</emphasis> OK to simply say</para>
1324 <programlisting>include ../mk/boilerplate.mk # NO NO NO</programlisting>
1327 <para>Why? Because the <filename>boilerplate.mk</filename>
1328 file needs to know where it is, so that it can, in turn,
1329 <literal>include</literal> other files. (Unfortunately,
1330 when an <literal>include</literal>d file does an
1331 <literal>include</literal>, the filename is treated relative
1332 to the directory in which <command>make</command> is being
1333 run, not the directory in which the
1334 <literal>include</literal>d sits.) In general,
1335 <emphasis>every file <filename>foo.mk</filename> assumes
1337 <filename>$(TOP)/mk/foo.mk</filename>
1338 refers to itself.</emphasis> It is up to the
1339 <filename>Makefile</filename> doing the
1340 <literal>include</literal> to ensure this is the case.</para>
1342 <para>Files intended for inclusion in other
1343 <filename>Makefile</filename>s are written to have the
1344 following property: <emphasis>after
1345 <filename>foo.mk</filename> is <literal>include</literal>d,
1346 it leaves <constant>TOP</constant> containing the same value
1347 as it had just before the <literal>include</literal>
1348 statement</emphasis>. In our example, this invariant
1349 guarantees that the <literal>include</literal> for
1350 <filename>target.mk</filename> will look in the same
1351 directory as that for <filename>boilerplate.mk</filename>.</para>
1355 <para> The second section defines the following standard
1356 <command>make</command> variables:
1357 <constant>SRCS</constant><indexterm><primary>SRCS</primary></indexterm>
1358 (the source files from which is to be built), and
1359 <constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>
1360 (the executable binary to be built). We will discuss in
1361 more detail what the “standard variables” are,
1362 and how they affect what happens, in <xref
1363 linkend="sec-targets"/>.</para>
1365 <para>The definition for <constant>SRCS</constant> uses the
1366 useful GNU <command>make</command> construct
1367 <literal>$(wildcard $pat$)</literal><indexterm><primary>wildcard</primary></indexterm>,
1368 which expands to a list of all the files matching the
1369 pattern <literal>pat</literal> in the current directory. In
1370 this example, <constant>SRCS</constant> is set to the list
1371 of all the <filename>.lhs</filename> and
1372 <filename>.c</filename> files in the directory. (Let's
1373 suppose there is one of each, <filename>Foo.lhs</filename>
1374 and <filename>Baz.c</filename>.)</para>
1378 <para>The last section includes a second file of standard
1380 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
1381 It contains the rules that tell <command>make</command> how
1382 to make the standard targets (<xref
1383 linkend="sec-standard-targets"/>). Why, you ask, can't this
1384 standard code be part of
1385 <filename>boilerplate.mk</filename>? Good question. We
1386 discuss the reason later, in <xref
1387 linkend="sec-boiler-arch"/>.</para>
1389 <para>You do not <emphasis>have</emphasis> to
1390 <literal>include</literal> the
1391 <filename>target.mk</filename> file. Instead, you can write
1392 rules of your own for all the standard targets. Usually,
1393 though, you will find quite a big payoff from using the
1394 canned rules in <filename>target.mk</filename>; the price
1395 tag is that you have to understand what canned rules get
1396 enabled, and what they do (<xref
1397 linkend="sec-targets"/>).</para>
1401 <para>In our example <filename>Makefile</filename>, most of the
1402 work is done by the two <literal>include</literal>d files. When
1403 you say <command>make all</command>, the following things
1408 <para><command>make</command> figures out that the object
1409 files are <filename>Foo.o</filename> and
1410 <filename>Baz.o</filename>.</para>
1414 <para>It uses a boilerplate pattern rule to compile
1415 <filename>Foo.lhs</filename> to <filename>Foo.o</filename>
1416 using a Haskell compiler. (Which one? That is set in the
1417 build configuration.)</para>
1421 <para>It uses another standard pattern rule to compile
1422 <filename>Baz.c</filename> to <filename>Baz.o</filename>,
1423 using a C compiler. (Ditto.)</para>
1427 <para>It links the resulting <filename>.o</filename> files
1428 together to make <literal>small</literal>, using the Haskell
1429 compiler to do the link step. (Why not use
1430 <command>ld</command>? Because the Haskell compiler knows
1431 what standard libraries to link in. How did
1432 <command>make</command> know to use the Haskell compiler to
1433 do the link, rather than the C compiler? Because we set the
1434 variable <constant>HS_PROG</constant> rather than
1435 <constant>C_PROG</constant>.)</para>
1439 <para>All <filename>Makefile</filename>s should follow the above
1440 three-section format.</para>
1444 <title>A larger project</title>
1446 <para>Larger projects are usually structured into a number of
1447 sub-directories, each of which has its own
1448 <filename>Makefile</filename>. (In very large projects, this
1449 sub-structure might be iterated recursively, though that is
1450 rare.) To give you the idea, here's part of the directory
1451 structure for the (rather large) GHC project:</para>
1453 <programlisting>$(FPTOOLS_TOP)/ghc/
1460 ...source files for documentation...
1463 ...source files for driver...
1466 parser/...source files for parser...
1467 renamer/...source files for renamer...
1468 ...etc...</programlisting>
1470 <para>The sub-directories <filename>docs</filename>,
1471 <filename>driver</filename>, <filename>compiler</filename>, and
1472 so on, each contains a sub-component of GHC, and each has its
1473 own <filename>Makefile</filename>. There must also be a
1474 <filename>Makefile</filename> in
1475 <filename>$(FPTOOLS_TOP)/ghc</filename>.
1476 It does most of its work by recursively invoking
1477 <command>make</command> on the <filename>Makefile</filename>s
1478 in the sub-directories. We say that
1479 <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
1480 <filename>Makefile</filename></emphasis>, because it does little
1481 except organise its children, while the
1482 <filename>Makefile</filename>s in the sub-directories are all
1483 <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
1484 principle the sub-directories might themselves contain a
1485 non-leaf <filename>Makefile</filename> and several
1486 sub-sub-directories, but that does not happen in GHC.)</para>
1488 <para>The <filename>Makefile</filename> in
1489 <filename>ghc/compiler</filename> is considered a leaf
1490 <filename>Makefile</filename> even though the
1491 <filename>ghc/compiler</filename> has sub-directories, because
1492 these sub-directories do not themselves have
1493 <filename>Makefile</filename>s in them. They are just used to
1494 structure the collection of modules that make up GHC, but all
1495 are managed by the single <filename>Makefile</filename> in
1496 <filename>ghc/compiler</filename>.</para>
1498 <para>You will notice that <filename>ghc/</filename> also
1499 contains a directory <filename>ghc/mk/</filename>. It contains
1500 GHC-specific <filename>Makefile</filename> boilerplate code.
1501 More precisely:</para>
1505 <para><filename>ghc/mk/boilerplate.mk</filename> is included
1506 at the top of <filename>ghc/Makefile</filename>, and of all
1507 the leaf <filename>Makefile</filename>s in the
1508 sub-directories. It in turn <literal>include</literal>s the
1509 main boilerplate file
1510 <filename>mk/boilerplate.mk</filename>.</para>
1514 <para><filename>ghc/mk/target.mk</filename> is
1515 <literal>include</literal>d at the bottom of
1516 <filename>ghc/Makefile</filename>, and of all the leaf
1517 <filename>Makefile</filename>s in the sub-directories. It
1518 in turn <literal>include</literal>s the file
1519 <filename>mk/target.mk</filename>.</para>
1523 <para>So these two files are the place to look for GHC-wide
1524 customisation of the standard boilerplate.</para>
1527 <sect2 id="sec-boiler-arch">
1528 <title>Boilerplate architecture</title>
1529 <indexterm><primary>boilerplate architecture</primary></indexterm>
1531 <para>Every <filename>Makefile</filename> includes a
1532 <filename>boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>
1533 file at the top, and
1534 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
1535 file at the bottom. In this section we discuss what is in these
1536 files, and why there have to be two of them. In general:</para>
1540 <para><filename>boilerplate.mk</filename> consists of:</para>
1544 <para><emphasis>Definitions of millions of
1545 <command>make</command> variables</emphasis> that
1546 collectively specify the build configuration. Examples:
1547 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1548 the options to feed to the Haskell compiler;
1549 <constant>NoFibSubDirs</constant><indexterm><primary>NoFibSubDirs</primary></indexterm>,
1550 the sub-directories to enable within the
1551 <literal>nofib</literal> project;
1552 <constant>GhcWithHc</constant><indexterm><primary>GhcWithHc</primary></indexterm>,
1553 the name of the Haskell compiler to use when compiling
1554 GHC in the <literal>ghc</literal> project.</para>
1558 <para><emphasis>Standard pattern rules</emphasis> that
1559 tell <command>make</command> how to construct one file
1560 from another.</para>
1564 <para><filename>boilerplate.mk</filename> needs to be
1565 <literal>include</literal>d at the <emphasis>top</emphasis>
1566 of each <filename>Makefile</filename>, so that the user can
1567 replace the boilerplate definitions or pattern rules by
1568 simply giving a new definition or pattern rule in the
1569 <filename>Makefile</filename>. <command>make</command>
1570 simply takes the last definition as the definitive one.</para>
1572 <para>Instead of <emphasis>replacing</emphasis> boilerplate
1573 definitions, it is also quite common to
1574 <emphasis>augment</emphasis> them. For example, a
1575 <filename>Makefile</filename> might say:</para>
1577 <programlisting>SRC_HC_OPTS += -O</programlisting>
1579 <para>thereby adding “<option>-O</option>” to
1581 <constant>SRC_HC_OPTS</constant><indexterm><primary>SRC_HC_OPTS</primary></indexterm>.</para>
1585 <para><filename>target.mk</filename> contains
1586 <command>make</command> rules for the standard targets
1587 described in <xref linkend="sec-standard-targets"/>. These
1588 rules are selectively included, depending on the setting of
1589 certain <command>make</command> variables. These variables
1590 are usually set in the middle section of the
1591 <filename>Makefile</filename> between the two
1592 <literal>include</literal>s.</para>
1594 <para><filename>target.mk</filename> must be included at the
1595 end (rather than being part of
1596 <filename>boilerplate.mk</filename>) for several tiresome
1602 <para><command>make</command> commits target and
1603 dependency lists earlier than it should. For example,
1604 <filename>target.mk</filename> has a rule that looks
1607 <programlisting>$(HS_PROG) : $(OBJS)
1608 $(HC) $(LD_OPTS) $< -o $@</programlisting>
1610 <para>If this rule was in
1611 <filename>boilerplate.mk</filename> then
1612 <constant>$(HS_PROG)</constant><indexterm><primary>HS_PROG</primary></indexterm>
1614 <constant>$(OBJS)</constant><indexterm><primary>OBJS</primary></indexterm>
1615 would not have their final values at the moment
1616 <command>make</command> encountered the rule. Alas,
1617 <command>make</command> takes a snapshot of their
1618 current values, and wires that snapshot into the rule.
1619 (In contrast, the commands executed when the rule
1620 “fires” are only substituted at the moment
1621 of firing.) So, the rule must follow the definitions
1622 given in the <filename>Makefile</filename> itself.</para>
1626 <para>Unlike pattern rules, ordinary rules cannot be
1627 overriden or replaced by subsequent rules for the same
1628 target (at least, not without an error message).
1629 Including ordinary rules in
1630 <filename>boilerplate.mk</filename> would prevent the
1631 user from writing rules for specific targets in specific
1636 <para>There are a couple of other reasons I've
1637 forgotten, but it doesn't matter too much.</para>
1644 <sect2 id="sec-boiler">
1645 <title>The main <filename>mk/boilerplate.mk</filename> file</title>
1646 <indexterm><primary>boilerplate.mk</primary></indexterm>
1648 <para>If you look at
1649 <filename>$(FPTOOLS_TOP)/mk/boilerplate.mk</filename>
1650 you will find that it consists of the following sections, each
1651 held in a separate file:</para>
1655 <term><filename>config.mk</filename>
1656 <indexterm><primary>config.mk</primary></indexterm>
1659 <para>is the build configuration file we discussed at
1660 length in <xref linkend="sec-build-config"/>.</para>
1665 <term><filename>paths.mk</filename>
1666 <indexterm><primary>paths.mk</primary></indexterm>
1669 <para>defines <command>make</command> variables for
1670 pathnames and file lists. This file contains code for
1671 automatically compiling lists of source files and deriving
1672 lists of object files from those. The results can be
1673 overriden in the <filename>Makefile</filename>, but in
1674 most cases the automatic setup should do the right
1677 <para>The following variables may be set in the
1678 <filename>Makefile</filename> to affect how the automatic
1679 source file search is done:</para>
1683 <term><literal>ALL_DIRS</literal>
1684 <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
1687 <para>Set to a list of directories to search in
1688 addition to the current directory for source
1694 <term><literal>EXCLUDED_SRCS</literal>
1695 <indexterm><primary><literal>EXCLUDED_SRCS</literal></primary></indexterm>
1698 <para>Set to a list of source files (relative to the
1699 current directory) to omit from the automatic
1700 search. The source searching machinery is clever
1701 enough to know that if you exclude a source file
1702 from which other sources are derived, then the
1703 derived sources should also be excluded. For
1704 example, if you set <literal>EXCLUDED_SRCS</literal>
1705 to include <filename>Foo.y</filename>, then
1706 <filename>Foo.hs</filename> will also be
1712 <term><literal>EXTRA_SRCS</literal>
1713 <indexterm><primary><literal>EXTRA_SRCS</literal></primary></indexterm>
1716 <para>Set to a list of extra source files (perhaps
1717 in directories not listed in
1718 <literal>ALL_DIRS</literal>) that should be
1724 <para>The results of the automatic source file search are
1725 placed in the following make variables:</para>
1729 <term><literal>SRCS</literal>
1730 <indexterm><primary><literal>SRCS</literal></primary></indexterm>
1733 <para>All source files found, sorted and without
1734 duplicates, including those which might not exist
1735 yet but will be derived from other existing sources.
1736 <literal>SRCS</literal> <emphasis>can</emphasis> be
1737 overriden if necessary, in which case the variables
1738 below will follow suit.</para>
1743 <term><literal>HS_SRCS</literal>
1744 <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
1747 <para>all Haskell source files in the current
1748 directory, including those derived from other source
1749 files (eg. Happy sources also give rise to Haskell
1755 <term><literal>HS_OBJS</literal>
1756 <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
1759 <para>Object files derived from
1760 <literal>HS_SRCS</literal>.</para>
1765 <term><literal>HS_IFACES</literal>
1766 <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
1769 <para>Interface files (<literal>.hi</literal> files)
1770 derived from <literal>HS_SRCS</literal>.</para>
1775 <term><literal>C_SRCS</literal>
1776 <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
1779 <para>All C source files found.</para>
1784 <term><literal>C_OBJS</literal>
1785 <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
1788 <para>Object files derived from
1789 <literal>C_SRCS</literal>.</para>
1794 <term><literal>SCRIPT_SRCS</literal>
1795 <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
1798 <para>All script source files found
1799 (<literal>.lprl</literal> files).</para>
1804 <term><literal>SCRIPT_OBJS</literal>
1805 <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
1808 <para><quote>object</quote> files derived from
1809 <literal>SCRIPT_SRCS</literal>
1810 (<literal>.prl</literal> files).</para>
1815 <term><literal>HSC_SRCS</literal>
1816 <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
1819 <para>All <literal>hsc2hs</literal> source files
1820 (<literal>.hsc</literal> files).</para>
1825 <term><literal>HAPPY_SRCS</literal>
1826 <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
1829 <para>All <literal>happy</literal> source files
1830 (<literal>.y</literal> or <literal>.hy</literal> files).</para>
1835 <term><literal>OBJS</literal>
1836 <indexterm><primary>OBJS</primary></indexterm>
1839 <para>the concatenation of
1840 <literal>$(HS_OBJS)</literal>,
1841 <literal>$(C_OBJS)</literal>, and
1842 <literal>$(SCRIPT_OBJS)</literal>.</para>
1847 <para>Any or all of these definitions can easily be
1848 overriden by giving new definitions in your
1849 <filename>Makefile</filename>.</para>
1851 <para>What, exactly, does <filename>paths.mk</filename>
1852 consider a <quote>source file</quote> to be? It's based
1853 on the file's suffix (e.g. <filename>.hs</filename>,
1854 <filename>.lhs</filename>, <filename>.c</filename>,
1855 <filename>.hy</filename>, etc), but this is the kind of
1856 detail that changes, so rather than enumerate the source
1857 suffices here the best thing to do is to look in
1858 <filename>paths.mk</filename>.</para>
1863 <term><filename>opts.mk</filename>
1864 <indexterm><primary>opts.mk</primary></indexterm>
1867 <para>defines <command>make</command> variables for option
1868 strings to pass to each program. For example, it defines
1869 <constant>HC_OPTS</constant><indexterm><primary>HC_OPTS</primary></indexterm>,
1870 the option strings to pass to the Haskell compiler. See
1871 <xref linkend="sec-suffix"/>.</para>
1876 <term><filename>suffix.mk</filename>
1877 <indexterm><primary>suffix.mk</primary></indexterm>
1880 <para>defines standard pattern rules—see <xref
1881 linkend="sec-suffix"/>.</para>
1886 <para>Any of the variables and pattern rules defined by the
1887 boilerplate file can easily be overridden in any particular
1888 <filename>Makefile</filename>, because the boilerplate
1889 <literal>include</literal> comes first. Definitions after this
1890 <literal>include</literal> directive simply override the default
1891 ones in <filename>boilerplate.mk</filename>.</para>
1894 <sect2 id="sec-platforms">
1895 <title>Platform settings</title>
1896 <indexterm><primary>Platform settings</primary>
1899 <para>There are three platforms of interest when building GHC:</para>
1903 <term>The <emphasis>build</emphasis> platform</term>
1905 <para>The platform on which we are doing this build.</para>
1910 <term>The <emphasis>host</emphasis> platform</term>
1912 <para>The platform on which these binaries will run.</para>
1917 <term>The <emphasis>target</emphasis> platform</term>
1919 <para>The platform for which this compiler will generate code.</para>
1924 <para>These platforms are set when running the
1925 <literal>configure</literal> script, using the
1926 <option>--build</option>, <option>--host</option>, and
1927 <option>--target</option> options. The <filename>mk/config.mk</filename>
1928 file defines several symbols related to the platform settings (see
1929 <filename>mk/config.mk</filename> for details).</para>
1931 <para>We don't currently support build & host being different, because
1932 the build process creates binaries that are both run during the build,
1933 and also installed.</para>
1935 <para>If host and target are different, then we are building a
1936 cross-compiler. For GHC, this means a compiler
1937 which will generate intermediate .hc files to port to the target
1938 architecture for bootstrapping. The libraries and stage 2 compiler
1939 will be built as HC files for the target system (see <xref
1940 linkend="sec-porting-ghc" /> for details.</para>
1942 <para>More details on when to use BUILD, HOST or TARGET can be found in
1943 the comments in <filename>config.mk</filename>.</para>
1946 <sect2 id="sec-suffix">
1947 <title>Pattern rules and options</title>
1948 <indexterm><primary>Pattern rules</primary></indexterm>
1951 <filename>suffix.mk</filename><indexterm><primary>suffix.mk</primary></indexterm>
1952 defines standard <emphasis>pattern rules</emphasis> that say how
1953 to build one kind of file from another, for example, how to
1954 build a <filename>.o</filename> file from a
1955 <filename>.c</filename> file. (GNU <command>make</command>'s
1956 <emphasis>pattern rules</emphasis> are more powerful and easier
1957 to use than Unix <command>make</command>'s <emphasis>suffix
1958 rules</emphasis>.)</para>
1960 <para>Almost all the rules look something like this:</para>
1962 <programlisting>%.o : %.c
1964 $(CC) $(CC_OPTS) -c $< -o $@</programlisting>
1966 <para>Here's how to understand the rule. It says that
1967 <emphasis>something</emphasis><filename>.o</filename> (say
1968 <filename>Foo.o</filename>) can be built from
1969 <emphasis>something</emphasis><filename>.c</filename>
1970 (<filename>Foo.c</filename>), by invoking the C compiler (path
1971 name held in <constant>$(CC)</constant>), passing to it
1972 the options <constant>$(CC_OPTS)</constant> and
1973 the rule's dependent file of the rule
1974 <literal>$<</literal> (<filename>Foo.c</filename> in
1975 this case), and putting the result in the rule's target
1976 <literal>$@</literal> (<filename>Foo.o</filename> in this
1979 <para>Every program is held in a <command>make</command>
1980 variable defined in <filename>mk/config.mk</filename>—look
1981 in <filename>mk/config.mk</filename> for the complete list. One
1982 important one is the Haskell compiler, which is called
1983 <constant>$(HC)</constant>.</para>
1985 <para>Every program's options are are held in a
1986 <command>make</command> variables called
1987 <constant><prog>_OPTS</constant>. the
1988 <constant><prog>_OPTS</constant> variables are
1989 defined in <filename>mk/opts.mk</filename>. Almost all of them
1990 are defined like this:</para>
1992 <programlisting>CC_OPTS = \
1993 $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)</programlisting>
1995 <para>The four variables from which
1996 <constant>CC_OPTS</constant> is built have the following
2001 <term><constant>SRC_CC_OPTS</constant><indexterm><primary>SRC_CC_OPTS</primary></indexterm>:</term>
2003 <para>options passed to all C compilations.</para>
2008 <term><constant>WAY_<way>_CC_OPTS</constant>:</term>
2010 <para>options passed to C compilations for way
2011 <literal><way></literal>. For example,
2012 <constant>WAY_mp_CC_OPTS</constant>
2013 gives options to pass to the C compiler when compiling way
2014 <literal>mp</literal>. The variable
2015 <constant>WAY_CC_OPTS</constant> holds
2016 options to pass to the C compiler when compiling the
2017 standard way. (<xref linkend="sec-ways"/> dicusses
2018 multi-way compilation.)</para>
2023 <term><constant><module>_CC_OPTS</constant>:</term>
2025 <para>options to pass to the C compiler that are specific
2026 to module <literal><module></literal>. For example,
2027 <constant>SMap_CC_OPTS</constant> gives the
2028 specific options to pass to the C compiler when compiling
2029 <filename>SMap.c</filename>.</para>
2034 <term><constant>EXTRA_CC_OPTS</constant><indexterm><primary>EXTRA_CC_OPTS</primary></indexterm>:</term>
2036 <para>extra options to pass to all C compilations. This
2037 is intended for command line use, thus:</para>
2039 <screen>$ make libHS.a EXTRA_CC_OPTS="-v"</screen>
2045 <sect2 id="sec-targets">
2046 <title>The main <filename>mk/target.mk</filename> file</title>
2047 <indexterm><primary>target.mk</primary></indexterm>
2049 <para><filename>target.mk</filename> contains canned rules for
2050 all the standard targets described in <xref
2051 linkend="sec-standard-targets"/>. It is complicated by the fact
2052 that you don't want all of these rules to be active in every
2053 <filename>Makefile</filename>. Rather than have a plethora of
2054 tiny files which you can include selectively, there is a single
2055 file, <filename>target.mk</filename>, which selectively includes
2056 rules based on whether you have defined certain variables in
2057 your <filename>Makefile</filename>. This section explains what
2058 rules you get, what variables control them, and what the rules
2059 do. Hopefully, you will also get enough of an idea of what is
2060 supposed to happen that you can read and understand any weird
2061 special cases yourself.</para>
2065 <term><constant>HS_PROG</constant><indexterm><primary>HS_PROG</primary></indexterm>.</term>
2067 <para>If <constant>HS_PROG</constant> is defined,
2068 you get rules with the following targets:</para>
2072 <term><filename>HS_PROG</filename><indexterm><primary>HS_PROG</primary></indexterm></term>
2074 <para>itself. This rule links
2075 <constant>$(OBJS)</constant> with the Haskell
2076 runtime system to get an executable called
2077 <constant>$(HS_PROG)</constant>.</para>
2082 <term><literal>install</literal><indexterm><primary>install</primary></indexterm></term>
2085 <constant>$(HS_PROG)</constant> in
2086 <constant>$(bindir)</constant>.</para>
2095 <term><constant>C_PROG</constant><indexterm><primary>C_PROG</primary></indexterm></term>
2097 <para>is similar to <constant>HS_PROG</constant>,
2098 except that the link step links
2099 <constant>$(C_OBJS)</constant> with the C
2100 runtime system.</para>
2105 <term><constant>LIBRARY</constant><indexterm><primary>LIBRARY</primary></indexterm></term>
2107 <para>is similar to <constant>HS_PROG</constant>,
2108 except that it links
2109 <constant>$(LIB_OBJS)</constant> to make the
2110 library archive <constant>$(LIBRARY)</constant>,
2111 and <literal>install</literal> installs it in
2112 <constant>$(libdir)</constant>.</para>
2117 <term><constant>LIB_DATA</constant><indexterm><primary>LIB_DATA</primary></indexterm></term>
2119 <para>…</para>
2124 <term><constant>LIB_EXEC</constant><indexterm><primary>LIB_EXEC</primary></indexterm></term>
2126 <para>…</para>
2131 <term><constant>HS_SRCS</constant><indexterm><primary>HS_SRCS</primary></indexterm>, <constant>C_SRCS</constant><indexterm><primary>C_SRCS</primary></indexterm>.</term>
2133 <para>If <constant>HS_SRCS</constant> is defined
2134 and non-empty, a rule for the target
2135 <literal>depend</literal> is included, which generates
2136 dependency information for Haskell programs. Similarly
2137 for <constant>C_SRCS</constant>.</para>
2142 <para>All of these rules are “double-colon” rules,
2145 <programlisting>install :: $(HS_PROG)
2146 ...how to install it...</programlisting>
2148 <para>GNU <command>make</command> treats double-colon rules as
2149 separate entities. If there are several double-colon rules for
2150 the same target it takes each in turn and fires it if its
2151 dependencies say to do so. This means that you can, for
2152 example, define both <constant>HS_PROG</constant> and
2153 <constant>LIBRARY</constant>, which will generate two rules for
2154 <literal>install</literal>. When you type <command>make
2155 install</command> both rules will be fired, and both the program
2156 and the library will be installed, just as you wanted.</para>
2159 <sect2 id="sec-subdirs">
2160 <title>Recursion</title>
2161 <indexterm><primary>recursion, in makefiles</primary></indexterm>
2162 <indexterm><primary>Makefile, recursing into subdirectories</primary></indexterm>
2164 <para>In leaf <filename>Makefile</filename>s the variable
2165 <constant>SUBDIRS</constant><indexterm><primary>SUBDIRS</primary></indexterm>
2166 is undefined. In non-leaf <filename>Makefile</filename>s,
2167 <constant>SUBDIRS</constant> is set to the list of
2168 sub-directories that contain subordinate
2169 <filename>Makefile</filename>s. <emphasis>It is up to you to
2170 set <constant>SUBDIRS</constant> in the
2171 <filename>Makefile</filename>.</emphasis> There is no automation
2172 here—<constant>SUBDIRS</constant> is too important to
2175 <para>When <constant>SUBDIRS</constant> is defined,
2176 <filename>target.mk</filename> includes a rather neat rule for
2177 the standard targets (<xref linkend="sec-standard-targets"/> that
2178 simply invokes <command>make</command> recursively in each of
2179 the sub-directories.</para>
2181 <para><emphasis>These recursive invocations are guaranteed to
2182 occur in the order in which the list of directories is specified
2183 in <constant>SUBDIRS</constant>. </emphasis>This guarantee can
2184 be important. For example, when you say <command>make
2185 boot</command> it can be important that the recursive invocation
2186 of <command>make boot</command> is done in one sub-directory
2187 (the include files, say) before another (the source files).
2188 Generally, put the most independent sub-directory first, and the
2189 most dependent last.</para>
2192 <sect2 id="sec-ways">
2193 <title>Way management</title>
2194 <indexterm><primary>way management</primary></indexterm>
2196 <para>We sometimes want to build essentially the same system in
2197 several different “ways”. For example, we want to build GHC's
2198 <literal>Prelude</literal> libraries with and without profiling,
2199 so that there is an appropriately-built library archive to link
2200 with when the user compiles his program. It would be possible
2201 to have a completely separate build tree for each such “way”,
2202 but it would be horribly bureaucratic, especially since often
2203 only parts of the build tree need to be constructed in multiple
2207 <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>
2208 contains some clever magic to allow you to build several
2209 versions of a system; and to control locally how many versions
2210 are built and how they differ. This section explains the
2213 <para>The files for a particular way are distinguished by
2214 munging the suffix. The <quote>normal way</quote> is always
2215 built, and its files have the standard suffices
2216 <filename>.o</filename>, <filename>.hi</filename>, and so on.
2217 In addition, you can build one or more extra ways, each
2218 distinguished by a <emphasis>way tag</emphasis>. The object
2219 files and interface files for one of these extra ways are
2220 distinguished by their suffix. For example, way
2221 <literal>mp</literal> has files
2222 <filename>.mp_o</filename> and
2223 <filename>.mp_hi</filename>. Library archives have their
2224 way tag the other side of the dot, for boring reasons; thus,
2225 <filename>libHS_mp.a</filename>.</para>
2227 <para>A <command>make</command> variable called
2228 <constant>way</constant> holds the current way tag.
2229 <emphasis><constant>way</constant> is only ever set on the
2230 command line of <command>make</command></emphasis> (usually in
2231 a recursive invocation of <command>make</command> by the
2232 system). It is never set inside a
2233 <filename>Makefile</filename>. So it is a global constant for
2234 any one invocation of <command>make</command>. Two other
2235 <command>make</command> variables,
2236 <constant>way_</constant> and
2237 <constant>_way</constant> are immediately derived from
2238 <constant>$(way)</constant> and never altered. If
2239 <constant>way</constant> is not set, then neither are
2240 <constant>way_</constant> and
2241 <constant>_way</constant>, and the invocation of
2242 <command>make</command> will build the <quote>normal
2243 way</quote>. If <constant>way</constant> is set, then the other
2244 two variables are set in sympathy. For example, if
2245 <constant>$(way)</constant> is “<literal>mp</literal>”,
2246 then <constant>way_</constant> is set to
2247 “<literal>mp_</literal>” and
2248 <constant>_way</constant> is set to
2249 “<literal>_mp</literal>”. These three variables are
2250 then used when constructing file names.</para>
2252 <para>So how does <command>make</command> ever get recursively
2253 invoked with <constant>way</constant> set? There are two ways
2254 in which this happens:</para>
2258 <para>For some (but not all) of the standard targets, when
2259 in a leaf sub-directory, <command>make</command> is
2260 recursively invoked for each way tag in
2261 <constant>$(WAYS)</constant>. You set
2262 <constant>WAYS</constant> in the
2263 <filename>Makefile</filename> to the list of way tags you
2264 want these targets built for. The mechanism here is very
2265 much like the recursive invocation of
2266 <command>make</command> in sub-directories (<xref
2267 linkend="sec-subdirs"/>). It is up to you to set
2268 <constant>WAYS</constant> in your
2269 <filename>Makefile</filename>; this is how you control what
2270 ways will get built.</para>
2274 <para>For a useful collection of targets (such as
2275 <filename>libHS_mp.a</filename>,
2276 <filename>Foo.mp_o</filename>) there is a rule which
2277 recursively invokes <command>make</command> to make the
2278 specified target, setting the <constant>way</constant>
2279 variable. So if you say <command>make
2280 Foo.mp_o</command> you should see a recursive
2281 invocation <command>make Foo.mp_o way=mp</command>,
2282 and <emphasis>in this recursive invocation the pattern rule
2283 for compiling a Haskell file into a <filename>.o</filename>
2284 file will match</emphasis>. The key pattern rules (in
2285 <filename>suffix.mk</filename>) look like this:
2287 <programlisting>%.$(way_)o : %.lhs
2288 $(HC) $(HC_OPTS) $< -o $@</programlisting>
2294 <para>You can invoke <command>make</command> with a
2295 particular <literal>way</literal> setting yourself, in order
2296 to build files related to a particular
2297 <literal>way</literal> in the current directory. eg.
2299 <screen>$ make way=p</screen>
2301 will build files for the profiling way only in the current
2308 <title>When the canned rule isn't right</title>
2310 <para>Sometimes the canned rule just doesn't do the right thing.
2311 For example, in the <literal>nofib</literal> suite we want the
2312 link step to print out timing information. The thing to do here
2313 is <emphasis>not</emphasis> to define
2314 <constant>HS_PROG</constant> or
2315 <constant>C_PROG</constant>, and instead define a special
2316 purpose rule in your own <filename>Makefile</filename>. By
2317 using different variable names you will avoid the canned rules
2318 being included, and conflicting with yours.</para>
2322 <sect1 id="building-docs">
2323 <title>Building the documentation</title>
2325 <sect2 id="pre-supposed-doc-tools">
2326 <title>Tools for building the Documentation</title>
2328 <para>The following additional tools are required if you want to
2329 format the documentation that comes with the
2330 <literal>fptools</literal> projects:</para>
2335 <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
2336 <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
2339 <para>Much of our documentation is written in DocBook XML, instructions
2340 on installing and configuring the DocBook tools are below.</para>
2346 <indexterm><primary>pre-supposed: TeX</primary></indexterm>
2347 <indexterm><primary>TeX, pre-supposed</primary></indexterm>
2350 <para>A decent TeX distribution is required if you want to
2351 produce printable documentation. We recomment teTeX,
2352 which includes just about everything you need.</para>
2358 <indexterm><primary>Haddock</primary></indexterm>
2361 <para>Haddock is a Haskell documentation tool that we use
2362 for automatically generating documentation from the
2363 library source code. It is an <literal>fptools</literal>
2364 project in itself. To build documentation for the
2365 libraries (<literal>fptools/libraries</literal>) you
2366 should check out and build Haddock in
2367 <literal>fptools/haddock</literal>. Haddock requires GHC
2375 <title>Installing the DocBook tools</title>
2378 <title>Installing the DocBook tools on Linux</title>
2380 <para>If you're on a recent RedHat (7.0+) or SuSE (8.1+) system,
2381 you probably have working DocBook tools already installed. The
2382 configure script should detect your setup and you're away.</para>
2384 <para>If you don't have DocBook tools installed, and you are
2385 using a system that can handle RPM packages, you can use <ulink
2386 url="http://rpmfind.net/">Rpmfind.net</ulink> to find suitable
2387 packages for your system. Search for the packages
2388 <literal>docbook-dtd</literal>,
2389 <literal>docbook-xsl-stylesheets</literal>,
2390 <literal>libxslt</literal>,
2391 <literal>libxml2</literal>,
2392 <literal>fop</literal>,
2393 <literal>xmltex</literal>, and
2394 <literal>dvips</literal>.</para>
2398 <title>Installing DocBook on FreeBSD</title>
2400 <para>On FreeBSD systems, the easiest way to get DocBook up
2401 and running is to install it from the ports tree or a
2402 pre-compiled package (packages are available from your local
2403 FreeBSD mirror site).</para>
2405 <para>To use the ports tree, do this:
2406 <screen>$ cd /usr/ports/textproc/docproj
2407 $ make install</screen>
2408 This installs the FreeBSD documentation project tools, which
2409 includes everything needed to format the GHC
2410 documentation.</para>
2414 <title>Installing from binaries on Windows</title>
2416 <para>Probably the fastest route to a working DocBook environment on
2417 Windows is to install <ulink url="http://www.cygwin.com/">Cygwin</ulink>
2418 with the complete <literal>Doc</literal> category. If you are using
2419 <ulink url="http://www.mingw.org/">MinGW</ulink> for compilation, you
2420 have to help <command>configure</command> a little bit: Set the
2421 environment variables <envar>XmllintCmd</envar> and
2422 <envar>XsltprocCmd</envar> to the paths of the Cygwin executables
2423 <command>xmllint</command> and <command>xsltproc</command>,
2424 respectively, and set <envar>fp_cv_dir_docbook_xsl</envar> to the path
2425 of the directory where the XSL stylesheets are installed,
2426 e.g. <filename>c:/cygwin/usr/share/docbook-xsl</filename>.
2429 <para>If you want to build HTML Help, you have to install the
2430 <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp">HTML Help SDK</ulink>,
2431 too, and make sure that <command>hhc</command> is in your <envar>PATH</envar>.</para>
2437 <title>Configuring the DocBook tools</title>
2439 <para>Once the DocBook tools are installed, the configure script
2440 will detect them and set up the build system accordingly. If you
2441 have a system that isn't supported, let us know, and we'll try
2446 <title>Building the documentation</title>
2448 <para>To build documentation in a certain format, you can
2449 say, for example,</para>
2451 <screen>$ make html</screen>
2453 <para>to build HTML documentation below the current directory.
2454 The available formats are: <literal>dvi</literal>,
2455 <literal>ps</literal>, <literal>pdf</literal>,
2456 <literal>html</literal>, and <literal>rtf</literal>. Note that
2457 not all documentation can be built in all of these formats: HTML
2458 documentation is generally supported everywhere, and DocBook
2459 documentation might support the other formats (depending on what
2460 other tools you have installed).</para>
2462 <para>All of these targets are recursive; that is, saying
2463 <literal>make html</literal> will make HTML docs for all the
2464 documents recursively below the current directory.</para>
2466 <para>Because there are many different formats that the DocBook
2467 documentation can be generated in, you have to select which ones
2468 you want by setting the <literal>XMLDocWays</literal> variable
2469 to a list of them. For example, in
2470 <filename>build.mk</filename> you might have a line:</para>
2472 <screen>XMLDocWays = html ps</screen>
2474 <para>This will cause the documentation to be built in the requested
2475 formats as part of the main build (the default is not to build
2476 any documentation at all).</para>
2480 <title>Installing the documentation</title>
2482 <para>To install the documentation, use:</para>
2484 <screen>$ make install-docs</screen>
2486 <para>This will install the documentation into
2487 <literal>$(datadir)</literal> (which defaults to
2488 <literal>$(prefix)/share</literal>). The exception is HTML
2489 documentation, which goes into
2490 <literal>$(datadir)/html</literal>, to keep things tidy.</para>
2492 <para>Note that unless you set <literal>$(XMLDocWays)</literal>
2493 to a list of formats, the <literal>install-docs</literal> target
2494 won't do anything for DocBook XML documentation.</para>
2500 <sect1 id="sec-porting-ghc">
2501 <title>Porting GHC</title>
2503 <para>This section describes how to port GHC to a currenly
2504 unsupported platform. There are two distinct
2505 possibilities:</para>
2509 <para>The hardware architecture for your system is already
2510 supported by GHC, but you're running an OS that isn't
2511 supported (or perhaps has been supported in the past, but
2512 currently isn't). This is the easiest type of porting job,
2513 but it still requires some careful bootstrapping. Proceed to
2514 <xref linkend="sec-booting-from-hc"/>.</para>
2518 <para>Your system's hardware architecture isn't supported by
2519 GHC. This will be a more difficult port (though by comparison
2520 perhaps not as difficult as porting gcc). Proceed to <xref
2521 linkend="unregisterised-porting"/>.</para>
2525 <sect2 id="sec-booting-from-hc">
2526 <title>Booting/porting from C (<filename>.hc</filename>) files</title>
2528 <indexterm><primary>building GHC from .hc files</primary></indexterm>
2529 <indexterm><primary>booting GHC from .hc files</primary></indexterm>
2530 <indexterm><primary>porting GHC</primary></indexterm>
2532 <para>Bootstrapping GHC on a system without GHC already
2533 installed is achieved by taking the intermediate C files (known
2534 as HC files) from another GHC compilation, compiling them using gcc to
2535 get a working GHC.</para>
2537 <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
2538 from C. We recommend using GHC 6.0.1 or
2539 later.</emphasis></para>
2541 <para>HC files are platform-dependent, so you have to get a set
2542 that were generated on <emphasis>the same platform</emphasis>. There
2543 may be some supplied on the GHC download page, otherwise you'll have to
2544 compile some up yourself, or start from
2545 <emphasis>unregisterised</emphasis> HC files - see <xref
2546 linkend="unregisterised-porting"/>.</para>
2548 <para>The following steps should result in a working GHC build
2549 with full libraries:</para>
2553 <para>Unpack the HC files on top of a fresh source tree
2554 (make sure the source tree version matches the version of
2555 the HC files <emphasis>exactly</emphasis>!). This will
2556 place matching <filename>.hc</filename> files next to the
2557 corresponding Haskell source (<filename>.hs</filename> or
2558 <filename>.lhs</filename>) in the compiler subdirectory
2559 <filename>ghc/compiler</filename> and in the libraries
2561 <literal>libraries</literal>).</para>
2565 <para>The actual build process is fully automated by the
2566 <filename>hc-build</filename> script located in the
2567 <filename>distrib</filename> directory. If you eventually
2568 want to install GHC into the directory
2569 <replaceable>dir</replaceable>, the following
2570 command will execute the whole build process (it won't
2571 install yet):</para>
2573 <screen>$ distrib/hc-build --prefix=<replaceable>dir</replaceable></screen>
2574 <indexterm><primary>--hc-build</primary></indexterm>
2576 <para>By default, the installation directory is
2577 <filename>/usr/local</filename>. If that is what you want,
2578 you may omit the argument to <filename>hc-build</filename>.
2579 Generally, any option given to <filename>hc-build</filename>
2580 is passed through to the configuration script
2581 <filename>configure</filename>. If
2582 <filename>hc-build</filename> successfully completes the
2583 build process, you can install the resulting system, as
2586 <screen>$ make install</screen>
2591 <sect2 id="unregisterised-porting">
2592 <title>Porting GHC to a new architecture</title>
2594 <para>The first step in porting to a new architecture is to get
2595 an <firstterm>unregisterised</firstterm> build working. An
2596 unregisterised build is one that compiles via vanilla C only.
2597 By contrast, a registerised build uses the following
2598 architecture-specific hacks for speed:</para>
2602 <para>Global register variables: certain abstract machine
2603 <quote>registers</quote> are mapped to real machine
2604 registers, depending on how many machine registers are
2606 <filename>ghc/includes/MachRegs.h</filename>).</para>
2610 <para>Assembly-mangling: when compiling via C, we feed the
2611 assembly generated by gcc though a Perl script known as the
2612 <firstterm>mangler</firstterm> (see
2613 <filename>ghc/driver/mangler/ghc-asm.lprl</filename>). The
2614 mangler rearranges the assembly to support tail-calls and
2615 various other optimisations.</para>
2619 <para>In an unregisterised build, neither of these hacks are
2620 used — the idea is that the C code generated by the
2621 compiler should compile using gcc only. The lack of these
2622 optimisations costs about a factor of two in performance, but
2623 since unregisterised compilation is usually just a step on the
2624 way to a full registerised port, we don't mind too much.</para>
2626 <para>Notes on GHC portability in general: we've tried to stick
2627 to writing portable code in most parts of the system, so it
2628 should compile on any POSIXish system with gcc, but in our
2629 experience most systems differ from the standards in one way or
2630 another. Deal with any problems as they arise - if you get
2631 stuck, ask the experts on
2632 <email>glasgow-haskell-users@haskell.org</email>.</para>
2634 <para>Lots of useful information about the innards of GHC is
2635 available in the <ulink
2636 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2637 Commentary</ulink>, which might be helpful if you run into some
2638 code which needs tweaking for your system.</para>
2641 <title>Cross-compiling to produce an unregisterised GHC</title>
2643 <para>NOTE! These instructions apply to GHC 6.4 and (hopefully)
2644 later. If you need instructions for an earlier version of GHC, try
2645 to get hold of the version of this document that was current at the
2646 time. It should be available from the appropriate download page on
2648 url="http://www.haskell.org/ghc/">GHC homepage</ulink>.</para>
2650 <para>In this section, we explain how to bootstrap GHC on a
2651 new platform, using unregisterised intermediate C files. We
2652 haven't put a great deal of effort into automating this
2653 process, for two reasons: it is done very rarely, and the
2654 process usually requires human intervention to cope with minor
2655 porting issues anyway.</para>
2657 <para>The following step-by-step instructions should result in
2658 a fully working, albeit unregisterised, GHC. Firstly, you
2659 need a machine that already has a working GHC (we'll call this
2660 the <firstterm>host</firstterm> machine), in order to
2661 cross-compile the intermediate C files that we will use to
2662 bootstrap the compiler on the <firstterm>target</firstterm>
2667 <para>On the target machine:</para>
2671 <para>Unpack a source tree (preferably a released
2672 version). We will call the path to the root of this
2673 tree <replaceable>T</replaceable>.</para>
2677 <screen>$ cd <replaceable>T</replaceable>
2678 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised</screen>
2680 <para>You might need to update
2681 <filename>configure.in</filename> to recognise the new
2682 architecture, and re-generate
2683 <filename>configure</filename> with
2684 <literal>autoreconf</literal>.</para>
2688 <screen>$ cd <replaceable>T</replaceable>/ghc/includes
2695 <para>On the host machine:</para>
2699 <para>Unpack a source tree (same released version). Call
2700 this directory <replaceable>H</replaceable>.</para>
2704 <screen>$ cd <replaceable>H</replaceable>
2705 $ ./configure</screen>
2710 <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
2711 with the following contents:</para>
2713 <programlisting>GhcUnregisterised = YES
2714 GhcLibHcOpts = -O -fvia-C -keep-hc-files
2715 GhcRtsHcOpts = -keep-hc-files
2718 GhcWithNativeCodeGen = NO
2719 GhcWithInterpreter = NO
2720 GhcStage1HcOpts = -O
2721 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
2722 SRC_HC_OPTS += -H32m
2723 GhcBootLibs = YES</programlisting>
2728 <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
2731 <para>change <literal>TARGETPLATFORM</literal>
2732 appropriately, and set the variables involving
2733 <literal>TARGET</literal> or
2734 <literal>Target</literal> to the correct values for
2735 the target platform. This step is necessary because
2736 currently <literal>configure</literal> doesn't cope
2737 with specifying different values for the
2738 <literal>--host</literal> and
2739 <literal>--target</literal> flags.</para>
2742 <para>copy <literal>LeadingUnderscore</literal>
2743 setting from target.</para>
2750 <filename><replaceable>T</replaceable>/ghc/includes/ghcautoconf.h</filename>, <filename><replaceable>T</replaceable>/ghc/includes/DerivedConstants.h</filename>, and <filename><replaceable>T</replaceable>/ghc/includes/GHCConstants.h</filename>
2752 <filename><replaceable>H</replaceable>/ghc/includes</filename>.
2753 Note that we are building on the host machine, using the
2754 target machine's configuration files. This
2755 is so that the intermediate C files generated here will
2756 be suitable for compiling on the target system.</para>
2760 <para>Touch the generated configuration files, just to make
2761 sure they don't get replaced during the build:</para>
2762 <screen>$ cd <filename><replaceable>H</replaceable></filename>/ghc/includes
2763 $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
2764 $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
2766 <para>Note: it has been reported that these files still get
2767 overwritten during the next stage. We have installed a fix
2768 for this in GHC 6.4.2, but if you are building a version
2769 before that you need to watch out for these files getting
2770 overwritte by the <literal>Makefile</literal> in
2771 <literal>ghc/includes</literal>. If your system supports
2772 it, you might be able to prevent it by making them
2774 <screen>$ chflags uchg ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
2778 <para>Now build the compiler:</para>
2779 <screen>$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
2780 $ cd <replaceable>H</replaceable>/ghc && make boot && make</screen>
2781 <para>Don't worry if the build falls over in the RTS, we
2782 don't need the RTS yet.</para>
2786 <screen>$ cd <replaceable>H</replaceable>/libraries
2787 $ make boot && make</screen>
2791 <screen>$ cd <replaceable>H</replaceable>/ghc/compiler
2792 $ make boot stage=2 && make stage=2</screen>
2796 <screen>$ cd <replaceable>H</replaceable>/compat
2799 $ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
2800 $ cd <replaceable>H</replaceable>/ghc/utils
2802 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'</screen>
2806 <screen>$ cd <replaceable>H</replaceable>
2807 $ make hc-file-bundle Project=Ghc</screen>
2812 <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
2813 to <filename><replaceable>T</replaceable>/..</filename>.</para>
2819 <para>On the target machine:</para>
2821 <para>At this stage we simply need to bootstrap a compiler
2822 from the intermediate C files we generated above. The
2823 process of bootstrapping from C files is automated by the
2824 script in <literal>distrib/hc-build</literal>, and is
2825 described in <xref linkend="sec-booting-from-hc"/>.</para>
2827 <screen>$ ./distrib/hc-build --enable-hc-boot-unregisterised</screen>
2829 <para>However, since this is a bootstrap on a new machine,
2830 the automated process might not run to completion the
2831 first time. For that reason, you might want to treat the
2832 <literal>hc-build</literal> script as a list of
2833 instructions to follow, rather than as a fully automated
2834 script. This way you'll be able to restart the process
2835 part-way through if you need to fix anything on the
2838 <para>Don't bother with running
2839 <literal>make install</literal> in the newly
2840 bootstrapped tree; just use the compiler in that tree to
2841 build a fresh compiler from scratch, this time without
2842 booting from C files. Before doing this, you might want
2843 to check that the bootstrapped compiler is generating
2844 working binaries:</para>
2846 <screen>$ cat >hello.hs
2847 main = putStrLn "Hello World!\n"
2849 $ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
2851 Hello World!</screen>
2853 <para>Once you have the unregisterised compiler up and
2854 running, you can use it to start a registerised port. The
2855 following sections describe the various parts of the
2856 system that will need architecture-specific tweaks in
2857 order to get a registerised build going.</para>
2864 <title>Porting the RTS</title>
2866 <para>The following files need architecture-specific code for a
2867 registerised build:</para>
2871 <term><filename>ghc/includes/MachRegs.h</filename>
2872 <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
2875 <para>Defines the STG-register to machine-register
2876 mapping. You need to know your platform's C calling
2877 convention, and which registers are generally available
2878 for mapping to global register variables. There are
2879 plenty of useful comments in this file.</para>
2883 <term><filename>ghc/includes/TailCalls.h</filename>
2884 <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
2887 <para>Macros that cooperate with the mangler (see <xref
2888 linkend="sec-mangler"/>) to make proper tail-calls
2893 <term><filename>ghc/rts/Adjustor.c</filename>
2894 <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
2898 <literal>foreign import "wrapper"</literal>
2900 <literal>foreign export dynamic</literal>).
2901 Not essential for getting GHC bootstrapped, so this file
2902 can be deferred until later if necessary.</para>
2906 <term><filename>ghc/rts/StgCRun.c</filename>
2907 <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
2910 <para>The little assembly layer between the C world and
2911 the Haskell world. See the comments and code for the
2912 other architectures in this file for pointers.</para>
2916 <term><filename>ghc/rts/MBlock.h</filename>
2917 <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
2919 <term><filename>ghc/rts/MBlock.c</filename>
2920 <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
2923 <para>These files are really OS-specific rather than
2924 architecture-specific. In <filename>MBlock.h</filename>
2925 is specified the absolute location at which the RTS
2926 should try to allocate memory on your platform (try to
2927 find an area which doesn't conflict with code or dynamic
2928 libraries). In <filename>Mblock.c</filename> you might
2929 need to tweak the call to <literal>mmap()</literal> for
2936 <sect3 id="sec-mangler">
2937 <title>The mangler</title>
2939 <para>The mangler is an evil Perl-script
2940 (<filename>ghc/driver/mangler/ghc-asm.lprl</filename>) that
2941 rearranges the assembly code output from gcc to do two main
2946 <para>Remove function prologues and epilogues, and all
2947 movement of the C stack pointer. This is to support
2948 tail-calls: every code block in Haskell code ends in an
2949 explicit jump, so we don't want the C-stack overflowing
2950 while we're jumping around between code blocks.</para>
2953 <para>Move the <firstterm>info table</firstterm> for a
2954 closure next to the entry code for that closure. In
2955 unregisterised code, info tables contain a pointer to the
2956 entry code, but in registerised compilation we arrange
2957 that the info table is shoved right up against the entry
2958 code, and addressed backwards from the entry code pointer
2959 (this saves a word in the info table and an extra
2960 indirection when jumping to the closure entry
2965 <para>The mangler is abstracted to a certain extent over some
2966 architecture-specific things such as the particular assembler
2967 directives used to herald symbols. Take a look at the
2968 definitions for other architectures and use these as a
2969 starting point.</para>
2973 <title>The splitter</title>
2975 <para>The splitter is another evil Perl script
2976 (<filename>ghc/driver/split/ghc-split.lprl</filename>). It
2977 cooperates with the mangler to support object splitting.
2978 Object splitting is what happens when the
2979 <option>-split-objs</option> option is passed to GHC: the
2980 object file is split into many smaller objects. This feature
2981 is used when building libraries, so that a program statically
2982 linked against the library will pull in less of the
2985 <para>The splitter has some platform-specific stuff; take a
2986 look and tweak it for your system.</para>
2990 <title>The native code generator</title>
2992 <para>The native code generator isn't essential to getting a
2993 registerised build going, but it's a desirable thing to have
2994 because it can cut compilation times in half. The native code
2995 generator is described in some detail in the <ulink
2996 url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
2997 commentary</ulink>.</para>
3003 <para>To support GHCi, you need to port the dynamic linker
3004 (<filename>fptools/ghc/rts/Linker.c</filename>). The linker
3005 currently supports the ELF and PEi386 object file formats - if
3006 your platform uses one of these then things will be
3007 significantly easier. The majority of Unix platforms use the
3008 ELF format these days. Even so, there are some
3009 machine-specific parts of the ELF linker: for example, the
3010 code for resolving particular relocation types is
3011 machine-specific, so some porting of this code to your
3012 architecture will probaly be necessary.</para>
3014 <para>If your system uses a different object file format, then
3015 you have to write a linker — good luck!</para>
3021 <sect1 id="sec-build-pitfalls">
3022 <title>Known pitfalls in building Glasgow Haskell
3024 <indexterm><primary>problems, building</primary></indexterm>
3025 <indexterm><primary>pitfalls, in building</primary></indexterm>
3026 <indexterm><primary>building pitfalls</primary></indexterm></title>
3029 WARNINGS about pitfalls and known “problems”:
3038 One difficulty that comes up from time to time is running out of space
3039 in <literal>TMPDIR</literal>. (It is impossible for the configuration stuff to
3040 compensate for the vagaries of different sysadmin approaches to temp
3042 <indexterm><primary>tmp, running out of space in</primary></indexterm>
3044 The quickest way around it is <command>setenv TMPDIR /usr/tmp</command><indexterm><primary>TMPDIR</primary></indexterm> or
3045 even <command>setenv TMPDIR .</command> (or the equivalent incantation with your shell
3048 The best way around it is to say
3050 <programlisting>export TMPDIR=<dir></programlisting>
3052 in your <filename>build.mk</filename> file.
3053 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
3062 In compiling some support-code bits, e.g., in <filename>ghc/rts/gmp</filename> and even
3063 in <filename>ghc/lib</filename>, you may get a few C-compiler warnings. We think these
3071 When compiling via C, you'll sometimes get “warning: assignment from
3072 incompatible pointer type” out of GCC. Harmless.
3079 Similarly, <command>ar</command>chiving warning messages like the following are not
3082 <screen>ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
3083 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
3092 In compiling the compiler proper (in <filename>compiler/</filename>), you <emphasis>may</emphasis>
3093 get an “Out of heap space” error message. These can vary with the
3094 vagaries of different systems, it seems. The solution is simple:
3101 If you're compiling with GHC 4.00 or later, then the
3102 <emphasis>maximum</emphasis> heap size must have been reached. This
3103 is somewhat unlikely, since the maximum is set to 64M by default.
3104 Anyway, you can raise it with the
3105 <option>-optCrts-M<size></option> flag (add this flag to
3106 <constant><module>_HC_OPTS</constant>
3107 <command>make</command> variable in the appropriate
3108 <filename>Makefile</filename>).
3115 For GHC < 4.00, add a suitable <option>-H</option> flag to the <filename>Makefile</filename>, as
3124 and try again: <command>make</command>. (see <xref linkend="sec-suffix"/> for information about
3125 <constant><module>_HC_OPTS</constant>.)
3127 Alternatively, just cut to the chase:
3129 <screen>$ cd ghc/compiler
3130 $ make EXTRA_HC_OPTS=-optCrts-M128M</screen>
3138 If you try to compile some Haskell, and you get errors from GCC about
3139 lots of things from <filename>/usr/include/math.h</filename>, then your GCC was
3140 mis-installed. <command>fixincludes</command> wasn't run when it should've been.
3142 As <command>fixincludes</command> is now automagically run as part of GCC installation,
3143 this bug also suggests that you have an old GCC.
3151 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
3154 <screen>$ cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
3155 $ foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
3157 ? # or, on some machines: ar s $i
3161 We'd be interested to know if this is still necessary.
3169 GHC's sources go through <command>cpp</command> before being compiled, and <command>cpp</command> varies
3170 a bit from one Unix to another. One particular gotcha is macro calls
3174 <programlisting>SLIT("Hello, world")</programlisting>
3177 Some <command>cpp</command>s treat the comma inside the string as separating two macro
3178 arguments, so you get
3181 <screen>:731: macro `SLIT' used with too many (2) args</screen>
3184 Alas, <command>cpp</command> doesn't tell you the offending file!
3186 Workaround: don't put weird things in string args to <command>cpp</command> macros.
3197 <sect1 id="platforms"><title>Platforms, scripts, and file names</title>
3199 GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility
3200 gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
3203 <sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
3205 <para> The build system is built around Unix-y makefiles. Because it's not native,
3206 the Windows situation for building GHC is particularly confusing. This section
3207 tries to clarify, and to establish terminology.</para>
3209 <sect3 id="ghc-mingw"><title>MinGW</title>
3211 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink>
3212 is a collection of header
3213 files and import libraries that allow one to use <command>gcc</command> and produce
3214 native Win32 programs that do not rely on any third-party DLLs. The
3215 current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
3216 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
3220 <para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
3225 <sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
3227 <para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
3228 or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
3229 <command>ls</command>, nor build-system stuff such as <command>make</command> and <command>darcs</command>.
3230 For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink>
3231 and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
3235 Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
3236 compile code that has access to all of Posix. The price is that the executables must be
3237 dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
3238 that doesn't have Cygwin</emphasis>. Worse, Cygwin is a moving target. The name of the main DLL, <literal>cygwin1.dll</literal>
3239 does not change, but the implementation certainly does. Even the interfaces to functions
3240 it exports seem to change occasionally. </para>
3244 MSYS is a fork of the Cygwin tree, so they
3245 are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes
3246 through fewer layers, so MSYS is quite a bit faster too.
3249 <para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
3250 compile binaries that run with no DLL support, on any Win32 system.
3251 However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>,
3252 <command>darcs</command>, <command>ssh</command> etc. To get these, you have to download the
3253 MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
3255 <para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>,
3256 <command>ssh</command> and so on),
3257 not by programs compiled under MSYS.
3265 <sect3><title>Targeting MinGW</title>
3267 <para>We want GHC to compile programs that work on any Win32 system. Hence:
3270 GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
3271 invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles
3272 will work on any system, but it also means that the programs GHC compiles do not have access
3273 to all of Posix. In particular, they cannot import the (Haskell) Posix
3274 library; they have to do
3275 their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
3276 <para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
3280 To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
3281 <command>as</command>, <command>ld</command>, and a bunch of input/output libraries.
3284 So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
3285 It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>,
3286 that targets Cygwin instead. The up-side of GHC-cygwin is
3287 that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
3288 <emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
3291 <para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about
3292 how GHC is <emphasis>built</emphasis>. We use both MSYS and Cygwin as build environments for
3293 GHC; both work fine, though MSYS is rather lighter weight.</para>
3295 <para>In your build tree, you build a compiler called <command>ghc-inplace</command>. It
3296 uses the <command>gcc</command> that you specify using the
3297 <option>--with-gcc</option> flag when you run
3298 <command>configure</command> (see below).
3299 The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
3300 to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
3301 whatever one happens to be in your path. However, the makefiles do use whatever <command>ld</command>
3302 and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
3303 used to glom together .o files into a bigger .o file, or a .a file,
3304 so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
3305 Cygwin and MinGW use the same .o file format. So its ok.
3309 <sect3><title> File names </title>
3311 <para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
3315 MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
3316 <filename>/c/tmp/foo</filename> etc. The exact mount table is given in the doc subdirectory of the MSYS distribution.
3318 <para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
3319 directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line
3320 arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example,
3322 <programlisting>foogle -B/c/tmp/baz</programlisting>
3323 the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
3327 Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
3329 <para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
3335 <sect3><title>Crippled <command>ld</command></title>
3338 It turns out that on both Cygwin and MSYS, the <command>ld</command> has a
3339 limit of 32kbytes on its command line. Especially when using split object
3340 files, the make system can emit calls to <command>ld</command> with thousands
3341 of files on it. Then you may see something like this:
3343 (cd Graphics/Rendering/OpenGL/GL/QueryUtils_split && /mingw/bin/ld -r -x -o ../QueryUtils.o *.o)
3344 /bin/sh: /mingw/bin/ld: Invalid argument
3346 The solution is either to switch off object file splitting (set
3347 <option>SplitObjs</option> to <literal>NO</literal> in your
3348 <filename>build.mk</filename>),
3349 or to make the module smaller.
3353 <sect3><title>Host System vs Target System</title>
3356 In the source code you'll find various ifdefs looking like:
3357 <programlisting>#ifdef mingw32_HOST_OS
3359 #endif</programlisting>
3361 <programlisting>#ifdef mingw32_TARGET_OS
3363 #endif</programlisting>
3364 These macros are set by the configure script (via the file config.h).
3365 Which is which? The criterion is this. In the ifdefs in GHC's source code:
3368 <para>The "host" system is the one on which GHC itself will be run.</para>
3371 <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
3374 For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
3375 So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
3382 <sect2><title>Wrapper scripts</title>
3385 Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
3386 For <emphasis>installed</emphasis> programs, the strategy depends on the platform. We'll use
3387 GHC itself as an example:
3390 On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
3391 paths to the front of the source file <filename>ghc.sh</filename>,
3392 that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
3393 where to find its supporting files.
3397 On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
3398 native Windows shell <command>cmd</command> (e.g. limits on the length
3399 of the command line). So instead we invoke the GHC binary directly, with no -B flag.
3400 GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
3401 and from that figures out where the supporting files are.
3404 (You can find the layout of GHC's supporting files in the
3405 section "Layout of installed files" of Section 2 of the GHC user guide.)
3408 Things work differently for <emphasis>in-place</emphasis> execution, where you want to
3409 execute a program that has just been built in a build tree. The difference is that the
3410 layout of the supporting files is different.
3411 In this case, whether on Windows or Unix, we always use a shell script. This works OK
3412 on Windows because the script is executed by MSYS or Cygwin, which don't have the
3413 shortcomings of the native Windows <command>cmd</command> shell.
3420 <sect1 id="winbuild"><title>Instructions for building under Windows</title>
3423 This section gives detailed instructions for how to build
3424 GHC from source on your Windows machine. Similar instructions for
3425 installing and running GHC may be found in the user guide. In general,
3426 Win95/Win98 behave the same, and WinNT/Win2k behave the same.
3429 Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
3430 before reading section.
3431 You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC,
3432 but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
3435 <sect2 id="msys-install"><title>Installing and configuring MSYS</title>
3438 MSYS is a lightweight alternative to Cygwin.
3439 You don't need MSYS to <emphasis>use</emphasis> GHC,
3440 but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
3441 Here's how to install MSYS.
3444 Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and
3445 download the following (of course, the version numbers will differ):
3447 <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
3449 <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
3450 This provides <command>make</command>, <command>autoconf</command>,
3451 <command>ssh</command> and probably more besides.
3454 Run both executables (in the order given above) to install them. I put them in <literal>c:/msys</literal>
3458 Set the following environment variables
3460 <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> and
3461 <literal>c:/msys/1.0/local/bin</literal>
3462 to your path. (Of course, the version number may differ.)
3463 MSYS mounts the former as both <literal>/bin</literal> and
3464 <literal>/usr/bin</literal> and the latter as <literal>/usr/local/bin</literal>.
3467 <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
3468 This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
3471 <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
3474 <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>. Only necessary if
3478 <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>. (I'm not certain this is necessary for MSYS.)
3485 Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set. It's a bad bug
3486 that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
3487 causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
3488 file has too-liberal permissinos.
3493 <para>Here are some points to bear in mind when using MSYS:
3495 <listitem> <para> MSYS does some kind of special magic to binaries stored in
3496 <filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
3497 to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
3498 Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories:
3499 they fail in mysterious ways. However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
3500 which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
3502 <listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
3506 Win32 has a <command>find</command> command which is not the same as MSYS's find.
3507 You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
3508 before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant>
3509 environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant>
3510 variable. You can always invoke <command>find</command> with an absolute path, or rename it.
3514 MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal>
3515 will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>). Useful when you get a
3516 bzip'd dump.</para></listitem>
3522 <sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
3524 <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
3525 The installation process is straightforward; we install it in
3526 <filename>c:/cygwin</filename>.</para>
3528 You must install enough Cygwin <emphasis>packages</emphasis> to support
3529 building GHC. If you miss out any of these, strange things will happen to you. There are two ways to do this:
3531 <listitem><para>The direct, but laborious way is to
3532 select all of the following packages in the installation dialogue:
3533 <command>cvs</command>,
3534 <command>openssh</command>,
3535 <command>autoconf</command>,
3536 <command>binutils</command> (includes ld and (I think) ar),
3537 <command>gcc</command>,
3538 <command>flex</command>,
3539 <command>make</command>.
3540 To see thse packages,
3541 click on the "View" button in the "Select Packages"
3542 stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is
3543 "Category" isn't very helpful, and the "View" button is rather unobtrousive.
3547 <listitem><para>The clever way is to point the Cygwin installer at the
3548 <command>ghc-depends</command> package, which is kept at <ulink
3549 url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
3550 When the Cygwin installer asks you to "Choose a Download Site", choose one of
3552 offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
3553 "User URL" box and click "Add"; now two sites are selected. (The Cygwin
3554 installer remembers this for next time.)
3555 Click "Next".</para>
3556 <para>In the "Select Packages" dialogue box that follows, click the "+" sign by
3557 "Devel", scroll down to the end of the "Devel" packages, and choose
3558 <command>ghc-depends</command>.
3559 The package <command>ghc-depends</command> will not actually install anything itself,
3560 but forces additional packages to be added by the Cygwin installer.
3566 <para> Now set the following user environment variables:
3569 <listitem><para> Add <filename>c:/cygwin/bin</filename> and <filename>c:/cygwin/usr/bin</filename> to your
3570 <constant>PATH</constant></para></listitem>
3574 Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
3575 don't do this you get very weird messages when you type
3576 <command>make</command>, such as:
3577 <screen>/c: /c: No such file or directory</screen>
3581 <listitem><para> Set <constant>SHELL</constant> to
3582 <filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
3583 <constant>SHELL</constant> is what you get.
3586 <listitem><para> Set <constant>HOME</constant> to point to your
3587 home directory. This is where, for example,
3588 <command>bash</command> will look for your <filename>.bashrc</filename>
3589 file. Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
3594 <para>Here are some things to be aware of when using Cygwin:
3596 <listitem> <para>Cygwin doesn't deal well with filenames that include
3597 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
3601 <listitem> <para> Cygwin implements a symbolic link as a text file with some
3602 magical text in it. So other programs that don't use Cygwin's
3603 I/O libraries won't recognise such files as symlinks.
3604 In particular, programs compiled by GHC are meant to be runnable
3605 without having Cygwin, so they don't use the Cygwin library, so
3606 they don't recognise symlinks.
3610 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
3611 which apply to Cygwin too.
3616 Some script files used in the make system start with "<command>#!/bin/perl</command>",
3617 (and similarly for <command>sh</command>). Notice the hardwired path!
3618 So you need to ensure that your <filename>/bin</filename> directory has at least
3619 <command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
3620 All these come in Cygwin's <filename>bin</filename> directory, which you probably have
3621 installed as <filename>c:/cygwin/bin</filename>. By default Cygwin mounts "<filename>/</filename>" as
3622 <filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
3623 (You can discover where your Cygwin
3624 root directory <filename>/</filename> is by typing <command>mount</command>.)
3625 Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
3626 directory, there's no need to copy anything. If not, copy these binaries from the <filename>cygwin/bin</filename>
3627 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
3633 By default, cygwin provides the command shell <filename>ash</filename>
3634 as <filename>sh.exe</filename>. It seems to be fine now, but in the past we
3635 saw build-system problems that turned out to be due to bugs in <filename>ash</filename>
3636 (to do with quoting and length of command lines). On the other hand <filename>bash</filename> seems
3638 If this happens to you (which it shouldn't), in <filename>cygwin/bin</filename>
3639 remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
3640 and copy <filename>bash.exe</filename> to <filename>sh.exe</filename>.
3641 You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
3642 you can't rename a running program!
3651 <sect2 id="configure-ssh"><title>Configuring SSH</title>
3653 <para><command>ssh</command> comes with both Cygwin and MSYS.
3654 (Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
3655 in the Cygwin list of packages; or use the <command>ghc-depends</command>
3656 package -- see <xref linkend="install-cygwin"/>.)</para>
3658 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
3662 The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
3663 seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
3664 they ask for a password). To solve this, start up <filename>cmd.exe</filename>
3665 and run it as follows:
3666 <screen>c:\tmp> set CYGWIN32=tty
3667 c:\tmp> c:/user/local/bin/ssh-keygen1</screen> </para>
3670 <listitem><para> (Cygwin-only problem, I think.)
3671 <command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.
3672 To determine your home directory <command>ssh</command> first looks in
3673 <filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed). If there's an entry
3674 there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
3675 the setting of the environment variable $HOME</emphasis>. If the home directory is
3676 bogus, <command>ssh</command> fails horribly. The best way to see what is going on is to say
3677 <screen>ssh -v cvs.haskell.org</screen>
3678 which makes <command>ssh</command> print out information about its activity.
3680 <para> You can fix this problem, either by correcting the home-directory field in
3681 <filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
3682 you do that, <command>ssh</command> uses the $HOME environment variable instead.
3688 <para>To protect your
3689 <literal>.ssh</literal> from access by anyone else,
3690 right-click your <literal>.ssh</literal> directory, and
3691 select <literal>Properties</literal>. If you are not on
3692 the access control list, add yourself, and give yourself
3693 full permissions (the second panel). Remove everyone else
3694 from the access control list. Don't leave them there but
3695 deny them access, because 'they' may be a list that
3696 includes you!</para>
3700 <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
3701 you to have Unix permissions 600 (read/write for owner only)
3702 on the <literal>.ssh/identity</literal> file, else it
3703 bombs out. For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
3704 but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).
3705 The solution seems to be to set the $CYGWIN environment
3706 variable to "<literal>ntsec neta</literal>". The $CYGWIN environment variable is discussed
3707 in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
3708 and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
3715 <sect2><title>Other things you need to install</title>
3717 <para>You have to install the following other things to build GHC, listed below.</para>
3719 <para>On Windows you often install executables in directories with spaces, such as
3720 "<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't
3721 deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
3722 to put binaries for all tools in places with no spaces in their path.
3723 On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
3724 <filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>. But it doesn't matter,
3725 provided they are in your path.
3729 Install an executable GHC, from <ulink url="http://www.haskell.org/ghc">http://www.haskell.org/ghc</ulink>.
3730 This is what you will use to compile GHC. Add it in your
3731 <constant>PATH</constant>: the installer tells you the path element
3732 you need to add upon completion.
3738 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
3739 Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily
3740 build it from the source distribution using
3741 <screen>$ ./configure
3743 $ make install</screen>
3744 This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
3746 Make sure the installation directory is in your
3747 <constant>PATH</constant>.
3752 <para>Install an executable Alex. This can be done by building from the
3753 source distribution in the same way as Happy. Sources are
3754 available from <ulink
3755 url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
3759 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
3760 generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>).
3761 Just pick up a mingw bundle at
3762 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
3763 We install it in <filename>c:/mingw</filename>.
3766 <para><emphasis>On MSYS</emphasis>, add <literal>c:/mingw/bin</literal> to your PATH. MSYS does not provide <command>gcc</command>,
3767 <command>ld</command>, <command>ar</command>, and so on, because it just uses the MinGW ones. So you need them
3771 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your path.
3772 They are only going to get used by explicit access (via the --with-gcc flag you
3773 give to <command>configure</command> later). If you do add them to your path
3774 you are likely to get into a mess because their names overlap with Cygwin
3776 On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
3777 (and perhaps one or two other things) in your path. The Cygwin ones are fine,
3778 but you must have them; hence needing the Cygwin binutils package.
3784 <para>We use <command>emacs</command> a lot, so we install that too.
3785 When you are in <filename>fptools/ghc/compiler</filename>, you can use
3786 "<literal>make tags</literal>" to make a TAGS file for emacs. That uses the utility
3787 <filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
3788 The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
3789 The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
3790 so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
3795 <para>You might want to install GLUT in your MSYS/Cygwin
3796 installation, otherwise the GLUT package will not be built with
3801 <para> Finally, check out a copy of GHC sources from
3802 the darcs repository, following the instructions at <ulink url="http://hackage.haskell.org/trac/ghc/wiki/GhcDarcs" />.</para>
3808 <sect2><title>Building GHC</title>
3811 Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>);
3812 the bullets below only tell
3813 you about Windows-specific wrinkles.</para>
3817 If you used <command>autoconf</command> instead of <command>autoreconf</command>,
3818 you'll get an error when you run <filename>./configure</filename>:
3821 creating mk/config.h
3822 mk/config.h is unchanged
3824 running /bin/sh ./configure --cache-file=.././config.cache --srcdir=.
3825 ./configure: ./configure: No such file or directory
3826 configure: error: ./configure failed for ghc</screen>
3830 <listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
3831 read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake),
3833 <screen>/usr/bin/autoconf: cannot create configure: permission denied</screen>
3834 Solution: delete <filename>configure</filename> first.
3839 After <command>autoreconf</command> run <command>./configure</command> in
3840 <filename>fptools/</filename> thus:
3842 <screen>$ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc</screen>
3843 This is the point at which you specify that you are building GHC-mingw
3844 (see <xref linkend="ghc-mingw"/>). </para>
3846 <para> Both these options are important! It's possible to get into
3847 trouble using the wrong C compiler!</para>
3849 Furthermore, it's <emphasis>very important</emphasis> that you specify a
3850 full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
3851 uses this path to invoke <command>gcc</command>) is a MinGW program and won't
3852 understand a Cygwin path. For example, if you
3853 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
3854 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
3855 time it tries to invoke it. Worse, the failure comes with
3856 no error message whatsoever. GHC simply fails silently when first invoked,
3857 typically leaving you with this:
3858 <screen>make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
3859 ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O
3860 -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes
3861 -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return
3862 -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes
3863 -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS
3864 -optc-fomit-frame-pointer -O2 -static
3865 -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
3866 make[2]: *** [Adjustor.o] Error 1
3867 make[1]: *** [all] Error 1
3868 make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
3869 make: *** [all] Error 1</screen>
3874 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
3875 you'll have to do something more like:
3876 <screen>$ ./configure --with-gcc=...the Cygwin gcc...</screen>
3881 If you are paranoid, delete <filename>config.cache</filename> if it exists.
3882 This file occasionally remembers out-of-date configuration information, which
3883 can be really confusing.
3887 <listitem><para> You almost certainly want to set
3888 <programlisting>SplitObjs = NO</programlisting>
3889 in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
3890 This tells the build system not to split each library into a myriad of little object files, one
3891 for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows
3892 it dramatically increases the time taken to build the libraries in the first place.
3896 <listitem><para> Do not attempt to build the documentation.
3897 It needs all kinds of wierd Jade stuff that we haven't worked out for
3898 Win32.</para></listitem>
3903 <sect2><title>A Windows build log using Cygwin</title>
3905 <para>Here is a complete, from-scratch, log of all you need to build GHC using
3906 Cygwin, kindly provided by Claus Reinke. It does not discuss alternative
3907 choices, but it gives a single path that works.</para>
3908 <programlisting>- Install some editor (vim, emacs, whatever)
3910 - Install cygwin (http://www.cygwin.com)
3911 ; i used 1.5.16-1, installed in c:\cygwin
3913 Choose a Download Source:
3914 select 'download from internet';
3915 Select Root Install Directory:
3916 root dir: c:\cygwin;
3917 install for: all users;
3918 default file type: unix
3919 Select Local Package Directory
3920 choose a spare temporary home
3921 Select Your Internet Connection
3923 Choose a Download Site
3924 Choose your preferred main mirror and
3925 Add 'http://www.haskell.org/ghc/cygwin'
3927 In addition to 'Base' (default install),
3928 select 'Devel->ghc-depends'
3930 - Install mingw (http://www.mingw.org/)
3931 ; i used MinGW-3.1.0-1.exe
3932 ; installed in c:\mingw
3933 - you probably want to add GLUT
3934 ; (http://www.xmission.com/~nate/glut.html)
3935 ; i used glut-3.7.3-mingw32.tar
3937 - Get recent binary snapshot of ghc-6.4.1 for mingw
3938 ; (http://www.haskell.org/ghc/dist/stable/dist/)
3940 - add C:\ghc\ghc-6.4.1\bin to %PATH%
3941 (Start->Control Panel->System->Advanced->Environment Variables)
3943 - Get darcs version of ghc
3944 ; also, subscribe to cvs-all@haskell.org, or follow the mailing list
3945 ; archive, in case you checkout a version with problems
3946 ; http://www.haskell.org//pipermail/cvs-all/
3947 - mkdir c:/fptools; cd c:/fptools
3948 ; (or whereever you want your darcs tree to be)
3949 - darcs get http://darcs.haskell.org/ghc
3951 - chmod +x darcs-all
3954 - Build ghc, using cygwin and mingw, targetting mingw
3955 - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
3956 ; for haddock, alex, happy (*)
3957 - export PATH=/cygdrive/c/mingw/bin:$PATH
3958 ; without, we pick up some cygwin tools at best!
3959 - cd c:/fptools/fptools
3960 ; (if you aren't there already)
3962 - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
3963 ; we use cygwin, but build for windows
3964 - cp mk/build.mk.sample mk/build.mk
3966 add line: SplitObjs = NO
3967 (MSYS seems slow when there are zillions of object files)
3968 uncomment line: BuildFlavour = perf
3969 (or BuildFlavour = devel, if you are doing development)
3970 add line: BIN_DIST=1
3971 - make 2>&1 | tee make.log
3972 ; always useful to have a log around
3974 - Package up binary distribution
3975 - make binary-dist Project=Ghc 2>&1 | tee make-bin-dist.log
3976 ; always useful to have a log around
3978 - chmod +x ../distrib/prep-bin-dist-mingw
3979 ; if you're happy with the script's contents (*)
3980 - ../distrib/prep-bin-dist-mingw
3981 ; then tar up, unpack where wanted, and enjoy</programlisting>
projects / ghc-hetmet.git / blob